Field explanations
- command: executable started by the client
- args: process arguments
- env: variables passed to the server
- transport: stdio, HTTP, or SSE depending on client support
Minimal template
{
"mcpServers": {
"example": {
"command": "node",
"args": ["server.js"],
"env": {
"API_KEY": "${API_KEY}"
}
}
}
}Common usage patterns
- Keep mcp.json / .mcp.json small and reviewable
- Use comments only when the format supports them
- Commit example files with placeholder values
- Validate locally before deploying
Common errors
- Missing env var
- Server crashed unexpectedly
- OAuth unsupported by client
- Relative path resolves from wrong cwd
Online validation
Validate syntax first, then compare behavior against your deploy target. For JSON-based configs, use the JSON formatter before debugging tool-specific behavior.