MCP Servers and Tool Integrations

Claude Code is powerful on its own, but its capabilities grow dramatically when you connect it to external tools and data sources. The Model Context Protocol (MCP) is the standard that makes this possible. In this lesson, you will learn what MCP is, how to configure MCP servers, and how to use them to connect Claude Code to databases, GitHub, and other services.

What You Will Learn

• What MCP is and why it exists
• How MCP servers work with Claude Code
• How to configure MCP servers in your project
• Popular MCP servers and what they do
• Practical examples: PostgreSQL and GitHub integrations
• Security considerations
• Troubleshooting common issues

---

What Is MCP (Model Context Protocol)?

The Model Context Protocol is an open standard created by Anthropic that defines how AI applications communicate with external tools and data sources. Think of it as a universal adapter system -- instead of building custom integrations for every service, MCP provides a single protocol that any tool can implement.

Before MCP, connecting an AI assistant to a database required custom code specific to that AI tool. With MCP, a PostgreSQL MCP server works with Claude Code, Claude Desktop, and any other application that supports the protocol.

The Key Concepts

MCP has three main concepts:

MCP Servers are programs that expose tools and data from external services. For example, a GitHub MCP server provides tools like "create issue," "list pull requests," and "read file contents."

MCP Clients are applications that connect to MCP servers and use the tools they provide. Claude Code is an MCP client.

Tools are the individual capabilities that an MCP server exposes. Each tool has a name, a description, and a set of parameters. Claude Code can invoke these tools just like it invokes its built-in tools (reading files, running commands, etc.).

How It Works in Practice

When you configure an MCP server for Claude Code:

1. Claude Code starts the MCP server process
2. The server announces what tools it provides
3. Claude Code adds those tools to its available capabilities
4. When you ask Claude Code to do something that requires an MCP tool, it calls the server
5. The server executes the action and returns the result

This all happens transparently. You simply ask Claude Code to do something, and it figures out which tools to use -- including MCP-provided ones.

---

Configuring MCP Servers

MCP servers are configured through JSON files. You have two options for where to put the configuration.

Project-Level Configuration

Create a .mcp.json file in your project root:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://localhost:5432/mydb"
      ]
    }
  }
}

This configuration is specific to the project and can be committed to your repository (be careful with connection strings that contain credentials -- more on security later).

User-Level Configuration

Create or edit ~/.claude/mcp.json:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

User-level servers are available across all your projects. This is ideal for personal tools like GitHub access that you want everywhere.

Configuration Format

Each MCP server entry has:

• Key (e.g., "postgres") -- A name you choose to identify this server
• command -- The executable to run (e.g., npx, node, python)
• args -- Command-line arguments passed to the executable
• env (optional) -- Environment variables to set for the server process

---

Popular MCP Servers

The MCP ecosystem has grown rapidly. Here are some of the most useful servers for developers.

Filesystem Server

Provides enhanced file system operations beyond what Claude Code has built in. Useful when you need controlled access to files outside your project directory.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/path/to/allowed/directory"
      ]
    }
  }
}

GitHub Server

Connects Claude Code to GitHub for managing repositories, issues, pull requests, and more.

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxxxxxxxxxx"
      }
    }
  }
}

Tools provided include creating issues, reading pull requests, managing branches, searching code, and more.

PostgreSQL Server

Gives Claude Code direct read access to your PostgreSQL database, allowing it to query schemas and data.

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://user:password@localhost:5432/dbname"
      ]
    }
  }
}

Slack Server

Connects Claude Code to Slack for reading messages, posting updates, and managing channels.

{
  "mcpServers": {
    "slack": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-slack"],
      "env": {
        "SLACK_BOT_TOKEN": "xoxb-your-token",
        "SLACK_TEAM_ID": "T0123456789"
      }
    }
  }
}

Sentry Server

Connects to Sentry for accessing error reports, stack traces, and issue data directly from Claude Code.

Linear Server

Connects to Linear for project management -- reading issues, updating status, and creating new tasks.

---

Example: Connecting to a PostgreSQL Database

Let us walk through a complete example of connecting Claude Code to a local PostgreSQL database.

Step 1: Ensure You Have a Running Database

Make sure PostgreSQL is running locally and you have a database to connect to:

# Check if PostgreSQL is running
pg_isready

# If using Docker
docker run -d \
  --name postgres-dev \
  -e POSTGRES_PASSWORD=devpassword \
  -e POSTGRES_DB=myapp \
  -p 5432:5432 \
  postgres:16

Step 2: Create the Configuration

Add to your project's .mcp.json:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://postgres:devpassword@localhost:5432/myapp"
      ]
    }
  }
}

Step 3: Restart Claude Code

MCP servers are loaded when Claude Code starts. After creating or modifying .mcp.json, restart your Claude Code session:

# Exit current session
> /quit

# Start a new session
claude

Step 4: Use It

Now you can ask Claude Code questions that involve your database:

> Show me the schema of the users table

> What are the most common values in the status column of the orders table?

> Write a migration to add an email_verified boolean column to the users table

> Find all orders from the last 7 days that have a total over $100

Claude Code uses the PostgreSQL MCP server to query your database and provide answers based on real data.

---

Example: Using the GitHub MCP Server

The GitHub MCP server is one of the most popular because it allows Claude Code to interact with your GitHub repositories directly.

Step 1: Create a Personal Access Token

Go to GitHub Settings > Developer settings > Personal access tokens > Fine-grained tokens, and create a token with the permissions you need (repository access, issues, pull requests).

Step 2: Configure the Server

Add to ~/.claude/mcp.json (user-level, since you want this across all projects):

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Step 3: Use It

With the GitHub MCP server configured, you can do things like:

> Create a GitHub issue titled "Fix login timeout bug" with a description
  of the problem we just debugged

> List all open pull requests on this repository

> Show me the comments on issue #42

> Create a pull request from this branch to main with a summary of
  the changes I have made in this session

Claude Code calls the GitHub MCP server behind the scenes, using the tools it provides to interact with the GitHub API.

---

Building Your Own MCP Server (Brief Overview)

If you need to connect Claude Code to an internal tool or service that does not have an existing MCP server, you can build your own. MCP servers can be written in any language, though TypeScript and Python have the best SDK support.

TypeScript Example (Conceptual)

An MCP server is a program that:

1. Implements the MCP protocol (using the @modelcontextprotocol/sdk package)
2. Defines one or more tools with names, descriptions, and input schemas
3. Handles tool invocations and returns results

# Install the MCP SDK
npm install @modelcontextprotocol/sdk

A minimal server defines tools and their handlers. Each tool has:

• A name (e.g., "query_inventory")
• A description that helps Claude Code understand when to use it
• An input schema (JSON Schema) defining what parameters it accepts
• A handler function that executes the tool and returns a result

The official MCP documentation at modelcontextprotocol.io provides complete tutorials for building servers in TypeScript and Python.

When to Build Your Own

Consider building a custom MCP server when:

• You have an internal API that Claude Code needs to access
• You want Claude Code to interact with a proprietary database or service
• No community MCP server exists for the tool you need
• You need custom business logic around how Claude Code accesses external data

---

Security Considerations

MCP servers can access external systems, so security matters. Here are the key concerns:

Credential Management

Never commit credentials directly in .mcp.json if the file is in your repository. Instead:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres"
      ],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    }
  }
}

Or keep credential-bearing configurations in your user-level ~/.claude/mcp.json which is not committed to any repository.

Principle of Least Privilege

When configuring MCP servers, grant only the permissions needed:

• Database servers: Use a read-only database user when Claude Code only needs to query data
• GitHub tokens: Scope tokens to only the repositories and permissions required
• File system servers: Restrict access to specific directories

# Create a read-only PostgreSQL user for Claude Code
psql -c "CREATE USER claude_readonly WITH PASSWORD 'readpass';"
psql -c "GRANT SELECT ON ALL TABLES IN SCHEMA public TO claude_readonly;"

Network Access

MCP servers run locally on your machine. They can make network requests to external services (APIs, databases). Be aware of what data flows through these connections, especially on shared or public networks.

Permission Prompts

Claude Code will ask for your approval before using MCP tools for the first time in a session. Always review what an MCP tool is doing before approving, especially for tools that can write data or make changes.

---

Troubleshooting MCP Connections

When an MCP server is not working, here are the steps to diagnose the issue.

Server Not Appearing

If your MCP server tools are not available in Claude Code:

1. Verify the .mcp.json file is valid JSON (no trailing commas, proper quoting)
2. Make sure you restarted Claude Code after adding the configuration
3. Check that the server command is installed and available on your PATH

# Test if the command works outside Claude Code
npx -y @modelcontextprotocol/server-postgres --help

Connection Errors

If the server starts but cannot connect to the external service:

1. Verify the connection string or credentials are correct
2. Test the connection independently:

# Test PostgreSQL connection
psql "postgresql://user:password@localhost:5432/dbname" -c "SELECT 1"

# Test that GitHub token works
curl -H "Authorization: token ghp_xxxx" https://api.github.com/user

3. Check that the external service is running and accessible

Using /doctor

The /doctor command can help identify MCP configuration issues:

> /doctor

This checks your configuration files and reports any problems it finds.

Check Server Logs

If a server starts but behaves unexpectedly, you can check for error output. MCP servers typically log errors to stderr, which Claude Code may surface in its error messages.

---

Combining MCP Servers

You can configure multiple MCP servers at once. They all become available to Claude Code simultaneously:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost:5432/myapp"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxx"
      }
    },
    "slack": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-slack"],
      "env": {
        "SLACK_BOT_TOKEN": "xoxb-xxxx",
        "SLACK_TEAM_ID": "T0123456789"
      }
    }
  }
}

With this setup, you could ask Claude Code something like:

> Check the database for any users who signed up in the last 24 hours,
  create a GitHub issue to track the onboarding email bug, and post
  a summary in the #engineering Slack channel

Claude Code orchestrates calls to multiple MCP servers to complete the task.

---

Summary

MCP (Model Context Protocol) is the standard that lets Claude Code connect to external tools and data sources through a server-based architecture. By adding a .mcp.json file to your project root or ~/.claude/mcp.json for global access, you can connect Claude Code to databases, GitHub, Slack, and dozens of other services. Each MCP server exposes tools that Claude Code can invoke naturally as part of your conversations. When configuring MCP servers, always follow the principle of least privilege and keep credentials out of version control.

In the next lesson, we will explore hooks -- a way to run automated actions in response to Claude Code events, enabling powerful workflows like auto-formatting and team convention enforcement.