List MCP Server Tools

Connect to a registered MCP server and return the tools it exposes. This read has side effects: it opens a live connection to the third-party server and writes connectionStatus, toolCount, lastError, and lastToolsRefresh. A HEAD skips the effect but is authorized exactly as the GET is, so it answers 400, 401, 403, or 404 wherever the GET would and an empty 200 otherwise. Skipping the effect means skipping the read that produces the payload, so that 200 carries none of the response headers documented below — it answers whether the GET would be allowed, not what the GET would return. Discovery is bounded at 1,000 tools and 5 MB of tool payload per server. The bounded set is returned in one page; nextCursor is always null. An unreachable, slow, or cooling-down server is a 503; a stored OAuth grant that no longer works is a 409 with error.details.code MCP_SERVER_REAUTHORIZATION_REQUIRED, which only a human reauthorizing in Sim can clear. A workspace API key is rejected with 403; use a personal API key.

GET/api/v2/mcp-servers/{id}/tools

Authorization

apiKey
X-API-Key<token>

Your Sim API key, personal or workspace-scoped. Generate one under Settings, then API Keys. Operations that reject workspace keys say so in their own description.

In: header

Path Parameters

id*string

Unique MCP server identifier.

Length1 <= length

Query Parameters

workspaceId*string

Workspace that owns the MCP server.

Length1 <= length
refresh?boolean

Bypass the short-lived per-workspace tool cache and reconnect under your own credentials. A cached result reflects whichever workspace member last ran discovery, so this is the only way to pick up a tool added since then; it costs a live round trip.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://www.sim.ai/api/v2/mcp-servers/string/tools?workspaceId=string" \  -H "X-API-Key: YOUR_API_KEY"
{
  "data": [
    {
      "name": "search_docs",
      "description": "Search the internal documentation",
      "inputSchema": {
        "type": "object",
        "properties": {
          "query": {
            "type": "string",
            "description": "Search terms"
          }
        },
        "required": [
          "query"
        ]
      },
      "serverId": "mcp-3f7a9c21",
      "serverName": "Docs server"
    }
  ],
  "nextCursor": null
}
{
  "error": {
    "code": "BAD_REQUEST",
    "message": "The request is invalid."
  }
}
{
  "error": {
    "code": "BAD_REQUEST",
    "message": "The request is invalid."
  }
}
{
  "error": {
    "code": "BAD_REQUEST",
    "message": "The request is invalid."
  }
}
{
  "error": {
    "code": "BAD_REQUEST",
    "message": "The request is invalid."
  }
}
{
  "error": {
    "code": "BAD_REQUEST",
    "message": "The request is invalid."
  }
}
{
  "error": {
    "code": "BAD_REQUEST",
    "message": "The request is invalid."
  }
}
{
  "error": {
    "code": "BAD_REQUEST",
    "message": "The request is invalid."
  }
}
{
  "error": {
    "code": "BAD_REQUEST",
    "message": "The request is invalid."
  }
}