mcp_tools

Load states a configured MCP server can end up in.

Display strings for the auto-discovered MCP config paths.

Ordered from lowest to highest precedence. Each entry is (path, label) suitable for rendering in help screens and error messages. The runtime discovery in discover_mcp_configs builds the same paths from Path.home() and _resolve_project_config_base().

Load and validate MCP configuration from a JSON file.

Supports multiple server types:

• stdio: Process-based servers with command, args, env fields (default)
• sse: Server-Sent Events servers with type: "sse", url, and optional headers
• http: HTTP-based servers with type: "http", url, and optional headers

Any server type may also set an optional tool filter:

• allowedTools: list of tool names or patterns to keep (all others dropped)
• disabledTools: list of tool names or patterns to drop (all others kept)

Entries are either literal tool names or fnmatch-style glob patterns (entries containing *, ?, or [). Each entry is matched against both the bare MCP tool name and the server-prefixed form (f"{server_name}_{tool}"), so either read_* or fs_read_* works. Setting both fields on a single server is an error.

Find MCP config files from standard locations.

Checks the paths listed in MCP_CONFIG_DISCOVERY_PATHS, lowest to highest precedence.

Split discovered config paths into user-level and project-level configs.

Extract stdio server entries from a parsed MCP config.

Return (name, kind, summary) for every server in a project config.

Used by the trust prompt and the untrusted-config skip warning so that both stdio servers (which spawn local commands) and remote servers (which can SSRF or exfiltrate environment variables via interpolated headers when an attacker controls .mcp.json) are gated identically.

Merge multiple MCP config dicts by server name.

Load an MCP config file, returning None on any error.

Load an MCP config file, returning (config, error).

Missing files yield (None, None) — not an error. Malformed files yield (None, error_text) so callers can surface the reason to users.

Load MCP tools from a configuration file.

Resolve MCP config and load tools.

Auto-discovers configs from standard locations and merges them. When explicit_config_path is provided it is added as the highest-precedence source and errors in that file are fatal.

Explicit user/project path context for project-sensitive behavior.

Metadata for a single MCP tool.

Metadata for a configured MCP server and its tools.

An MCP configuration file is malformed or structurally invalid.

Subclasses ValueError so existing except ValueError handlers keep working; new code can catch this specifically to render a user-actionable message (typically with a file path and hint).

Lazy, per-server cache of persistent MCP sessions.

Discovery always happens through throwaway sessions. Live sessions are only created on the first real tool call inside the runtime event loop so sessions stay bound to the loop that owns their subprocess/transport handles, and so stdio servers are not restarted on every invocation.