Connect MCP servers

Register a remote Model Context Protocol (MCP) server, call its tools over the API, and add it to an agent.

Central Hub stores the server's credentials encrypted and calls the server itself, so a client calls tools without holding the server's secret.

Endpoints

Every route selects the workspace with X-Space-Slug.

Requires names the MCP connections permission (mcp_connection:read, create, edit, delete).

Request fields

Register an MCP server

1. Optional: check the config first with POST /api/v1/mcp-connections/test/ and the same body. The response is {"ok": true, "tools": [...], "server_instructions": null}.

2. Register it. Central Hub connects, lists the tools and stores them in discovered_tools:

   curl -X POST "$CENTRAL_HUB_URL/api/v1/mcp-connections/" \
     -H "X-API-Key: $ALO_API_KEY" \
     -H "X-Space-Slug: $WORKSPACE_SLUG" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "Issues MCP",
       "url": "https://mcp.example.com/mcp",
       "auth_type": "bearer_token",
       "credentials": {"token": "…"}
     }'

3. Keep the id from the 201 response (abridged):

   {
     "id": 62,
     "name": "Issues MCP",
     "url": "https://mcp.example.com/mcp",
     "transport": "streamable_http",
     "auth_type": "bearer_token",
     "credentials": {"token": "[REDACTED]"},
     "scope_visibility": "private",
     "discovered_tools": [
       {
         "name": "search_issues",
         "title": null,
         "description": "Search issues by text.",
         "input_schema": {
           "type": "object",
           "required": ["query"],
           "properties": {"query": {"type": "string"}, "limit": {"type": "integer", "default": 5}}
         }
       }
     ],
     "last_error": null,
     "user_authenticated": true
   }

If the server cannot be reached or refuses the credentials, nothing is saved and the response is 422 with the reason.

Connect an OAuth server

An oauth2 server is saved without tools; each user then signs in with their own account.

1. Register it with "auth_type": "oauth2". discovered_tools is [] and user_authenticated is false.

2. Start your sign-in:

   curl -X POST "$CENTRAL_HUB_URL/api/v1/mcp-connections/63/authenticate/init/" \
     -H "X-API-Key: $ALO_API_KEY" \
     -H "X-Space-Slug: $WORKSPACE_SLUG" \
     -H "Content-Type: application/json" \
     -d '{"redirect_uri": "https://your-app.example.com/oauth/callback"}'

3. Send the user to the returned auth_url. When the server redirects back, send its code and state to POST …/mcp-connections/63/authenticate/callback/; the response is the auth status with authenticated: true.

4. Fill discovered_tools with POST …/mcp-connections/63/refresh-tools/.

To sign in before the connection exists, send {url, redirect_uri} to POST /api/v1/mcp-connections/authenticate/init/, then {code, state} to POST /api/v1/mcp-connections/authenticate/callback/; pass the returned handle as oauth_handle when you register the server.

Connect a server from the catalog

GET /api/v1/mcp-connections/catalog/ lists the ready-made servers the Connectors page offers:

[
  {
    "key": "intercom_eu",
    "name": "Intercom (EU)",
    "description": "Search conversations, contacts and Help Center articles.",
    "url": "https://mcp.eu.intercom.com/mcp",
    "auth_type": "bearer_token",
    "logo_url": "/images/mcp-catalog/intercom_eu.png",
    "docs_url": "https://developers.intercom.com/docs/guides/mcp"
  }
]

To connect one, register it with its name, url and auth_type, connector_key set to its key, and the credentials that auth_type needs. For oauth2, sign in first and pass oauth_handle.

Call a tool

1. Read the connection and pick a tool:

   curl "$CENTRAL_HUB_URL/api/v1/mcp-connections/62/" \
     -H "X-API-Key: $ALO_API_KEY" \
     -H "X-Space-Slug: $WORKSPACE_SLUG"

   Each discovered_tools[].input_schema is what arguments must satisfy. If the list is empty or stale, send POST …/mcp-connections/62/refresh-tools/.

2. Call it. arguments is optional and defaults to {}:

   curl -X POST "$CENTRAL_HUB_URL/api/v1/mcp-connections/62/call/" \
     -H "X-API-Key: $ALO_API_KEY" \
     -H "X-Space-Slug: $WORKSPACE_SLUG" \
     -H "Content-Type: application/json" \
     -d '{"tool_name": "search_issues", "arguments": {"query": "renewal"}}'

3. Read result, the tool's output:

   {"result": {"issues": [{"id": "ISS-1", "title": "Renewal overdue (renewal)"}]}}

Rotate credentials

1. Send the new credentials to PATCH /api/v1/mcp-connections/{connection_id}/. They merge into the stored ones:

   curl -X PATCH "$CENTRAL_HUB_URL/api/v1/mcp-connections/62/" \
     -H "X-API-Key: $ALO_API_KEY" \
     -H "X-Space-Slug: $WORKSPACE_SLUG" \
     -H "Content-Type: application/json" \
     -d '{"credentials": {"token": "…"}}'

2. A change to url, transport, auth_type or credentials reconnects and refreshes discovered_tools; if that fails, the response is 422 and nothing changes.

Add an MCP server to an agent

• On every run: add the connection ID to the agent's enabled_mcp_connection_ids, with PATCH /api/v1/agents-v2/agents/{agent_id}/ or in a bundle's agent.yaml, as in Create and configure an agent.
• For one run: pass it in forwardedProps.runtimeConfig.mcp_connection_ids; see Run an agent and stream its events.

Troubleshooting