MCP Protocol
MCP Protocol
Model Context Protocol turns every Octopus integration into an AI-callable tool.
AI Agent → Octopus MCP Server → External APIs
Model Context Protocol turns every Octopus integration into an AI-callable tool
+more
What is MCP and Why Does It Matter?
MCP (Model Context Protocol) is Anthropic's open standard for connecting AI agents to external tools. Octopus implements an MCP server so any MCP-compatible AI agent — Claude, GPT-4, or a custom LLM — can discover and call Octopus integrations without knowing the underlying REST API signatures.
What changes for AI agents:
| Without MCP | With MCP |
|---|---|
| Agent must know exact endpoint URLs | Agent discovers tools by name |
| Agent must know precise parameter schemas | Agent reads inputSchema from tool registry |
| No natural language discovery | Agent searches tools by natural language query |
| No audit trail for AI decisions | Every tool call traced in Sagittarius |
The key shift: Octopus stops being a REST API you call and becomes a tool platform the AI explores autonomously.
Detail Diagram: Tool Registration Flow
Every @service_method-decorated method in a service class is automatically registered as an MCP tool at startup:
def create_issue(
owner: str,
repo: str,
title: str
):
"""Create a GitHub issue."""
"name": "github:create_issue",
"description": "Create a GitHub issue.",
"inputSchema": {
"type": "object",
"properties": {
"owner": {"type":"string"},
"repo": {"type":"string"},
"title": {"type":"string"}
}
}
}
Tool name format: service:method · inputSchema auto-generated from Python type hints · description from docstring
Detail Diagram: Semantic Tool Search
AI agents can discover tools using natural language. Octopus embeds all tool descriptions with sentence-transformers and finds the most relevant tools by cosine similarity:
Embeddings are pre-computed at startup and cached. Search latency is typically <50 ms.
Execution Flow
When an AI agent calls POST /mcp/{domain}/execute, the executor runs five steps:
Reference
Endpoints
| Method | Path | Description |
|---|---|---|
GET | /mcp/{domain}/tools | List all tools available in a domain. Optional ?query= for semantic ranking. |
POST | /mcp/{domain}/tools/search | Semantic search over tool descriptions. Returns tools ranked by relevance. |
POST | /mcp/{domain}/execute | Execute a tool by name with JSON arguments. |
GET | /mcp/{domain}/resources | List resources available to the agent in this domain. |
GET | /mcp/domains | List all available domains with descriptions. |
GET | /mcp/schema | Full ontology schema — domains, concepts, providers. |
Available domains: engineering, documentation, work, communication, analytics
Tool Schema Format
Every tool returned by GET /mcp/{domain}/tools has this structure:
{
"name": "github:create_issue",
"description": "Create a new issue in a GitHub repository.",
"inputSchema": {
"type": "object",
"properties": {
"owner": {
"type": "string",
"description": "Repository owner (GitHub username or org)"
},
"repo": {
"type": "string",
"description": "Repository name"
},
"title": {
"type": "string",
"description": "Issue title"
},
"body": {
"type": "string",
"description": "Issue body (markdown supported)"
}
},
"required": ["owner", "repo", "title"]
},
"llm_hints": {
"aliases": ["open an issue", "file a bug"],
"when_to_use": "When the user wants to report a bug or request a feature on GitHub.",
"not_for": "Jira tickets — use jira:create_issue instead.",
"examples": [
{
"query": "open a bug report in my-org/api-service",
"arguments": {"owner": "my-org", "repo": "api-service", "title": "Bug: ..."}
}
]
}
}
Example: Discover and Call a Tool
Step 1 — Semantic search to find the right tool:
curl -X GET "https://api.example.com/mcp/engineering/tools?query=create+a+GitHub+issue" \
-H "Access-Token: <your-jwt>"
Response (top result):
{
"tools": [
{
"name": "github:create_issue",
"description": "Create a new issue in a GitHub repository.",
"inputSchema": { "..." : "..." }
}
]
}
Step 2 — Execute the tool:
curl -X POST "https://api.example.com/mcp/engineering/execute" \
-H "Access-Token: <your-jwt>" \
-H "Content-Type: application/json" \
-d '{
"tool": "github:create_issue",
"arguments": {
"owner": "my-org",
"repo": "api-service",
"title": "Bug: timeout on /v1/search endpoint",
"body": "Observed 30s timeouts under high load."
}
}'
Response:
{
"success": true,
"data": {
"id": 1234,
"number": 42,
"title": "Bug: timeout on /v1/search endpoint",
"url": "https://github.com/my-org/api-service/issues/42",
"state": "open"
},
"meta": {
"tool": "github:create_issue",
"trace_id": "sag-abc123",
"duration_ms": 312
}
}
Connecting an AI Agent (Claude)
Claude natively supports MCP. Point it at the Octopus MCP server using the Claude Desktop config:
{
"mcpServers": {
"octopus": {
"url": "https://api.example.com/mcp",
"headers": {
"Access-Token": "<your-jwt>"
}
}
}
}
Claude will automatically call GET /mcp/engineering/tools, build its tool list, and call POST /mcp/engineering/execute when it needs to act.