MCP Gateway¶
How to discover and call MCP gateway capabilities — the primary interface for agents
When to use¶
agent needs to interact with work-buddy systems or discover capabilities
Directions¶
FastMCP server exposing work-buddy capabilities via 5 gateway tools with dynamic tool discovery. Runs as a persistent sidecar service on localhost:5126, shared across all Claude Code sessions in this project.
Before writing Python to interact with the vault, tasks, journal, contracts, or memory — check the gateway first. Many operations already exist as registered capabilities.
| Tool | Purpose |
|---|---|
| wb_init(session_id) | REQUIRED first call. Registers your session. |
wb_search(query) |
Discover OR inspect. Natural language → find capabilities. |
wb_run(capability, params) |
Execute a discovered capability. |
wb_advance(run_id, result) |
Step through multi-step workflows. |
wb_status() |
Check system health and active workflows. |
Workflow: wb_init → wb_search to discover → read the parameter schema → wb_run to execute.
Inspect before calling: wb_search with an exact capability name returns just that one entry with its full parameter schema.
Transport modes: streamable-http (default, persistent sidecar, .mcp.json type:http url:http://localhost:5126/mcp) or stdio (fallback, session-specific, python -m work_buddy.mcp_server without --http).
Subprocess isolation for auto_run steps: Workflow steps marked auto_run execute in isolated subprocesses (not in-process). This prevents CPU-bound code from holding the GIL and blocking other sessions. Protocol: conductor spawns python -m work_buddy.mcp_server.subprocess_runner, sends JSON on stdin (callable, kwargs, session_id), reads JSON result from stdout. All logging goes to stderr. Timeout: 30s default.
Search architecture: BM25 + semantic embeddings computed server-side by embedding service (localhost:5124), fused into a single score. Falls back to substring matching if service offline. Each capability has name, description, and optional search_aliases as scoring surfaces.
Gateway pattern: Instead of one MCP tool per function, the server has a registry of capabilities and workflows. Agents discover via wb_search, execute via wb_run.
Workflow conductor: wb_run starts a WorkflowDAG, returns first step instructions + workflow_run_id. Agent calls wb_advance after each step. auto_run steps are executed transparently in subprocesses.
Configuration: sidecar.services.mcp_gateway in config.yaml (module, port 5126, args: [--http]). Claude Code connection: .mcp.json with type:http, url:http://localhost:5126/mcp.
Health check: GET /health on port 5126 returns {status: ok}.
Do not: - Guess at work_buddy.* module paths or function signatures — search first - Write raw Python to read vault files when a gateway capability already exists - Write Python to call work-buddy functions when the same operation is available as an MCP tool - Skip wb_init — all other tools are gated behind it