kienbui1995/claude-mcp-setup

Claude MCP Setup

Overview

MCP (Model Context Protocol) lets Claude Code call external tools: query your database, create GitHub issues, search Slack, call APIs. Without MCP, Claude can only work with files and bash commands. With MCP, Claude becomes a full participant in your entire toolchain — querying live data to debug, creating issues, looking up docs.

When to Use

• Want Claude to directly query your database during development
• Need Claude to access external APIs (Stripe, GitHub, Slack) as tools
• Building custom MCP tools for your specific workflow
• Connecting Claude to Amplitude, Sentry, or other SaaS tools
• Setting up Claude Code for a new project with external dependencies

Core Jobs

1. MCP Server Configuration (.claude/settings.json)

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "postgresql://localhost/mydb"
      }
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"]
    }
  }
}

Scope: Project-level (.claude/settings.json) or global (~/.claude/settings.json). Project-level preferred for team consistency. Never hardcode secrets — use ${ENV_VAR} syntax.

2. Popular MCP Servers

Database:
  @modelcontextprotocol/server-postgres    — Query PostgreSQL directly
  @modelcontextprotocol/server-sqlite      — Query SQLite files

Development:
  @modelcontextprotocol/server-github      — Issues, PRs, repos
  @modelcontextprotocol/server-git         — Git history, blame
  @modelcontextprotocol/server-filesystem  — File system access

Analytics:
  @amplitude/mcp                           — Amplitude analytics
  (see Amplitude Division in magic-powers)

Productivity:
  @modelcontextprotocol/server-slack       — Slack messages, channels
  mcp-server-linear                        — Linear issues

3. Designing Tool Descriptions for Claude

The most important thing about MCP: tool descriptions determine when Claude uses them.

// Bad tool description — Claude won't know when to call this
{
  name: "query_db",
  description: "Queries the database",
  inputSchema: { query: { type: "string" } }
}

// Good tool description — Claude knows exactly when and how to use
{
  name: "query_user_data",
  description: "Query the PostgreSQL database for user information, analytics, or debugging. Use when: checking what data exists for a user, debugging production issues, verifying data integrity. Returns: JSON with query results. Max 100 rows. Timeout: 10s.",
  inputSchema: {
    query: {
      type: "string",
      description: "SQL SELECT query only. No INSERT/UPDATE/DELETE. Tables: users, subscriptions, events, audit_log."
    }
  }
}

Good descriptions answer: when to call this tool, what it returns, what constraints apply (read-only, row limits, timeouts), and what tables/endpoints are available.

4. Security Considerations for MCP

Read-only access:     Grant Claude SELECT-only DB permissions for dev databases
Scoped access:        Limit filesystem MCP to project directory only
No production creds:  Use dev/staging credentials in local MCP config
Audit logging:        Log all MCP tool calls for security review
Secret management:    Use environment variables, never hardcode in settings.json

Key Concepts

• MCP (Model Context Protocol) — standard for connecting AI to external tools; Anthropic-invented, industry-adopted
• MCP server — process that exposes tools Claude can call (DB queries, API calls, file operations)
• Tool description — text that tells Claude when and how to use a tool; the most important configuration
• Project vs global MCP — project-level for team tools; global for personal productivity tools

Checklist

• [ ] MCP servers configured for all external services Claude needs to access?
• [ ] Tool descriptions explain WHEN to use (not just what they do)?
• [ ] Read-only credentials used where possible?
• [ ] MCP config in .claude/settings.json committed to repo (minus secrets)?
• [ ] Secrets in environment variables (not hardcoded in settings.json)?

Key Outputs

• .claude/settings.json: MCP server configuration
• Tool capability summary in CLAUDE.md: what Claude can access and how

Output Format

• 🔴 Critical — production credentials in MCP config, write access to DB when read-only suffices, secrets hardcoded in committed settings.json
• 🟡 Warning — poor tool descriptions (Claude doesn't know when to call), no MCP for commonly-needed external data (team queries DB manually that Claude could query)
• 🟢 Suggestion — add GitHub MCP for PR/issue context, add DB MCP for debugging queries, scope filesystem MCP to project root only

Anti-Patterns

• Production database credentials in development MCP config
• Generic tool descriptions ("queries the database") — Claude won't know when to use them
• Global MCP for project-specific tools (creates confusion across unrelated projects)
• No MCP for services that are constantly needed during development (forces manual lookup)

Integration

• Use with claude-hooks (hooks can validate/audit MCP tool calls via PreToolUse)
• Use with claude-project-settings (MCP configured in same settings.json)
• See Amplitude Division skills for Amplitude-specific MCP usage patterns