# src/mcp KNOWLEDGE BASE
## OVERVIEW
Model Context Protocol client runtime: stdio and Streamable HTTP transports, OAuth 2.1 PKCE auth, JSON-RPC request/response, tool discovery, and routing to provider-visible tool definitions.
## WHERE TO LOOK
| Module boundary | `mod.rs` | `McpError`, `McpResult`, crate-private re-exports. |
| Client lifecycle | `client.rs` | `McpClient`: connect, initialize, list_tools, call_tool. Cancellable variants. |
| Server registry | `manager.rs` | `McpManager`: settings → connected servers, route table, qualified names `mcp__server__tool`, provider tool definitions. |
| Protocol types | `protocol.rs` | Initialize/tool-list/call-tool params/results, content blocks, protocol version `2025-03-26`. |
| JSON-RPC | `jsonrpc.rs` | Request/response/error/notification message types, `RequestId`. |
| Stdio transport | `stdio.rs` | Spawn child process, newline-delimited JSON-RPC frames, reader thread, bounded stderr, timeout/cancel. |
| HTTP transport | `http.rs` | Streamable HTTP: POST JSON/SSE, GET SSE notification stream, session ID, DELETE teardown. |
| SSE parser | `sse.rs` | Incremental SSE event reader, bounded bytes, JSON-RPC extraction. |
| OAuth | `oauth.rs` | PKCE flow, token storage (`$MC_HOME/mcp-tokens/*.json`, 0600), refresh, discovery, dynamic client registration. |
| HTTP headers | `headers.rs` | Env-var references `{env:VAR}`, sensitive header detection, literal secret rejection. |
| Tool schema | `tool_schema.rs` | MCP `Tool` → provider JSON schema, name validation, qualified name length cap (64 bytes). |
## CONVENTIONS
- MCP protocol version pinned `2025-03-26`. Reject unsupported versions at initialize.
- Tool names validated: non-empty, ASCII alphanumeric plus `_`/`-`, no `__`.
- Qualified names use `mcp__server__tool` and cap at 64 bytes.
- Duplicate qualified tool names are config errors.
- One bad server does not break other configured servers.
- Stdio uses newline-delimited JSON-RPC over child stdin/stdout.
- Stdio frame cap is 1 MiB.
- Stdio reader thread fails all pending requests on EOF.
- HTTP uses Streamable HTTP with session ID header.
- HTTP POST returns JSON or SSE.
- HTTP GET opens notification SSE best-effort; tolerate 404/405.
- All transports support cancellation through `AgentCancellation` checks in send-request loops.
- Timeout comes from config `timeout`; default is `DEFAULT_MCP_TIMEOUT_SECONDS`.
- Timeout fails in-flight request and terminates connection.
- OAuth tokens stored at `$MC_HOME/mcp-tokens/{server}.json`.
- OAuth token files require 0600 permissions and cross-process file lock.
- OAuth uses PKCE S256.
- OAuth dynamic client registration used when no `client_id` configured.
- OAuth refresh uses 60s expiry skew.
- Discovery supports RFC 8414 and OIDC metadata.
- Sensitive HTTP headers (`authorization`, `token`, `secret`, `api-key`) must use `{env:VAR}` syntax.
- Literal sensitive header values are rejected.
- Error messages sanitize URLs: strip userinfo, query, fragment.
- Error messages redact header values and bearer tokens.
- `Drop` shuts down connections: kill child process, join reader thread, DELETE HTTP session.
## ANTI-PATTERNS
- Do not accept MCP tool names with `__`, slashes, or non-ASCII characters.
- Do not bypass qualified name length cap.
- Do not bypass route deduplication.
- Do not store OAuth tokens without file lock.
- Do not store OAuth tokens without 0600 permissions.
- Do not combine static Authorization header with OAuth config.
- Do not leak URLs with query/fragment in errors or Debug output.
- Do not leak header values or bearer tokens in errors or Debug output.
- Do not let HTTP GET SSE failure block POST request flow.
- Do not skip cancellation checks in request loops.
- Do not make MCP module types public; keep crate-private.