MCP Server Configuration Rules

This rule applies to files matching the patterns above.

# MCP Server Configuration Rules

## Rule
All MCP server configurations MUST follow security and access control standards. Never commit credentials directly in .mcp.json.

## Configuration Location
```
# Project-level (team-shared, version controlled)
.mcp.json            # Server definitions with env var references
.mcp.json.example    # Template without real credentials

# User-level (personal integrations)
~/.claude/.mcp.json  # Private servers and credentials
```

## Credential Rules

### Good — Environment Variable References
```json
{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "$DATABASE_URL"
      }
    }
  }
}
```

### Bad — Hardcoded Credentials
```json
{
  "mcpServers": {
    "postgres": {
      "env": {
        "DATABASE_URL": "postgresql://admin:password123@prod.example.com:5432/mydb"
      }
    }
  }
}
```

## Access Control Rules
1. **Filesystem MCP**: Scope to specific directories, NEVER allow root access
2. **Database MCP**: Use read-only credentials when possible
3. **GitHub MCP**: Use fine-grained tokens with minimal permissions
4. **Custom MCP**: Implement authentication and rate limiting

## Gitignore Rules
```gitignore
# If .mcp.json contains any credentials
.mcp.json

# Always provide a template
!.mcp.json.example
```

## Server Limits
- Maximum 5 MCP servers per project (startup performance)
- Each server should have a clear, documented purpose
- Remove unused servers — they consume resources on startup

## Required Documentation
```markdown
<!-- In CLAUDE.md -->
## MCP Servers
- **postgres**: Read-only access to development database
- **github**: Repository management (issues, PRs)
- **filesystem**: Access to /docs for documentation reading
```

## Anti-Patterns
- Committing .mcp.json with real credentials
- Giving filesystem MCP access to / or ~
- Using production database credentials in MCP
- Not documenting MCP servers in CLAUDE.md
- Running more than 5 MCP servers (slow startup)