MCP (Model Context Protocol)

Connect your AI coding assistant to live external systems — databases, APIs, internal tools

🎯 What is MCP?

MCP (Model Context Protocol) is an open standard for connecting AI assistants to external tools and data sources. Instead of an AI only knowing what's in its training data and the files you show it, an MCP server exposes live capabilities — querying a database, calling an internal API, searching documentation, reading tickets from an issue tracker — as tools the AI can call directly during a conversation.

Think of MCP servers as plugins: each one focuses on a single system and exposes a small set of tools/resources for interacting with it.

💡 Why it matters

Without MCP, "check the current staging database schema" or "look up this ticket in Jira" requires you to copy-paste data into the chat. With the right MCP server connected, the AI queries it directly and reasons over live, current data.

📦 Configuration scopes

MCP servers can be registered at three levels, same idea as other Claude Code configuration:

Scope	File	Shared with team?	Typical use
User (global)	~/.claude.json (user scope)	No — personal	Servers you use across all projects (e.g. your personal GitHub account, personal note-taking tool)
Project	.mcp.json at repo root, committed to git	Yes	Servers every teammate needs for this project (e.g. the project's database, internal API gateway)
Local	Project-scoped but not committed	No — personal override	Servers with per-developer credentials or local-only endpoints

# Add an MCP server at project scope (writes to .mcp.json, shared via git)
claude mcp add --scope project my-db -- npx -y @some/mcp-server-db

# Add an MCP server at user scope (personal, available in every project)
claude mcp add --scope user github -- npx -y @modelcontextprotocol/server-github

# List configured servers
claude mcp list

# Remove a server
claude mcp remove my-db

🧩 Example: project-level .mcp.json

{
  "mcpServers": {
    "mysql_prod": {
      "command": "npx",
      "args": ["-y", "@some-org/mysql-mcp-server"],
      "env": {
        "MYSQL_HOST": "${MYSQL_PROD_HOST}",
        "MYSQL_USER": "${MYSQL_PROD_USER}",
        "MYSQL_PASSWORD": "${MYSQL_PROD_PASSWORD}"
      }
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"]
    }
  }
}

⚠️ Never commit credentials

Reference secrets via environment variables (${MYSQL_PROD_PASSWORD}), not literal values, in any .mcp.json that gets committed to git. Local-only credentials belong in .env files or your shell profile, never in a tracked config file.

🔒 Permissions and safety

Every MCP tool call goes through the same permission system as built-in tools. You can:

• Require manual approval per tool call (default for new servers)
• Pre-allow specific tools in settings.json / settings.local.json, e.g. "mcp__github__create_issue" in the allow list
• Restrict a database MCP server to read-only queries at the server level (the safest approach — don't rely on prompting alone to prevent writes)

⚠️ Production database servers

If you connect an MCP server to a production database, prefer a read-only database user at the connection-string level. Don't depend on the AI "being careful" — enforce it at the infrastructure layer.

🚀 Common MCP servers in real projects

Server	Purpose
Filesystem	Read/write files outside the normal working directory sandbox
GitHub / GitLab	Issues, PRs, code search across repos the CLI doesn't have checked out
Database (MySQL/Postgres/etc.)	Query schemas and data directly instead of pasting SQL results
Slack	Read/post messages for status updates or incident coordination
Web fetch / browser	Fetch and read documentation pages, API references
Internal API gateways	Custom MCP servers wrapping a company's internal services

💡 Multiple environments, one name pattern

For projects with dev/test/UAT/prod databases, it's common to register one MCP server per environment (e.g. mysql, mysql_test, mysql_uat, mysql_prod) rather than one server with an environment parameter — this makes it visually obvious in tool calls which environment is being touched, reducing the chance of an accidental prod query.

🛠️ Writing your own MCP server

If no existing server covers an internal system, you can build one. At a high level, an MCP server:

1. Declares a set of tools (functions the AI can call, with a JSON schema for arguments)
2. Optionally declares resources (read-only data the AI can browse)
3. Runs as a local process (stdio transport) or a remote service (HTTP/SSE transport)

Official SDKs exist for TypeScript and Python, making it straightforward to wrap an internal API or database as a small MCP server your whole team can register in .mcp.json.

🎉 Result

Once configured, your AI assistant can query the actual staging database, open a real GitHub issue, or check the current state of an internal service — all without you manually fetching and pasting that data first.