MCP Integration

Octipus can consume tools from external MCP servers. This is separate from the standalone MCP server, which exposes Octipus tools to other clients.

Connect a server

Use the MCP settings page or POST /api/mcp/servers. Supported bridge transports include stdio and legacy SSE. Example server entries:

{
  "id": "local-tools",
  "name": "Local tools",
  "transport": "stdio",
  "isEnabled": true,
  "command": "node",
  "args": ["/path/to/server.js"]
}

{
  "id": "remote-tools",
  "name": "Remote tools",
  "transport": "sse",
  "isEnabled": true,
  "sseUrl": "https://tools.example.com/sse",
  "postUrl": "https://tools.example.com/messages"
}

Use the external server’s actual protocol and authentication configuration; a generic HTTP URL is not necessarily an SSE endpoint. Stdio servers run as local subprocesses and need installed executables and suitable permissions.

Discovery and execution

Agents with the mcp tool discover schemas through mcp_list_tools and call mcp_call_tool. The general root has MCP access. Discovery is separate from authorization: outbound calls are checked at the bridge using tool ID mcp and action <serverId>.<remoteToolName>. Unattended ASK blocks; attended descendants can use session approvals. Old overrides using mcp:<serverId> must be reviewed and recreated under the canonical identity.

The bridge’s permission checks govern dispatch, not the external server’s internal actions or isolation. Review the credentials and capabilities exposed by each server.

Inspect and recover

• GET /api/mcp/servers lists connection status; /api/mcp/tools lists discovered tools.
• Connect/disconnect with POST /api/mcp/servers/:id/connect or /disconnect.
• Admins inspect /api/mcp/circuit and reset a breaker through POST /api/mcp/circuit/:serverId/reset after fixing the underlying failure.

A stale schema, failed connection, permission block, and external tool error need different fixes; read the reported failure rather than assuming discovery implies a working tool.