MCP

HTTP routes that expose BigwaveMcpServer as MCP-over-HTTP — the in-tree Model Context Protocol server that lets agent harnesses discover and invoke bigwave-defined tools. External MCP-aware clients (Claude Code, the Cursor agent, custom orchestrators) hit these routes for tool catalog and execution; see the agent-harness concept page for how MCP fits the broader tool-orchestration story.

The router lives at packages/mcp/server_routes.py. The server itself is BigwaveMcpServer (packages/mcp/server.py). Wire types are at packages/mcp/types.py:23 (McpTool), :34 (McpCall), and :43 (McpResult).

Endpoints

Method	Path	Auth	Summary
GET	/admin/mcp/tools	Bearer	List tools the server exposes (workspace-fenced).
POST	/admin/mcp/call	Bearer	Invoke a tool by name with arguments.

GET /admin/mcp/tools

Returns a JSON array of McpTool:

[
  {
    "name": "knowledge.search",
    "description": "Vector-search the workspace's knowledge base.",
    "input_schema": {
      "type": "object",
      "properties": {
        "query": {"type": "string"},
        "kb_id": {"type": "string"}
      },
      "required": ["query"]
    }
  }
]

The catalog is workspace-fenced — tools that depend on workspace-scoped state (e.g. a missing knowledge base) are not returned for tenants that lack the prerequisite.

curl -H "Authorization: Bearer $BIGWAVE_ADMIN_TOKEN" \
  http://localhost:8000/admin/mcp/tools

POST /admin/mcp/call

Body schema McpCall:

{
  "name": "knowledge.search",
  "arguments": {
    "query": "What's the workspace fence?",
    "kb_id": "kb_01HF…"
  }
}

Returns McpResult:

{
  "is_error": false,
  "content": "[{\"text\": \"…\", \"score\": 0.83}]",
  "metadata": {"latency_ms": 41}
}

content is a free-form text payload — JSON-stringified for structured tools. An unknown tool name returns 404 with the McpToolNotFoundError message. In-tool failures are surfaced inside the result envelope (is_error: true) rather than as HTTP errors — the protocol carries error semantics in-band.

curl -X POST -H "Authorization: Bearer $BIGWAVE_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"knowledge.search","arguments":{"query":"workspace fence"}}' \
  http://localhost:8000/admin/mcp/call

Operator notes

• Workspace fence. Both routes resolve the workspace from the bearer principal and pass it as workspace_id into the server call site; tools cannot enumerate or invoke against another tenant's state. See workspace fence.
• In-tool errors vs HTTP errors. A tool that fails its own contract (invalid arguments, upstream miss) returns 200 with is_error: true. Only "tool does not exist" is a 404. This matches the MCP spec and lets agent harnesses keep their state machine simple.
• Transport. This is HTTP — the in-tree server also speaks stdio for local agent harnesses. The HTTP surface is what external orchestrators reach.
• 503 causes. app.state.mcp_server is wired in lifespan; routes return 503 with "bigwave mcp server not initialised" when the lifespan did not complete or MCP support is disabled.
• Concept page. See the agent harness for how tool orchestration is one of the eight harness primitives.