Configure MCP servers

Model Context Protocol (MCP) is optional and off by default. Saved server configuration does not grant consent to discover, connect to, or start a server. Use xcsh mcp list to inspect saved configuration without enabling the runtime.

Enable MCP persistently for your user with xcsh config set mcp.enabled true, enable it for one run with xcsh --mcp, or use the MCP toggle in /settings. --no-mcp always disables MCP for that run. The mcp.enabled setting is user-only: a repository’s project settings cannot enable MCP. An external xcsh config set command affects new processes; the /settings toggle updates the current interactive session before the settings panel closes.

SDK callers must pass the literal option enableMCP: true. Agent Client Protocol (ACP) sessions ignore ambient configuration and enable only non-empty mcpServers descriptors supplied by the ACP client.

Which transport and lifecycle should I declare?

A local server uses a command plus arguments and communicates over stdio. A remote server declares an HTTP-capable uniform resource locator (URL) and the supported transport options. The runtime selects from the declared shape; it does not silently reinterpret a malformed local entry as a remote one.

How do I resolve variables without embedding secrets?

Configuration values can reference environment-backed variables. Credential resolution happens before connection establishment, and unresolved required variables fail that server without printing the secret. Keep tokens outside committed mcp.json files.

How do I disable a discovered server?

Add its normalized identifier to disabledServers when a higher-precedence discovery source should remain visible but inactive. Validate the resulting set with xcsh mcp list, then use the MCP management commands to reconnect or reload after a file change.

For a first connection, configure one local stdio server with an absolute executable path and no credentials, then run xcsh mcp list. Add required environment references only after the explicit opt-in succeeds. Starting xcsh without an opt-in and listing configuration never launch the server. /mcp test may make one temporary connection and disconnects it afterward without enabling the runtime. After testing, remove the entry and confirm the saved server disappears.