MCP reference

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.

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:

{
  "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.).

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	`<project>/.qoder/settings.json` → `mcpServers`	Requires approval before use (for security reasons).
Project-Level	`<project>/.mcp.json`	Requires a top-level `mcpServers` key; requires approval before use.
Local Level	`<project>/.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 <path>`, `--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):

{
  "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, loads only servers from the file specified by --mcp-config.
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 qodercli mcp subcommand in the command line for non-interactive management:

qodercli mcp add <name> -- <command> — Add a stdio server.
qodercli mcp list — List configured servers.
qodercli mcp remove <name> — Remove a server.

For arguments and examples for each subcommand, see MCP Servers.

Next Steps

MCP usage guide: MCP Servers.
Full configuration reference: Configurations, environment variables, and file paths.
Extension troubleshooting: Hooks, MCP, and plugin issues.

​Transport Methods

​Configuration Fields

​stdio Type

​sse Type

​http / streamable-http Type

​ws Type (TCP)

​Common Optional Fields

​Configuration Scope

​Permissions and Security

​Lazy Loading Mode

​Management Commands

​Next Steps