MCP Configuration

ValidatorMCPOfficial docsMCP servers

The .mcp.json file configures Model Context Protocol servers. It supports a wrapped format ({ "mcpServers": { ... } }) for project scope or a flat format ({ "server-name": { ... } }) for plugin scope.

Fields

Server configuration varies by transport type.

stdio

Default transport when command is present.

Field	Type	Required	Description
type	string	no	Optional, inferred from command
command	string	yes	Command to execute
args	string[]	no	Command arguments
env	object	no	Environment variables
timeout	number	no	Per-server timeout in milliseconds
alwaysLoad	boolean	no	Load tool definitions without deferring to tool search

http

Field	Type	Required	Description
type	string	yes	Must be "http"
url	string	yes	HTTP endpoint URL
headers	object	no	HTTP headers
env	object	no	Environment variables
timeout	number	no	Per-server timeout in milliseconds
alwaysLoad	boolean	no	Load tool definitions without deferring to tool search
headersHelper	string	no	Command printing dynamic request headers
oauth	object	no	OAuth options: clientId, callbackPort, authServerMetadataUrl, and space-separated scopes

sse (deprecated)

Field	Type	Required	Description
type	string	yes	Must be "sse"
url	string	yes	SSE endpoint URL
headers	object	no	HTTP headers
env	object	no	Environment variables
timeout	number	no	Per-server timeout in milliseconds
alwaysLoad	boolean	no	Load tool definitions without deferring to tool search
headersHelper	string	no	Command printing dynamic request headers
oauth	object	no	OAuth options: clientId, callbackPort, authServerMetadataUrl, and space-separated scopes

ws (WebSocket)

The config literal is "ws" — not "websocket", which is not a valid value.

Field	Type	Required	Description
type	string	yes	Must be "ws"
url	string	yes	WebSocket URL (ws:// or wss://)
headers	object	no	Request headers (WebSocket auth is header-only)
env	object	no	Environment variables
timeout	number	no	Per-server timeout in milliseconds
alwaysLoad	boolean	no	Load tool definitions without deferring to tool search
headersHelper	string	no	Command printing dynamic request headers
oauth	object	no	OAuth options: clientId, callbackPort, authServerMetadataUrl, and space-separated scopes

streamable-http

A documented alias for http, accepted so configurations copied from MCP server documentation work unmodified. Same fields as http.

Example

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "analytics": {
      "type": "http",
      "url": "https://mcp.example.com/analytics"
    }
  }
}