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:
- You configure an MCP server in your Claude Code settings
- Claude Code starts the MCP server when it needs the tool
- 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
- The MCP server translates the request into the tool's native API
- 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
MCP servers are configured in JSON files at different levels:
Project-Level Configuration
Create .claude/mcp.json in your project root:
\{
"mcpServers": \{
"postgres": \{
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost:5432/mydb"]
\}
\}
\}
This configuration is shared with your team through version control.
User-Level Configuration
For personal MCP servers, configure them in ~/.claude/mcp.json:
\{
"mcpServers": \{
"github": \{
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": \{
"GITHUB_TOKEN": "ghp_your_token_here"
\}
\}
\}
\}
Configuration Structure
Each MCP server entry has:
- command: The program to run (usually
npx,node, orpython) - args: Arguments passed to the command (the server package and its config)
- env (optional): Environment variables the server needs (API keys, tokens)
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
\{
"mcpServers": \{
"postgres": \{
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://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
\{
"mcpServers": \{
"sqlite": \{
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-sqlite", "path/to/database.db"]
\}
\}
\}
Project Management
GitHub
\{
"mcpServers": \{
"github": \{
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": \{
"GITHUB_TOKEN": "ghp_your_token"
\}
\}
\}
\}
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
\{
"mcpServers": \{
"linear": \{
"command": "npx",
"args": ["-y", "mcp-linear"],
"env": \{
"LINEAR_API_KEY": "lin_api_your_key"
\}
\}
\}
\}
Communication
Slack
\{
"mcpServers": \{
"slack": \{
"command": "npx",
"args": ["-y", "@anthropic/mcp-server-slack"],
"env": \{
"SLACK_BOT_TOKEN": "xoxb-your-token"
\}
\}
\}
\}
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", "@modelcontextprotocol/server-brave-search"],
"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:
- Queries the database for the current schema
- Creates the migration file
- Updates the TypeScript type definitions
- 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 user-level MCP config (~/.claude/mcp.json) for tokens, not project-level config.
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. The official @modelcontextprotocol/server-* packages are maintained by the MCP community.
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 correct location (.claude/mcp.json for project, ~/.claude/mcp.json for user).
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 configured in
.claude/mcp.json(project-level) or~/.claude/mcp.json(user-level) as JSON entries with command, args, and optional env fields - 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-level config or environment variables, never in committed project-level config
- Claude Code's permission system still applies to MCP tool calls, so you remain in control of what external actions are taken