---
title: "Discover Mcp Tools"
method: POST
path: "/agents/mcp/tools"
tags: ["Agents"]
---

# Discover Mcp Tools

`POST /agents/mcp/tools`

Discover available tools from an MCP server.

Three callable shapes - see ``DiscoverMcpToolsRequest`` docs for full details:

- **Saved-id:** ``{savedConnectionId}`` -> BE reads the stored row and
  composes headers server-side; the browser never sees the token.
  ``savedConnectionName`` is accepted as a deprecated alias for one
  release cycle.
- **Inline with masked secret:** ``{serverUrl, headers: {...: "********"}}`` ->
  BE matches the serverUrl against saved settings and substitutes the
  stored secret for every masked header value.
- **Inline plaintext:** ``{serverUrl, headers}`` - used on first-save
  "Test" click before the row exists.

URL is validated (SSRF guard) on every path. Per-tenant rate limit:
30 req/min -> 429 with ``Retry-After``. A 300s in-process cache (M10)
keyed by ``(serverUrl, headers-hash)`` short-circuits repeat calls;
``X-MCP-Cache: hit|miss`` is emitted on every response. Cache hits
still consume rate-limit budget - the cache is not a bypass.

## Request body

- DiscoverMcpToolsRequest — Request body for POST /agents/mcp/tools. Two callable shapes: 1. **Inline** - the caller sends ``{serverUrl, headers}`` directly. Used for the "Test" button on a new connection form before the row has been saved. If any header value is ``MASK_SENTINEL``, the BE substitutes the stored secret for that row (matched by ``serverUrl``) server-side so the decrypted value never reaches the browser. 2. **By saved-id** - the caller sends ``savedConnectionId`` and the BE reads the stored row from ``agent_connections`` and composes headers via ``mcp_header_resolver``. Used when the tenant triggers a re-discover against an existing saved connection - the browser doesn't need to hold the token at all. For MCP connections (which are keyed by ``name`` in storage), the value sent as ``savedConnectionId`` is the connection's stable ``name``. ``savedConnectionName`` is accepted as a deprecated alias for one release cycle so an in-flight FE that hasn't shipped the rename yet keeps working. New callers should send ``savedConnectionId``.
  - `serverUrl` string
  - `headers` object
  - `savedConnectionId` string, nullable — If set, BE resolves serverUrl + headers from the tenant's saved connection by id
  - `savedConnectionName` string, nullable — Deprecated - prefer ``savedConnectionId``. Accepted for backward compatibility for one release cycle.

## Response `200`

Successful Response

- object

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/streamkap/apis/streamkap-rest-api.md) · [All operations](https://skmtc.net/streamkap/apis/streamkap-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/streamkap/streamkap-rest-api/revisions/e9ce8221bac6/schema)