Module mcp 

MCP (Model Context Protocol) integration — JSON-RPC client, tool bridging, lazy loading.

Modules

descriptors

Task 19 (Commit A) — safe local MCP descriptor cache and dormant deferred-tool integration (spec §7.4).

lease

Task 19 (Commit B) — session-scoped exact MCP runtime leases (spec §7.4).

Structs

McpConfig

MCP config file format: { “mcpServers”: { “name”: { command, args, env } } }

McpLeaseCapability

Typed per-session lease capability handed to tool contexts: the exact session identity plus the shared manager. Never widens to a server grant — every call re-validates the exact tool and fingerprint.

McpRuntimeManager

Session-scoped exact MCP runtime lease manager. See module docs.

McpServerConfig

MCP server configuration — matches claude-code/gemini-cli format.

McpSessionEndGuard

Durable last-owner session scope. The Runtime mints ONE of these per tool session (wrapped in an Arc shared by every runtime clone and in-flight stream); streams HOLD it, never construct or drop their own. Leases therefore survive across provider turns, and only the drop of the LAST owner — true session end — terminates the session’s leases.

PendingMcpDiscovery

Discovery deferred by setup_cached_mcp: exactly the configured servers (from the SAME config snapshot phase 1 used) that had no fingerprint-matching cache entry, so none of them has registered tools.

Enums

McpDiscovery

How engine boot treats configured MCP servers that have no fingerprint-matching descriptor-cache entry (see setup_lazy_mcp).

Constants

DISCOVERY_CONCURRENCY

How many missing servers are discovered at once. With N missing servers boot discovery costs at most ceil(N / DISCOVERY_CONCURRENCY) seed timeouts (one for any realistic N), never N × one.

MCP_CONFIG_MAX_ARGS

MCP_CONFIG_MAX_ARG_BYTES

MCP_CONFIG_MAX_BYTES

Hard byte bound on mcp.json.

MCP_CONFIG_MAX_COMMAND_BYTES

MCP_CONFIG_MAX_ENV_ENTRIES

MCP_CONFIG_MAX_ENV_KEY_BYTES

MCP_CONFIG_MAX_ENV_VALUE_BYTES

MCP_CONFIG_MAX_SERVERS

Structural bounds on mcp.json (Task 19 review): the 1 MiB byte cap alone leaves server/env counts and string shapes unbounded. Violations fail the WHOLE config closed with a static reason.

MCP_CONFIG_MAX_SERVER_NAME_BYTES

Functions

load_mcp_config

Load MCP config from ~/.synaps-cli/mcp.json (or profile variant).

setup_cached_mcp

Background-mode phase 1 (McpDiscovery::Background): register the cached descriptors only — never spawns — and hand back the discovery still owed for servers without a fingerprint-matching entry (None when there is none). Returns (tools registered, pending discovery).

setup_lazy_mcp

Set up MCP loading at engine boot, before any session tool set exists.

validate_mcp_config

Validate config structure before ANY use. Static reasons only — no config content is ever echoed.