MCP Server Configuration

MCP server configuration for Claude Code.

Type StdioServer | HttpServer | SseServer
Schema URL https://catalog.lintel.tools/schemas/claude-code/mcp-server-config/latest.json

Validate with Lintel

npx @lintel/lintel check
Type: StdioServer | HttpServer | SseServer

Configuration for a single MCP server in Claude Code.

Supports three transport types:

  • stdio — Runs a local child process; Claude Code communicates over stdin/stdout
  • http — Connects to a remote server using streamable HTTP (recommended for remote servers)
  • sse — Connects to a remote server using server-sent events (deprecated; prefer HTTP)

All string fields support environment variable expansion:

  • ${VAR} — expands to the value of VAR
  • ${VAR:-default} — expands to VAR if set, otherwise uses default

Expansion is supported in command, args, env, url, and headers fields.

One of

1. StdioServer object
2. HttpServer object
3. SseServer object

Definitions

StdioServer object

A stdio-based MCP server that runs as a local child process.

Claude Code launches the specified command and communicates over stdin/stdout using the MCP stdio transport.

If type is omitted and command is present, stdio transport is assumed.

Use ${CLAUDE_PLUGIN_ROOT} in command, args, env, and cwd for plugin-relative paths. All string values support ${VAR} and ${VAR:-default} environment variable expansion.

Windows note: On native Windows (not WSL), servers that use npx require a cmd /c wrapper (e.g. "command": "cmd", "args": ["/c", "npx", "-y", "@some/package"]).

command string required

Executable to run.

Must be in PATH or specified as an absolute or relative path. Supports ${VAR} expansion and ${CLAUDE_PLUGIN_ROOT} for plugin-relative paths.

Examples: "node", "python", "npx", "/usr/local/bin/company-mcp-server", "${CLAUDE_PLUGIN_ROOT}/servers/db-server"
type const: "stdio"

Transport type.

Optional for stdio servers — if type is omitted and command is present, stdio is assumed.

Constant: "stdio"
args string[]

Command-line arguments passed to the server process.

Supports ${VAR} expansion and ${CLAUDE_PLUGIN_ROOT}.

Examples: ["serve"], ["--config","/etc/company/mcp-config.json"], ["--port","8080"], ["-y","@modelcontextprotocol/server-filesystem"]
env Record<string, string>

Environment variables set when starting the server process.

These are merged with the parent environment. Values support ${VAR} and ${VAR:-default} expansion, as well as ${CLAUDE_PLUGIN_ROOT} for plugin-relative paths.

Examples: {"DB_PATH":"${CLAUDE_PLUGIN_ROOT}/data"}, {"COMPANY_API_URL":"https://internal.company.com"}, {"AIRTABLE_API_KEY":"${AIRTABLE_API_KEY}"}
cwd string

Working directory for the server process.

If omitted, inherits the current working directory. Supports ${CLAUDE_PLUGIN_ROOT} for plugin-relative paths.

Examples: "${CLAUDE_PLUGIN_ROOT}", "/opt/mcp-servers"
timeout number

Connection timeout in milliseconds.

How long Claude Code waits for the server to start and respond to the initial handshake. Can also be configured globally via the MCP_TIMEOUT environment variable (e.g. MCP_TIMEOUT=10000 claude).

Examples: 10000, 30000
HttpServer object

A remote MCP server using the streamable HTTP transport.

This is the recommended transport for remote/cloud-based MCP servers. Claude Code connects to the server over HTTP/HTTPS.

Use headers for static authentication (e.g. API keys). For OAuth 2.0 authentication, configure the oauth field and use /mcp in Claude Code to complete the browser login flow.

All string values support ${VAR} and ${VAR:-default} environment variable expansion.

type const: "http" required

Transport type. Required for HTTP servers.

Constant: "http"
url string required

URL of the remote MCP server endpoint.

Supports ${VAR} and ${VAR:-default} environment variable expansion.

Examples: "https://api.githubcopilot.com/mcp/", "https://mcp.sentry.dev/mcp", "https://mcp.notion.com/mcp", "https://mcp.paypal.com/mcp", "${API_BASE_URL:-https://api.example.com}/mcp"
headers Record<string, string>

HTTP headers to include with every request.

Commonly used for static authentication (API keys, bearer tokens). Supports ${VAR} and ${VAR:-default} environment variable expansion in values.

Examples: {"Authorization":"Bearer ${MCP_API_KEY}"}, {"X-API-Key":"${API_KEY}"}
oauth object

Pre-configured OAuth 2.0 client credentials.

Required when the remote MCP server does not support dynamic client registration. Register an OAuth app through the server's developer portal and provide the clientId here. The client secret is passed separately via claude mcp add-json --client-secret and stored securely in your system keychain — it is never written to config files.

After configuring, run /mcp in Claude Code to complete the browser authentication flow. Tokens are stored securely and refreshed automatically.

2 nested properties
clientId string required

OAuth client ID obtained from the server's developer portal.

If the server uses a public OAuth client with no secret, provide only clientId without a corresponding --client-secret flag.

Examples: "your-client-id", "abc123def456"
callbackPort integer

Local port for the OAuth callback redirect.

Claude Code starts a temporary HTTP server on this port to receive the OAuth redirect. The redirect URI registered in the server's developer portal must match <http://localhost:<callbackPort>>/callback.

Choose any available port; it just needs to match the redirect URI you registered.

Examples: 8080, 3000, 9090
SseServer object

A remote MCP server using the SSE (server-sent events) transport.

Deprecated: The SSE transport is deprecated. Use HTTP servers instead, where available.

Claude Code connects to the server over HTTP/HTTPS with SSE for server-to-client messages. Configuration is identical to HTTP servers.

All string values support ${VAR} and ${VAR:-default} environment variable expansion.

type const: "sse" required

Transport type. Required for SSE servers.

Constant: "sse"
url string required

URL of the remote MCP server SSE endpoint.

Supports ${VAR} and ${VAR:-default} environment variable expansion.

Examples: "https://mcp.asana.com/sse", "https://mcp.example.com/sse"
headers Record<string, string>

HTTP headers to include with every request.

Commonly used for static authentication (API keys, bearer tokens). Supports ${VAR} and ${VAR:-default} environment variable expansion in values.

Examples: {"Authorization":"Bearer ${MCP_API_KEY}"}, {"X-API-Key":"${API_KEY}"}
oauth object

Pre-configured OAuth 2.0 client credentials.

Required when the remote MCP server does not support dynamic client registration. Register an OAuth app through the server's developer portal and provide the clientId here. The client secret is passed separately via claude mcp add-json --client-secret and stored securely in your system keychain — it is never written to config files.

After configuring, run /mcp in Claude Code to complete the browser authentication flow. Tokens are stored securely and refreshed automatically.

2 nested properties
clientId string required

OAuth client ID obtained from the server's developer portal.

If the server uses a public OAuth client with no secret, provide only clientId without a corresponding --client-secret flag.

Examples: "your-client-id", "abc123def456"
callbackPort integer

Local port for the OAuth callback redirect.

Claude Code starts a temporary HTTP server on this port to receive the OAuth redirect. The redirect URI registered in the server's developer portal must match <http://localhost:<callbackPort>>/callback.

Choose any available port; it just needs to match the redirect URI you registered.

Examples: 8080, 3000, 9090
OAuthConfig object

Pre-configured OAuth 2.0 client credentials.

Required when the remote MCP server does not support dynamic client registration. Register an OAuth app through the server's developer portal and provide the clientId here. The client secret is passed separately via claude mcp add-json --client-secret and stored securely in your system keychain — it is never written to config files.

After configuring, run /mcp in Claude Code to complete the browser authentication flow. Tokens are stored securely and refreshed automatically.

clientId string required

OAuth client ID obtained from the server's developer portal.

If the server uses a public OAuth client with no secret, provide only clientId without a corresponding --client-secret flag.

Examples: "your-client-id", "abc123def456"
callbackPort integer

Local port for the OAuth callback redirect.

Claude Code starts a temporary HTTP server on this port to receive the OAuth redirect. The redirect URI registered in the server's developer portal must match <http://localhost:<callbackPort>>/callback.

Choose any available port; it just needs to match the redirect URI you registered.

Examples: 8080, 3000, 9090