Gumloop MCP API
The MCP API from Gumloop — 4 operation(s) for mcp.
OpenAPI Specification
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.