ktg-plugin-marketplace/plugins/config-audit/skills/config-hierarchy/references/mcp-json-patterns.md

MCP Server Configuration Reference

File Locations

Location	Scope
~/.claude.json → mcpServers	Global (all projects)
.mcp.json	Project-specific
.claude/settings.json → mcpServers	Project-specific

Basic Structure

{
  "mcpServers": {
    "server-name": {
      "command": "executable",
      "args": ["arg1", "arg2"],
      "env": {
        "KEY": "value"
      }
    }
  }
}

Server Types

stdio (Standard I/O)

Most common type, runs as subprocess:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-server-filesystem", "/path/to/root"],
      "env": {}
    }
  }
}

SSE (Server-Sent Events)

Connect to remote HTTP server:

{
  "mcpServers": {
    "remote-service": {
      "url": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${API_TOKEN}"
      }
    }
  }
}

Common Patterns

Filesystem Server

{
  "filesystem": {
    "command": "npx",
    "args": ["-y", "@anthropic/mcp-server-filesystem", "."],
    "env": {}
  }
}

Database Server

{
  "database": {
    "command": "npx",
    "args": ["-y", "@anthropic/mcp-server-postgres"],
    "env": {
      "DATABASE_URL": "${DATABASE_URL}"
    }
  }
}

Slack Server

{
  "slack": {
    "command": "npx",
    "args": ["-y", "@anthropic/mcp-server-slack"],
    "env": {
      "SLACK_BOT_TOKEN": "${SLACK_BOT_TOKEN}",
      "SLACK_TEAM_ID": "${SLACK_TEAM_ID}"
    }
  }
}

Environment Variables

Best practice: Use ${VAR_NAME} syntax instead of hardcoded values:

{
  "env": {
    "API_KEY": "${MY_API_KEY}"  // Good
    // "API_KEY": "sk-abc123..."  // Bad - exposed secret
  }
}

Security Considerations

1. Never hardcode secrets in .mcp.json
2. Use environment variable references (${VAR})
3. .mcp.json should be gitignored if it contains any sensitive paths
4. Check for secrets before committing

Global vs Project

When to use global (~/.claude.json)

• Servers used across all projects
• Personal tools (Slack, email)
• Utility servers (filesystem with safe root)

When to use project (.mcp.json)

• Project-specific databases
• Project APIs
• Specialized tools for this codebase