tai/taicpp/docs/mcp.md

mcp (taicpp)

Port of the MCP section of ../tai.py, normative text in ../mcp.md. Namespace detz::mcp, sources in src/mcp/. Reuses the detz::wire layer from src/cap/ (see docs/cap.md).

Spec delta (this milestone)

The placeholder serve_list/serve_call is replaced by the real client, OAuth, bridge, vault tables, tool backends and server.

Parity table

Python	C++
MCP_PROTOCOL_VERSION MCP_CLIENT_NAME MCP_TOOL_PREFIX MCP_RESOLVER_TIMEOUT MCP_RESOLVER_STEPS MCP_OAUTH_TIMEOUT MCP_RESOLVER_BRIEF MCP_CONNECT_TIMEOUT MCP_CALL_TIMEOUT MCP_RESULT_MAX MCP_HTTP_MAX_BODY MCP_MAX_SERVERS MCP_MAX_TOOLS MCP_SESSION_IDLE MCP_CHAT_TIMEOUT MCP_DEFAULT_PORT MCP_SERVER_RE MCP_VAR_RE MCP_GITHUB_RE	mcp_constants.h
McpError McpJsonRpcError McpHttpError	mcp_error.h
mcp_sanitize_name mcp_github_target mcp_expand_vars mcp_rewrite_placeholders mcp_entry_from_mapping mcp_normalize mcp_tool_hash mcp_bridge_name	McpNormalizer
McpStdioTransport McpHttpTransport McpClient	same names, McpTransport interface
McpOAuthCallback McpOAuth	same names
McpBridge	McpBridge over McpHost
Store.mcp_*	McpStore interface, McpSqliteStore (four tables)
Tools.run_mcp_*, mcp_resolve_github, mcp_resolve_agent, mcp_schemas	McpTools
McpServeSession McpServeContext mcp_serve_tools mcp_serve_handler mcp_serve_main	McpServeSession McpServeContext McpServeHandler McpServeMain

Wire subset

Methods: initialize, notifications/initialized, ping, tools/list, tools/call, notifications/cancelled. Errors -32601, -32602, -32603. Protocol 2025-11-25.

Caps

MCP_CONNECT_TIMEOUT 20, MCP_CALL_TIMEOUT 60, MCP_RESULT_MAX 65536, MCP_HTTP_MAX_BODY 10485760, MCP_MAX_SERVERS 32, MCP_MAX_TOOLS 100, MCP_SESSION_IDLE 3600, MCP_CHAT_TIMEOUT 600, MCP_RESOLVER_TIMEOUT 300, MCP_RESOLVER_STEPS 12, MCP_OAUTH_TIMEOUT 300.

Vault tables

mcp_servers, mcp_server_profiles, mcp_tool_pins, mcp_server_tools (McpSqliteStore::ensureSchema).

Agent tools

mcp_add, mcp_list, mcp_enable, mcp_disable, mcp_remove, mcp_tools, mcp_call, mcp_login (McpTools::dispatch). Served extras: chat, completions.

Differences from Python (declared)

• mcp_login browser: opens xdg-open only when DISPLAY/WAYLAND_DISPLAY is set; Python's webbrowser has a longer fallback list.
• Transport error texts come from libcurl mapped to urllib wording ([Errno 111] Connection refused, timed out); exotic failures differ.
• HTTP Server: header omits the Python version suffix.
• mcp_store_tools runs in one transaction (Python leaves partial writes pending on a duplicate tool name).
• stdio stderr is a pipe nobody drains, exactly as in tai.py (the doc says drained, the code does not).

Verification

tests/capmcp_unit.cpp (vault tables, normalizer, served endpoint in process). No differential run against tai.py yet for the client, OAuth, bridge and server (see docs/wiring/capmcp.md, Known gaps).