MCP Interface
MCP Interface
How AI agents connect to Octopus, discover tools by meaning, and execute actions across namespaced domains.
AI Agent → MCP Protocol → Octopus → External APIs
What & Why
MCP (Model Context Protocol) makes Octopus natively usable by AI agents without any prompt engineering for API calls. Instead of telling an agent "to create a GitHub issue, POST to /github/issues with these headers and this JSON schema", an agent simply connects to an MCP endpoint and discovers what is possible.
Three key advantages:
- Semantic discovery. Agents find tools by describing what they need in natural language (
tools/search), not by memorizing URL paths. The server ranks and returns the most relevant tools. - Domain namespacing. An agent connected to
/mcp/engineeringcan only see engineering tools. An agent connected to/mcp/financecan only see billing tools. This is access control built into the protocol layer. - Standard protocol. Any MCP-compatible agent (Claude Desktop, GPT-4 via MCP adapters, LangChain, custom agents) works out of the box. No Octopus-specific SDK needed.
The MCP server runs on port 3007 — the same port as the HTTP API — so no additional infrastructure is required. Tool names use double-underscore namespacing (github__create_issue) to keep them unambiguous across domains.
Tool Discovery vs Direct Call
Two paths an agent can take when it wants to accomplish something:
Path A — Semantic Discovery
Path B — Direct Call
When to use: Agent has previously called tools/list or already has the tool name cached. Avoids the search round-trip.
Domain Access Control
Each domain endpoint exposes only the tools registered to that domain. An agent connected to /mcp/engineering cannot discover or call finance tools — they are simply absent from its tool list.
Custom domains are configurable. Any domain name maps to an arbitrary set of tool tags. Add a new domain in the Octopus config to create a scoped tool namespace for a new agent role or team.
Reference
MCP Endpoints
| Endpoint | Method | Description |
|---|---|---|
/mcp/{domain} | GET | Open SSE connection — agent receives server hello and session ID |
/mcp/{domain} | POST | Send a single HTTP request (streamable HTTP transport) |
tools/list | MCP op | List all tools available in this domain |
tools/search | MCP op | Semantic search across tool descriptions |
tools/call | MCP op | Execute a tool by name with arguments |
Available domains: engineering, communication, knowledge, finance (custom domains configurable)
Tool Call Format
{
"tool": "github__create_issue",
"arguments": {
"owner": "acme-corp",
"repo": "backend-service",
"title": "Fix memory leak in worker pool",
"body": "Observed in production — worker memory grows unbounded after 24h uptime.",
"labels": ["bug", "priority-high"]
}
}
Tool names follow the pattern {service}__{action}. Double underscores separate the integration name from the action verb.
Authentication
Bearer token in the Authorization header — same credential used for the HTTP API:
Authorization: Bearer <your-api-key>
No separate MCP authentication. If the bearer token is valid, the agent has access to all tools in the requested domain.
Claude Desktop Configuration
To connect Claude Desktop to Octopus, add this block to your claude_desktop_config.json:
{
"mcpServers": {
"octopus-engineering": {
"command": "npx",
"args": [
"mcp-remote",
"http://localhost:3007/mcp/engineering",
"--header",
"Authorization: Bearer YOUR_API_KEY"
]
},
"octopus-communication": {
"command": "npx",
"args": [
"mcp-remote",
"http://localhost:3007/mcp/communication",
"--header",
"Authorization: Bearer YOUR_API_KEY"
]
}
}
}
You can add one entry per domain to give Claude access to specific tool sets. Restart Claude Desktop after saving.
Domain Configuration
Domains and their tool mappings are defined in the Octopus configuration. Each tool is tagged with one or more domain labels via the @service_method decorator:
@service_method(
name="create_issue",
description="Create a GitHub issue in a repository",
domains=["engineering"],
)
async def create_issue(self, owner: str, repo: str, title: str, body: str = "") -> dict:
...
An agent connecting to /mcp/engineering will see github__create_issue in its tool list. An agent connecting to /mcp/communication will not.
Custom domain example — add a recruiting domain in config and tag relevant tools:
domains=["engineering", "recruiting"]
The tool then appears in both /mcp/engineering and /mcp/recruiting.