openapi: 3.0.0 info: title: Public Agents MCP API version: 1.0.0 servers: - url: https://api.gumloop.com/api/v1 tags: - name: MCP paths: /mcp/servers: get: summary: List MCP servers description: Return the catalog of MCP servers visible to the caller — Gumloop-hosted (`gumcp_server`), user-deployed Gumstack (`gumstack_server`), and custom (`mcp_server`) — along with each server's connection state. operationId: listMcpServers tags: - MCP x-codeSamples: - lang: bash label: cURL source: "curl 'https://api.gumloop.com/api/v1/mcp/servers?team_id=YOUR_TEAM_ID' \\\n -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'\n" - lang: python label: Python source: "from gumloop import Gumloop\n\nclient = Gumloop(access_token=\"YOUR_ACCESS_TOKEN\")\n\nresponse = client.mcp.list_servers(team_id=\"YOUR_TEAM_ID\")\nfor server in response.servers:\n print(server.server_id, server.status)\n" parameters: - in: query name: team_id required: false schema: type: string description: Scope the catalog to a single team. When omitted, returns servers visible to the authenticated user. responses: '200': description: MCP servers visible to the caller. content: application/json: schema: type: object properties: servers: type: array items: type: object required: - server_id - type - status - gumloop_auth_url properties: server_id: type: string description: Stable identifier for the server. example: gumloop_slack name: type: string nullable: true example: Slack type: type: string description: One of `gumcp_server`, `gumstack_server`, or `mcp_server`. example: gumcp_server status: type: string description: Connection state. `connected` means the server is ready to accept tool calls; other values (for example `unauthenticated`, `blocked`) indicate the user must complete OAuth or the server is otherwise unavailable. example: connected icon_url: type: string nullable: true example: https://www.gumloop.com/icons/slack.png description: type: string nullable: true example: Send and read Slack messages. gumloop_auth_url: type: string description: URL the user should visit to connect or reauthorize this server. example: https://www.gumloop.com/oauth/connect/slack mcp_url: type: string nullable: true description: For `mcp_server` (custom) and `gumstack_server` entries, the upstream MCP URL. `null` for Gumloop-hosted servers. example: null tool_count: type: integer nullable: true example: 12 allowed_tool_call_ids: type: array nullable: true description: Populated only by the retrieve endpoint. Always `null` here. items: type: string example: null examples: multiple: summary: Mixed connection states value: servers: - server_id: gumloop_slack name: Slack type: gumcp_server status: connected icon_url: https://www.gumloop.com/icons/slack.png description: Send and read Slack messages. gumloop_auth_url: https://www.gumloop.com/oauth/connect/slack mcp_url: null tool_count: 12 allowed_tool_call_ids: null - server_id: gumloop_linear name: Linear type: gumcp_server status: unauthenticated icon_url: https://www.gumloop.com/icons/linear.png description: Read and create Linear issues. gumloop_auth_url: https://www.gumloop.com/oauth/connect/linear mcp_url: null tool_count: 8 allowed_tool_call_ids: null '401': description: Unauthorized — missing or invalid API key. '403': description: Forbidden — the caller does not have agent access on the requested team. '500': description: Internal server error. security: - bearerAuth: [] /mcp/servers/{server_id}: get: summary: Retrieve an MCP server description: Return a single MCP server. The response populates `allowed_tool_call_ids` with the tool call IDs the caller is permitted to invoke on this server. operationId: retrieveMcpServer tags: - MCP x-codeSamples: - lang: bash label: cURL source: "curl 'https://api.gumloop.com/api/v1/mcp/servers/gumloop_slack?team_id=YOUR_TEAM_ID' \\\n -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'\n" - lang: python label: Python source: 'from gumloop import Gumloop client = Gumloop(access_token="YOUR_ACCESS_TOKEN") response = client.mcp.get_server("gumloop_slack", team_id="YOUR_TEAM_ID") print(response.server.status, response.server.allowed_tool_call_ids) ' parameters: - in: path name: server_id required: true schema: type: string description: Identifier of the MCP server to retrieve. - in: query name: team_id required: false schema: type: string description: Scope the lookup to a single team. responses: '200': description: The requested MCP server. content: application/json: schema: type: object properties: server: type: object required: - server_id - type - status - gumloop_auth_url properties: server_id: type: string example: gumloop_slack name: type: string nullable: true example: Slack type: type: string description: One of `gumcp_server`, `gumstack_server`, or `mcp_server`. example: gumcp_server status: type: string example: connected icon_url: type: string nullable: true example: https://www.gumloop.com/icons/slack.png description: type: string nullable: true example: Send and read Slack messages. gumloop_auth_url: type: string example: https://www.gumloop.com/oauth/connect/slack mcp_url: type: string nullable: true example: null tool_count: type: integer nullable: true example: 12 allowed_tool_call_ids: type: array nullable: true description: Tool call IDs the caller is permitted to invoke on this server, after RBAC and policy checks. items: type: string example: - gumloop_slack__slack_send_message - gumloop_slack__slack_list_channels examples: connected: summary: Connected server value: server: server_id: gumloop_slack name: Slack type: gumcp_server status: connected icon_url: https://www.gumloop.com/icons/slack.png description: Send and read Slack messages. gumloop_auth_url: https://www.gumloop.com/oauth/connect/slack mcp_url: null tool_count: 12 allowed_tool_call_ids: - gumloop_slack__slack_send_message - gumloop_slack__slack_list_channels '401': description: Unauthorized — missing or invalid API key. '403': description: Forbidden — the caller does not have agent access on the requested team. '404': description: MCP server not found. '500': description: Internal server error. security: - bearerAuth: [] /mcp/servers/{server_id}/tools: get: summary: List MCP server tools description: Return the tools exposed by an MCP server. When the server is not in `connected` state, `tools` is empty and `gumloop_auth_url` is returned so the caller can prompt the user to authenticate. operationId: listMcpServerTools tags: - MCP x-codeSamples: - lang: bash label: cURL source: "curl 'https://api.gumloop.com/api/v1/mcp/servers/gumloop_slack/tools?team_id=YOUR_TEAM_ID' \\\n -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'\n" - lang: python label: Python source: "from gumloop import Gumloop\n\nclient = Gumloop(access_token=\"YOUR_ACCESS_TOKEN\")\n\nresponse = client.mcp.list_tools(\"gumloop_slack\", team_id=\"YOUR_TEAM_ID\")\nfor tool in response.tools:\n print(tool.tool_call_id, tool.name)\n" parameters: - in: path name: server_id required: true schema: type: string description: Identifier of the MCP server. - in: query name: team_id required: false schema: type: string description: Scope the lookup to a single team. responses: '200': description: Tools available on the server, plus the server's connection state. content: application/json: schema: type: object properties: tools: type: array items: type: object required: - tool_call_id - name properties: tool_call_id: type: string description: Composite identifier used to route tool calls — `"{server_id}__{tool_name}"`. Pass `server_id` and `tool_name` separately to `POST /mcp/tools/call`. example: gumloop_slack__slack_send_message name: type: string example: slack_send_message description: type: string nullable: true example: Send a message to a Slack channel. input_schema: type: object description: JSON Schema describing the tool's arguments. Defaults to `{}` when the upstream server does not advertise a schema. example: type: object properties: channel: type: string text: type: string required: - channel - text server_id: type: string nullable: true example: gumloop_slack server_type: type: string nullable: true example: gumcp_server server: type: object description: Server metadata snapshot. Defaults to `{}`. example: {} server_id: type: string nullable: true example: gumloop_slack status: type: string nullable: true example: connected gumloop_auth_url: type: string nullable: true example: https://www.gumloop.com/oauth/connect/slack examples: connected: summary: Connected server value: tools: - tool_call_id: gumloop_slack__slack_send_message name: slack_send_message description: Send a message to a Slack channel. input_schema: type: object properties: channel: type: string text: type: string required: - channel - text server_id: gumloop_slack server_type: gumcp_server server: {} server_id: gumloop_slack status: connected gumloop_auth_url: https://www.gumloop.com/oauth/connect/slack unauthenticated: summary: Server not yet connected value: tools: [] server_id: gumloop_slack status: unauthenticated gumloop_auth_url: https://www.gumloop.com/oauth/connect/slack '401': description: Unauthorized — missing or invalid API key. '403': description: Forbidden — the caller does not have agent access on the requested team. '404': description: MCP server not found. '500': description: Internal server error. security: - bearerAuth: [] /mcp/tools/call: post: summary: Call MCP tools description: Execute a batch of 1–5 MCP tool calls. Calls run concurrently and each result reports its own `status`. When Gumloop accepts the request, MCP execution failures such as target server authentication, policy blocks, invalid tools, upstream HTTP errors, and connection failures are returned in `results[*].status` and `results[*].error`. Top-level `4xx` responses are reserved for Gumloop request, authentication, and permission failures. `200` covers homogeneous execution outcomes (all calls succeeded or all calls failed); mixed success/failure batches return `207`. If you previously treated non-2xx HTTP statuses as MCP execution failures, update your integration to inspect each result's `status` and `error`. operationId: callMcpTools tags: - MCP x-codeSamples: - lang: bash label: cURL source: "curl 'https://api.gumloop.com/api/v1/mcp/tools/call' \\\n -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"team_id\": \"team_4f8c92ab\",\n \"calls\": [\n {\n \"ref\": \"send-1\",\n \"server_id\": \"gumloop_slack\",\n \"tool_name\": \"slack_send_message\",\n \"arguments\": {\"channel\": \"#general\", \"text\": \"Hello from Gumloop\"}\n }\n ]\n }'\n" - lang: python label: Python source: "from gumloop import Gumloop\n\nclient = Gumloop(access_token=\"YOUR_ACCESS_TOKEN\")\n\nresponse = client.mcp.execute(\n server_id=\"gumloop_slack\",\n tool_name=\"slack_send_message\",\n arguments={\"channel\": \"#general\", \"text\": \"Hello from Gumloop\"},\n ref=\"send-1\",\n team_id=\"team_4f8c92ab\",\n)\nfor result in response.results:\n print(result.ref, result.status)\n" requestBody: required: true content: application/json: schema: type: object required: - calls properties: calls: type: array minItems: 1 maxItems: 5 description: Tool calls to execute. Dispatched concurrently; the batch is capped at 5. items: type: object required: - server_id - tool_name properties: ref: type: string nullable: true description: Caller-supplied identifier echoed back on the matching result. When omitted, Gumloop assigns the call's zero-based index in `calls` as its `ref`. example: send-1 server_id: type: string example: gumloop_slack tool_name: type: string example: slack_send_message arguments: type: object description: Arguments passed to the tool. Defaults to `{}`. Validated by the tool's `input_schema`. example: channel: '#general' text: Hello from Gumloop team_id: type: string nullable: true description: Team the calls are scoped to. example: team_4f8c92ab responses: '200': description: Batch processed. Inspect each result's `status` and `error`; this can include all-success and all-failed execution outcomes. content: application/json: schema: type: object properties: results: type: array items: type: object required: - ref - status properties: ref: type: string example: send-1 server_id: type: string nullable: true example: gumloop_slack tool_name: type: string nullable: true example: slack_send_message status: type: string description: One of `success`, `unauthenticated`, or `error`. example: success content: type: array nullable: true description: Raw MCP content blocks returned by the tool when `status` is `success`. items: type: object example: - type: text text: 'Message sent to #general' error: type: object nullable: true description: Error payload when `status` is not `success`. Includes `code`, `message`, `type`, and optional `param` and `details`. example: null examples: success: summary: Single successful call value: results: - ref: send-1 server_id: gumloop_slack tool_name: slack_send_message status: success content: - type: text text: 'Message sent to #general' error: null execution_error: summary: Tool execution failed value: results: - ref: issue-1 server_id: gumloop_linear tool_name: linear_create_issue status: unauthenticated content: null error: code: auth_required message: Connect Linear before using this tool. type: permission_error param: tool_name details: server_id: gumloop_linear tool_name: linear_create_issue gumloop_auth_url: https://www.gumloop.com/oauth/connect/linear '207': description: Partial success — at least one call succeeded and at least one failed. Inspect each result's `status` and `error`. content: application/json: schema: type: object properties: results: type: array items: type: object examples: mixed: summary: One success, one needs authentication value: results: - ref: send-1 server_id: gumloop_slack tool_name: slack_send_message status: success content: - type: text text: 'Message sent to #general' error: null - ref: issue-1 server_id: gumloop_linear tool_name: linear_create_issue status: unauthenticated content: null error: code: auth_required message: Connect Linear before using this tool. type: permission_error param: tool_name details: server_id: gumloop_linear tool_name: linear_create_issue gumloop_auth_url: https://www.gumloop.com/oauth/connect/linear '400': description: Invalid Gumloop request body, for example fewer than 1 or more than 5 calls. '401': description: Unauthorized — missing or invalid Gumloop API credentials. '403': description: Forbidden — the caller lacks permission to use this Gumloop API endpoint or requested team scope. '500': description: Internal server error. security: - bearerAuth: [] components: securitySchemes: bearerAuth: type: http scheme: bearer description: A personal API key or an [OAuth 2.0](/api-reference/oauth) access token. Personal API keys also require the `x-auth-key` header with your user ID.