MCP Config Cheat Sheet
Client-side MCP configuration: how to wire servers into Cursor, Claude Code, and other MCP hosts.
Last reviewed: June 2026
Config file location and field names vary by client. Verify in your IDE's MCP settings. Full guide: MCP Security · Building MCP Servers
File locations
| Client | Config path |
|---|---|
| Cursor (project) | .cursor/mcp.json |
| Cursor (global) | ~/.cursor/mcp.json |
| Claude Code | ~/.claude/settings.json → mcpServers (same shape) |
| VS Code MCP extensions | Extension-specific; often .vscode/mcp.json |
Project config overrides global for that repo.
Minimal config
{
"mcpServers": {
"my-dev-tools": {
"command": "node",
"args": ["./mcp-server/dist/index.js"]
}
}
}
Field reference
| Field | Type | Purpose |
|---|---|---|
command | string | Executable: node, python3, uv, npx, docker |
args | string[] | Arguments after command — path to entry file |
env | object | Environment variables for the spawned process |
cwd | string | Working directory (some clients support) |
disabled | boolean | Temporarily disable without removing entry |
Environment variables
{
"mcpServers": {
"staging-db": {
"command": "node",
"args": ["./mcp-server/dist/index.js"],
"env": {
"DATABASE_URL": "${env:DATABASE_URL}",
"LOG_LEVEL": "info"
}
}
}
}
| Pattern | Use |
|---|---|
${env:VAR} | Read from host shell environment |
Literal "info" | Non-secret config |
Never sk-... in JSON | Use env vars; rotate on leak |
Launch patterns
Node (built TypeScript)
{
"command": "node",
"args": ["./mcp-server/dist/index.js"]
}
Build first: cd mcp-server && npm run build
npx (no local install)
{
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/dir"]
}
Restrict filesystem paths — never mount repo root with secrets.
Python (uv)
{
"command": "uv",
"args": ["run", "mcp-server/main.py"]
}
Python (venv)
{
"command": "/path/to/venv/bin/python",
"args": ["mcp-server/main.py"]
}
Docker
{
"command": "docker",
"args": ["run", "-i", "--rm", "-e", "DATABASE_URL", "myorg/mcp-staging:1.2.0"]
}
Pin image digest in production; pass secrets via -e, not in the image.
Multiple servers
{
"mcpServers": {
"internal-docs": {
"command": "node",
"args": ["./servers/docs/dist/index.js"]
},
"staging-db": {
"command": "uv",
"args": ["run", "servers/db/main.py"],
"env": { "DATABASE_URL": "${env:STAGING_DATABASE_URL}" }
}
}
}
Each key is the server name shown in the IDE MCP panel.
Remote / SSE servers
Some clients support HTTP-based MCP (no local spawn):
{
"mcpServers": {
"remote-api": {
"url": "https://mcp.internal.example.com/sse",
"headers": {
"Authorization": "Bearer ${env:MCP_TOKEN}"
}
}
}
}
Verify OAuth vs static token support in your client version. See MCP Security.
Troubleshooting
| Symptom | Fix |
|---|---|
| Server not listed | Validate JSON (trailing commas break parse); restart IDE |
| Red / disconnected | Run command + args manually in terminal |
command not found | Use absolute path to node/python/uv |
| Env var empty | Export in shell before launching IDE, or use .env loader |
| Tool never invoked | Improve tool description; name tool explicitly in prompt |
| Works in terminal, not IDE | Check cwd; relative paths resolve from project root |
| Timeout | Return less data; add pagination to tools |
Test workflow
# 1. Build server
cd mcp-server && npm run build
# 2. Run MCP Inspector
npx @modelcontextprotocol/inspector node ./mcp-server/dist/index.js
# 3. Edit mcp.json, restart IDE
# 4. Ask mode smoke test
# "Use lookup_user to find [email protected]"
Security checklist
- [ ] No secrets in committed
mcp.json - [ ] Read-only DB credentials for dev tools
- [ ] PR review on config changes
- [ ]
.cursorignorecovers.env*