SCHEMA SPECIFICATION • DRAFT-07
MCP Config JSON Schema
The hand-authored JSON Schema (Draft-07) used to validate MCP host configuration files including claude_desktop_config.json and Cursor MCP configs.
Schema Architecture Overview
The root object requires a single mcpServers property. Each key in mcpServers represents a unique server identifier and must match one of two transport shapes:
stdio Transport
Requires command (string). Optionally accepts args (string[]) and env (key-value strings).
SSE Transport
Requires url (valid URI). Optionally accepts headers (key-value strings).
Field Reference
| Field | Type | Required | Description |
|---|---|---|---|
| mcpServers | object | Yes | Root container; keys are unique server names. |
| command | string | stdio: Yes | Executable binary to launch (e.g. npx, node, python3, uv). |
| args | string[] | No | CLI arguments — must be an array of strings. |
| env | object | No | Environment variables — all values must strictly be strings. |
| url | string (URI) | SSE: Yes | SSE endpoint URL — must be a valid http:// or https:// URI. |
| headers | object | No | HTTP headers sent with SSE requests — values must be strings. |
Full Schema (Draft-07 JSON)
schema.json{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "mcp-config",
"title": "MCP Host Configuration",
"type": "object",
"required": [
"mcpServers"
],
"additionalProperties": false,
"properties": {
"mcpServers": {
"type": "object",
"additionalProperties": {
"oneOf": [
{
"$ref": "#/definitions/stdioServer"
},
{
"$ref": "#/definitions/sseServer"
}
]
}
}
},
"definitions": {
"stdioServer": {
"type": "object",
"required": [
"command"
],
"additionalProperties": false,
"properties": {
"command": {
"type": "string",
"minLength": 1,
"description": "Executable to run, e.g. \"npx\" or \"node\""
},
"args": {
"type": "array",
"items": {
"type": "string"
},
"description": "CLI arguments passed to the command. Must be an array of strings."
},
"env": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "Environment variables. All values must be strings."
}
}
},
"sseServer": {
"type": "object",
"required": [
"url"
],
"additionalProperties": false,
"properties": {
"url": {
"type": "string",
"format": "uri",
"description": "SSE endpoint URL. Must be a valid http:// or https:// URI."
},
"headers": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "HTTP headers to send with SSE requests. All values must be strings."
}
}
}
}
}Validate your configuration
Check existing JSON configs against this schema in real-time.