# 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

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

## Server Types

### stdio (Standard I/O)

Most common type, runs as subprocess:

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

### SSE (Server-Sent Events)

Connect to remote HTTP server:

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

## Common Patterns

### Filesystem Server

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

### Database Server

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

### Slack Server

```json
{
  "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:

```json
{
  "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
