MCP connections

MCP connections expose tools from a remote Model Context Protocol server to an agent. Register the endpoint in Central Hub, test it to discover its tools, then attach its connection ID to enabled_mcp_connection_ids.

An MCP connection includes a URL, transport, authentication mode, encrypted credentials, and scope_visibility (private or space). Use the MCP endpoints to create, update, delete, test, and refresh discovered tools. Rotate credentials through the connection instead of embedding secrets in prompts or skills.

Authentication

Every MCP endpoint accepts an API key and selects a workspace with X-Space-Slug:

X-API-Key: sk-...
X-Space-Slug: acme-manufacturing

Endpoints

Method	URL	Purpose
`GET`	`/api/v1/mcp-connections/`	List the MCP connections the key can see
`GET`	`/api/v1/mcp-connections/{connection_id}/`	Read one connection, including its `discovered_tools`
`POST`	`/api/v1/mcp-connections/{connection_id}/call/`	Invoke a discovered tool and get its structured result
`POST`	`/api/v1/mcp-connections/{connection_id}/test/`	Re-test the endpoint and refresh discovered tools

Creating, updating, and deleting MCP connections is also available; those routes manage encrypted credentials and are typically driven from the UI.

List MCP connections

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

Each item includes id, name, and transport (for example streamable_http).

Inspect a connection's tools

A connection's callable tools live on the discovered_tools field of the single-connection read. Always inspect these before calling — each tool carries the input_schema your arguments must satisfy.

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

{
  "id": 5,
  "name": "EFG Jedify MCP",
  "transport": "streamable_http",
  "discovered_tools": [
    {
      "name": "search_issues",
      "description": "Search issues",
      "input_schema": {
        "type": "object",
        "properties": { "query": { "type": "string" } },
        "required": ["query"]
      }
    }
  ]
}

If discovered_tools is empty or stale, POST .../{connection_id}/test/ to re-probe the server and refresh the list.

Call a tool

Invoke a discovered tool server-side. The body names the tool and its arguments; the response's result is the tool's structured output.

curl -X POST "$CENTRAL_HUB_URL/api/v1/mcp-connections/5/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 overdue" }
  }'

Field	Type	Required	Notes
`tool_name`	string	yes	Must match a `name` from `discovered_tools`
`arguments`	object	yes	Must satisfy that tool's `input_schema` (may be `{}` if the schema takes no input)

The response is { "result": <tool output> }. Central Hub holds the encrypted credentials and performs the call on the server side, so no MCP secret ever passes through the client. An unknown tool_name or invalid arguments may come back as a server-side error payload rather than a hard HTTP error — check the tool's schema first, and only call tools that appear in discovered_tools.

Attach to an agent

To let an agent use these tools during a run, add the connection ID to the agent's enabled_mcp_connection_ids (see Create and configure an agent), or pass it per run via runtimeConfig.mcp_connection_ids (see Run and stream an agent).