Issue 20 | Official Built-in Connector Configuration and Enablement
🎯 Learning Objectives
By the end of this issue, you will master:
- The complete configuration process for Claude Code's built-in MCP Server
- Practical guides for official connectors like GitHub, Postgres, and Filesystem
- Selection strategies for Global vs. Project-level MCP configurations
- Troubleshooting methods for common configuration issues
📖 Core Concepts Explained
20.1 Two Levels of Configuration
Level 1: Global Configuration (User-level)
Location: ~/.claude/settings.json
Purpose: MCP Server common to all projects
Suitable for: Personal account-level services like GitHub, Slack
Level 2: Project Configuration (Project-level)
Location: .mcp.json (Project root directory)
Purpose: Effective only within the current project
Suitable for: Project-specific database connections, private APIs
⚠️ First-time use requires Claude to request your authorization
Level 3: Enterprise Configuration (Enterprise)
Location: Centrally distributed by administrators
Purpose: MCP Server shared by the entire team
Suitable for: Internal tool platforms, compliance review services
20.2 Common Official MCP Servers
╭────────────────────────────────────────────────╮
│ Anthropic Official Maintenance: │
│ ├── @anthropic-ai/mcp-server-github │
│ ├── @anthropic-ai/mcp-server-postgres │
│ ├── @anthropic-ai/mcp-server-filesystem │
│ └── @anthropic-ai/mcp-server-memory │
│ │
│ High-Quality Community Maintained: │
│ ├── mcp-server-slack │
│ ├── mcp-server-notion │
│ ├── mcp-server-linear │
│ ├── mcp-server-playwright │
│ ├── mcp-server-puppeteer │
│ └── mcp-server-excalidraw │
╰────────────────────────────────────────────────╯
💻 Simulating Claude TUI Interaction
Scenario 1: Configure GitHub MCP Server
> I want to configure GitHub integration so you can directly operate my repositories
╭─ Claude ─────────────────────────────────────────────╮
│ │
│ Great! Configuring the GitHub MCP Server requires 3 steps:│
│ │
│ 📋 Step 1: Create a GitHub Personal Access Token │
│ Visit: github.com/settings/tokens/new │
│ Select: repo, issues, pull_requests permissions │
│ │
│ 📋 Step 2: Add MCP Configuration │
│ ⚙️ Tool: Edit → ~/.claude/settings.json │
│ ╭─ Add Content ────────────────────────────────╮ │
│ │ { │ │
│ │ "mcpServers": { │ │
│ │ "github": { │ │
│ │ "command": "npx", │ │
│ │ "args": [ │ │
│ │ "-y", │ │
│ │ "@anthropic-ai/mcp-server-github" │ │
│ │ ], │ │
│ │ "env": { │ │
│ │ "GITHUB_TOKEN": "ghp_xxxxx" │ │
│ │ } │ │
│ │ } │ │
│ │ } │ │
│ │ } │ │
│ ╰────────────────────────────────────────────╯ │
│ │
│ 📋 Step 3: Restart Claude Code │
│ Exit and re-run the `claude` command │
│ │
│ Once configured, you can use it like this: │
│ - "List all my GitHub repositories" │
│ - "Create an Issue in my-repo" │
│ - "Commit current changes and create a Pull Request"│
│ │
╰──────────────────────────────────────────────────────╯
Scenario 2: Configure Project-Specific Postgres MCP
> This project needs to connect to a Postgres database for queries
╭─ Claude ─────────────────────────────────────────────╮
│ │
│ Project-level database connections are suitable for .mcp.json:│
│ │
│ ⚙️ Tool: Write → .mcp.json │
│ ╭─ File Content ────────────────────────────────╮ │
│ │ { │ │
│ │ "mcpServers": { │ │
│ │ "postgres": { │ │
│ │ "command": "npx", │ │
│ │ "args": [ │ │
│ │ "-y", │ │
│ │ "@anthropic-ai/mcp-server-postgres"│ │
│ │ ], │ │
│ │ "env": { │ │
│ │ "DATABASE_URL": │ │
│ │ "postgresql://user:pass@ │ │
│ │ localhost:5432/mydb" │ │
│ │ } │ │
│ │ } │ │
│ │ } │ │
│ │ } │ │
│ ╰────────────────────────────────────────────╯ │
│ │
│ ⚠️ Security Reminder: │
│ - Do not commit .mcp.json to Git │
│ - Automatically added to .gitignore │
│ - For production environments, passwords are recommended to use environment variables│
│ │
│ ⚙️ Tool: Edit → .gitignore │
│ Added: .mcp.json │
│ │
│ ✅ Configuration complete! After restarting, you can say:│
│ - "View the first 10 records of the user table" │
│ - "Does this SQL query have performance issues?" │
│ - "How many new users registered in the last 7 days?"│
│ │
╰──────────────────────────────────────────────────────╯
Scenario 3: Use an Already Configured MCP Tool
> Help me check the number of new users in the database over the past 7 days
╭─ Claude ─────────────────────────────────────────────╮
│ │
│ ⚙️ Tool: postgres_query │
│ $ SELECT COUNT(*) as new_users, │
│ DATE(created_at) as date │
│ FROM users │
│ WHERE created_at > NOW() - INTERVAL '7 days' │
│ GROUP BY DATE(created_at) │
│ ORDER BY date DESC; │
│ │
│ 📊 New users in the past 7 days: │
│ ╭────────────────────────────────╮ │
│ │ Date │ New Users │ │
│ │───────────│────────────────│ │
│ │ 03-22 │ 145 ████████████ │ │
│ │ 03-21 │ 128 ██████████ │ │
│ │ 03-20 │ 112 █████████ │ │
│ │ 03-19 │ 98 ████████ │ │
│ │ 03-18 │ 134 ███████████ │ │
│ │ 03-17 │ 156 █████████████│ │
│ │ 03-16 │ 143 ████████████ │ │
│ ╰────────────────────────────────╯ │
│ │
│ 📈 Trend: Average daily new users 131, weekend (03-17) registration volume│
│ highest (156), weekday (03-19) lowest (98). │
│ Total for 7 days: 916 new users. │
│ │
╰──────────────────────────────────────────────────────╯
💻 Code Demonstration
# ✅ Use claude mcp command to manage MCP Server
claude mcp add github \
-e GITHUB_TOKEN=ghp_xxxx \
-- npx -y @anthropic-ai/mcp-server-github
claude mcp add postgres \
--scope project \
-e DATABASE_URL=postgresql://localhost/mydb \
-- npx -y @anthropic-ai/mcp-server-postgres
# ✅ List all configured MCP Servers
claude mcp list
# ✅ Remove MCP Server
claude mcp remove postgres
# ✅ Test if connection is normal
claude "List all available MCP tools"
# ✅ Security Best Practice: Use .env file
# Reference environment variables in .mcp.json
{
"mcpServers": {
"postgres": {
"command": "npx",
"args": ["-y", "@anthropic-ai/mcp-server-postgres"],
"env": {
"DATABASE_URL": "${DATABASE_URL}"
}
}
}
}
Troubleshooting Common Configuration Issues
# Issue 1: MCP Server failed to start
# Manually run Server command to check for errors
npx -y @anthropic-ai/mcp-server-github
# Issue 2: Token expired
# Check if environment variables are correctly set
echo $GITHUB_TOKEN
# Issue 3: Database connection timeout
# Confirm database service is running
pg_isready -h localhost -p 5432
# Issue 4: Insufficient permissions
# Check if Token has the required Scope
curl -H "Authorization: Bearer ghp_xxx" \
https://api.github.com/user
🔧 Involved Tools / Commands
| Command/Tool | Purpose | Description |
|---|---|---|
claude mcp add |
Add MCP Server | Supports --scope project/user |
claude mcp list |
List configured Servers | Displays status and number of tools |
claude mcp remove |
Remove Server | Removes from configuration |
settings.json |
Global Configuration | ~/.claude/settings.json |
.mcp.json |
Project Configuration | Project root directory |
📝 Key Takeaways from This Issue
- MCP configuration is divided into Global and Project-level, choose according to security requirements
- Using the
claude mcp addcommand is the simplest configuration method - Do not hardcode sensitive credentials, use environment variables
.mcp.jsonshould be added to.gitignoreto prevent leakage- Once configured, all MCP tools can be invoked using natural language