MCP Servers: Connecting External Tools

Claude Code is powerful on its own, but its capabilities grow dramatically when you connect it to external tools and data sources through the Model Context Protocol (MCP). MCP is an open standard that lets Claude Code interact with databases, APIs, project management tools, and more, all through a consistent interface.

In this lesson, you will learn what MCP is, how to configure MCP servers, and how to use them to supercharge your Claude Code workflow.

What You Will Learn

• What MCP is and why it was created
• How MCP servers work with Claude Code
• How to configure MCP servers for your project
• Popular MCP servers and their use cases
• Practical examples with real MCP integrations
• Security considerations for MCP servers

---

What Is the Model Context Protocol?

The Model Context Protocol (MCP) is an open standard created by Anthropic that defines how AI assistants communicate with external tools. Think of it like a USB standard for AI tools: just as USB lets you plug any device into any computer, MCP lets you plug any tool into any AI assistant that supports the protocol.

Before MCP, connecting an AI tool to a database, a project management system, or a CI/CD pipeline required custom integrations for each combination. MCP standardizes this so:

• Tool developers create one MCP server that works with any MCP-compatible AI
• AI tools support MCP once and get access to any MCP server
• Users configure connections without writing code

How MCP Servers Work

An MCP server is a small program that sits between Claude Code and an external tool. Here is the flow:

1. You add an MCP server to Claude Code
2. Claude Code connects to the server. A local server runs on your machine, and a remote server is hosted by the tool's provider
3. When you ask Claude Code to do something that requires the external tool (like querying a database), it sends a request to the MCP server
4. The MCP server translates the request into the tool's native API
5. The result comes back through the MCP server to Claude Code

You do not interact with MCP servers directly. You just talk to Claude Code naturally, and it uses the appropriate MCP server when needed.

---

Configuring MCP Servers

The easiest way to add a server is the claude mcp add command. Remote servers use HTTP. Local servers run a program on your machine:

# Add a remote server
claude mcp add --transport http notion https://mcp.notion.com/mcp

# Add a local server. Everything after -- is the command to run
claude mcp add --transport stdio airtable --env AIRTABLE_API_KEY=YOUR_KEY -- npx -y airtable-mcp-server

Each server has a scope that decides where it is stored and who gets it:

Scope	Available in	Shared with team	Stored in
Local (default)	Current project	No	~/.claude.json
Project	Current project	Yes, through git	.mcp.json in the project root
User	All your projects	No	~/.claude.json

Choose one with the --scope flag. To check your servers, run claude mcp list in your terminal or /mcp inside a session. If a remote server needs you to sign in, /mcp also handles that.

Project-Level Configuration

Create .mcp.json in your project root, or run claude mcp add --scope project:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@bytebase/dbhub", "--dsn", "postgresql://readonly:${DB_PASSWORD}@localhost:5432/mydb"]
    }
  }
}

This configuration is shared with your team through version control. Claude Code asks each person to approve project servers before it uses them. The ${DB_PASSWORD} part is read from your environment, so the password stays out of git.

User-Level Configuration

For personal MCP servers, add them with claude mcp add --scope user, which stores them in ~/.claude.json:

claude mcp add --transport http github --scope user https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer YOUR_GITHUB_PAT"

Configuration Structure

A local (stdio) server entry has:

• command: The program to run (usually npx, node, or python)
• args: Arguments passed to the command (the server package and its config)
• env (optional): Environment variables the server needs (API keys, tokens)

A remote server entry has:

• type: The transport, usually "http"
• url: The server's address
• headers (optional): Extra headers, such as an authorization token

---

Popular MCP Servers

The MCP ecosystem has servers for many common tools. Here are some of the most useful ones for developers:

Database Servers

PostgreSQL

DBHub is an open source server that connects to many databases:

claude mcp add --transport stdio postgres -- npx -y @bytebase/dbhub --dsn "postgresql://readonly:pass@localhost:5432/mydb"

With this configured, you can ask Claude Code:

Show me the top 10 users by order count.
What is the schema of the orders table?
Write a migration to add a "status" column to the orders table.

Claude Code queries your database directly to answer these questions.

SQLite

DBHub also works with SQLite. Its documentation shows the connection string to use.

Project Management

GitHub

claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer YOUR_GITHUB_PAT"

With GitHub MCP, you can ask Claude Code:

What are the open pull requests on this repo?
Create an issue for the bug we just found.
Review the latest PR and leave comments.

Linear

claude mcp add --transport http linear https://mcp.linear.app/mcp

Then run /mcp in a session to sign in.

Communication

Slack

Slack runs an official hosted MCP server, and Claude Code is one of the clients it supports. Follow Slack's MCP documentation for the current setup steps.

File and Search

Filesystem (for accessing directories outside your project):

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

Web Search (Brave Search):

{
  "mcpServers": {
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@brave/brave-search-mcp-server", "--transport", "stdio"],
      "env": {
        "BRAVE_API_KEY": "your_api_key"
      }
    }
  }
}

---

Practical MCP Workflow Examples

Database-Driven Development

With a PostgreSQL MCP server configured:

Look at the users table schema. I need to add a
"notification_preferences" JSONB column with a default
value of email notifications enabled. Create the
migration and update the User type in TypeScript.

Claude Code:

1. Queries the database for the current schema
2. Creates the migration file
3. Updates the TypeScript type definitions
4. Ensures everything is consistent

GitHub-Integrated Workflow

With the GitHub MCP server:

Look at the open issues labeled "bug". Pick the oldest one
and start working on a fix. When done, create a pull request
that references the issue.

Claude Code reads the issues from GitHub, picks one, makes the code fix, creates a branch, commits the changes, and opens a PR.

Cross-Tool Integration

With multiple MCP servers configured, Claude Code can work across tools:

Check the latest Slack messages in the #bugs channel.
If there are any new bug reports, create GitHub issues
for them and add them to our Linear sprint.

---

Security Considerations

MCP servers can access external systems, so security is important:

API keys and tokens: Store them in environment variables or secure key stores, not in committed configuration files. Use the env field in a user-scope MCP server (added with claude mcp add --scope user) for tokens, not project-level config. If a project server needs a secret, reference it as ${MY_TOKEN} in .mcp.json so the value stays in your environment.

Database access: Use read-only database users for MCP servers when you only need to query data. Create a dedicated user with limited permissions.

Review server sources: Only install MCP servers from trusted sources. Prefer a hosted server from the tool's own provider when one exists. Check that a package is still maintained, because several older MCP packages have been archived.

Permission model: Claude Code's existing permission system applies to MCP tool calls too. You will be asked before Claude Code executes any MCP action that could modify data.

Network access: MCP servers may make network requests. Be aware of what data is being sent where, especially in enterprise environments.

---

Troubleshooting MCP Servers

Server fails to start: Check that the package is installed correctly and that the command path is valid. Try running the command manually in your terminal.

Authentication errors: Verify your API keys and tokens are correct and have not expired. Check that environment variables are being passed correctly.

Slow responses: MCP servers that connect to remote APIs depend on network latency. Local servers (like SQLite) are much faster.

Server not appearing: Make sure your .mcp.json file is valid JSON and in the project root. User servers live in ~/.claude.json. Run claude mcp list or /mcp to check status.

---

Key Takeaways

• MCP (Model Context Protocol) is an open standard that lets Claude Code connect to external tools through a consistent interface
• MCP servers are added with claude mcp add and stored in .mcp.json (project-level) or ~/.claude.json (user-level), as local entries (command, args, env) or remote entries (type, url)
• Popular MCP servers include PostgreSQL, GitHub, Slack, Linear, filesystem, and web search
• With MCP, you can query databases, manage GitHub issues and PRs, send Slack messages, and more, all through natural language
• Store API keys in user-scope servers or environment variables, never in a committed .mcp.json
• Claude Code's permission system still applies to MCP tool calls, so you remain in control of what external actions are taken