> ## Documentation Index > Fetch the complete documentation index at: https://docs.qoder.com/llms.txt > Use this file to discover all available pages before exploring further. # MCP reference > Transport methods, configuration fields, scope, and permissions for MCP servers The Model Context Protocol (MCP) allows Qoder CLI to integrate with third-party tools and services. This page provides a complete reference for MCP server configuration. For a usage guide, see [MCP Servers](/cli/mcp-reference). ## Transport Methods MCP servers specify the transport protocol via the `type` field: | Type | Description | | -------------------------- | --------------------------------------------------- | | `stdio` (default) | Spawns a subprocess and interacts via stdin/stdout. | | `sse` | Connects via Server-Sent Events over HTTP. | | `http` / `streamable-http` | Connects via HTTP (JSON-RPC + optional streaming). | | `ws` | Connects via WebSocket / TCP. | | `sdk` | Built-in SDK-level server (in-process). | ## Configuration Fields MCP servers are configured under the `mcpServers` field in `settings.json`, where each key represents a server name: ```json { "mcpServers": { "my-server": { "command": "node", "args": ["./mcp-server.js"], "env": { "API_KEY": "..." }, "cwd": "/path/to/dir" } } } ``` ### stdio Type | Field | Type | Description | | --------- | --------- | ----------------------------------------------- | | `command` | string | The command to start the server. | | `args` | string\[] | Arguments passed to the command. | | `env` | object | Environment variables passed to the subprocess. | | `cwd` | string | The working directory for the subprocess. | ### sse Type | Field | Type | Description | | --------- | ------- | ------------------------------------------ | | `url` | string | The SSE endpoint URL. | | `type` | `"sse"` | Transport type identifier. | | `headers` | object | HTTP headers (may include authentication). | ### http / streamable-http Type | Field | Type | Description | | --------- | -------- | -------------------------- | | `url` | string | The HTTP endpoint URL. | | `type` | `"http"` | Transport type identifier. | | `headers` | object | HTTP headers. | ### ws Type (TCP) | Field | Type | Description | | ------ | ------ | -------------------------------------- | | `tcp` | object | TCP connection parameters (host/port). | | `type` | `"ws"` | Transport type identifier. | ### Common Optional Fields | Field | Type | Description | | -------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | `timeout` | number | Connection/request timeout (in milliseconds). | | `type` | string | Explicitly specifies the transport type. | | `description` | string | Server description, displayed in the management view. | | `trust` | boolean | Trusts the server, skipping confirmation when its tools are called. | | `includeTools` | string\[] | Registers only the listed tools. | | `excludeTools` | string\[] | Excludes the listed tools. | | `disabled` | boolean | Disables the server (keeps the configuration without deleting it). | | `alwaysAllow` | string\[] | List of tool names that are always allowed without confirmation. | | `oauth` | object | OAuth authorization configuration (fields include `enabled`, `clientId`, `clientSecret`, `authorizationUrl`, `tokenUrl`, `scopes`, `callbackPort`, etc.). | | `qoder_url` | string | Complete HTTPS endpoint for a Qoder-managed MCP Gateway. When present, it is used with Streamable HTTP and takes precedence over other transport fields. | Managed Gateway requests use the current Qoder sign-in credential. If the upstream provider requires authorization, QoderCLI presents a secure authorization URL and reconnects the server after authorization succeeds. An interrupted tool call is not replayed automatically; invoke it again after the server reconnects. ## Configuration Scope MCP servers can be configured at multiple levels: | Level | Location | Description | | ------------- | ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | | User Level | `~/.qoder/settings.json` → `mcpServers` | Available to all projects. | | Project-Level | `/.qoder/settings.json` → `mcpServers` | Requires approval before use (for security reasons). | | Project-Level | `/.mcp.json` | Requires a top-level `mcpServers` key; requires approval before use. | | Local Level | `/.qoder/settings.local.json` → `mcpServers` | Local to the current project on this machine; the default scope for `-s`, loaded only when the directory is trusted. | | Plugin | `.mcp.json` or `mcp.json` in the plugin directory | Loaded upon plugin installation. | | CLI argument | `--mcp-config `, `--settings` | Valid for this session only. | Servers with the same name are overridden in the following order (later overrides earlier): User Level → Project-Level `settings.json` → Project-Level `.mcp.json` → Local Level → CLI argument. Project-level MCP servers require individual approval by default. This can be bypassed using the following methods: - `mcp.enableAllProjectMcpServers: true`: Automatically approves all project-level servers. - `mcp.enabledProjectMcpServers`: Allowlist, approves by name. Both settings are placed under the `mcp` group in `settings.json` (a restart is required after modification): ```json { "mcp": { "enableAllProjectMcpServers": true, "enabledProjectMcpServers": ["playwright", "context7"] } } ``` ## Permissions and Security - MCP tools are managed by the Permissions System just like built-in tools—user confirmation is required before invocation (unless using `auto` or `bypass_permissions` mode). - `--allowed-mcp-server-names`: Restricts loading to only MCP servers with specified names. - `--strict-mcp-config`: Strict mode: skip MCP servers from settings and `.mcp.json`, and disable plugin MCP servers by default. Servers specified by `--mcp-config` can still load. - `mcp.allowed` / `mcp.excluded`: Controls the allowlist or blocklist of servers in the configuration. ## Lazy Loading Mode When multiple MCP servers are connected, all tool schemas are registered at startup by default, which may consume a significant number of Prompt Tokens in the first turn. When lazy loading is enabled (`mcp.lazyLoad: true` or `QODER_MCP_LAZY=1`), the CLI exposes only three Meta Tools (`mcp_list` / `mcp_get` / `mcp_call`) and loads the actual tools on demand, saving token overhead. ## Management Commands Use the `/mcp` Slash Command to manage MCP servers in an interactive session: - `/mcp` — View the list and status of connected servers. - `/mcp reload` (alias `/mcp refresh`) — Rediscover MCP servers and tools, useful after adding or modifying configurations. Use the `qoder mcp` subcommand in the command line for non-interactive management: - `qoder mcp add -- ` — Add a stdio server. - `qoder mcp add --qoder-url ` — Add a server routed through a managed MCP Gateway. - `qoder mcp list` — List configured servers. - `qoder mcp remove ` — Remove a server. For arguments and examples for each subcommand, see [MCP Servers](/cli/mcp-reference). ## Next Steps - MCP usage guide: [MCP Servers](/cli/mcp-reference). - Full configuration reference: [Configurations, environment variables, and file paths](/cli/settings-reference). - Extension troubleshooting: [Hooks, MCP, and plugin issues](/cli/troubleshoot-extensions).