How to Add an MCP Server to Claude Code (Step-by-Step Guide)

Introduction

Claude Code is designed to do more than just assist with coding, it can analyze entire codebases, plan multi-step changes, and execute tasks across files. But on its own, Claude Code is still limited to your local environment. Modern development workflows involve interacting with:

• Repositories
• Databases
• APIs
• Internal tools

This is where MCP (Model Context Protocol) servers come in. MCP allows Claude Code to connect to external systems and take actions beyond code editing, enabling workflows like:

• Pushing code changes
• Querying databases
• Running commands
• Triggering services

In other words, MCP transforms Claude Code from a coding tool into a full execution agent. However, setting up MCP servers in Claude Code can be confusing especially if you’re doing it for the first time. This guide walks you through exactly how to add an MCP server to Claude Code, step by step.

What You Need Before Getting Started

Before adding an MCP server to Claude Code, make sure you have the following in place.

Setting these up beforehand will save time and prevent common configuration issues.

1. Claude Code Installed and Working

Ensure Claude Code is installed and running correctly in your environment.

You should be able to:

• Open and navigate a codebase
• Run commands or prompts
• Access configuration settings

If Claude Code is not fully set up, complete that first.

2. An MCP Server (Local or Hosted)

Claude Code does not include MCP servers by default, you need to connect one. This can be:

• A local MCP server running on your machine
• A hosted MCP server (internal or third-party)

Common MCP servers include:

• GitHub (for repositories)
• Filesystem (for file operations)
• PostgreSQL (for databases)
• REST APIs (for services)

Start with one server that matches your use case.

3. Credentials and Access

Most MCP servers require authentication. You may need:

• API keys
• Access tokens
• Database credentials

Make sure:

• Credentials are valid
• Permissions are correctly scoped
• Sensitive data is stored securely

4. A Clear Use Case

Before adding an MCP server, decide what you want Claude Code to do.

For example:

• Manage code → GitHub MCP
• Query data → Database MCP
• Call services → API MCP

This helps you avoid unnecessary complexity.

5. A Safe Environment for Testing

It’s best to configure MCP servers in a development or staging environment first.

This allows you to:

• Test integrations safely
• Debug issues without risk
• Validate permissions and workflows

Once everything works, you can extend the setup to production.

How MCP Works in Claude Code

Before configuring anything, it helps to understand how MCP integrates with Claude Code. Claude Code is responsible for:

• Understanding your codebase
• Planning tasks
• Deciding what actions to take

MCP servers are responsible for:

• Executing those actions
• Interacting with external systems
• Returning results back to Claude Code

How the Flow Works

1. You define a task in Claude Code
2. Claude Code determines which tool (MCP server) is needed
3. The MCP server executes the request
4. Results are returned and used for the next step

For example:

• “Fix failing API and deploy”
  • Claude analyzes code
  • Uses MCP to run tests
  • Uses MCP to push changes
  • Uses MCP to trigger deployment

Step-by-Step: Add an MCP Server to Claude Code

Let’s walk through how to actually add and configure an MCP server.

Step 1: Set Up Your MCP Server

Before adding it to Claude Code, your MCP server must be running.

Depending on the server, setup may involve:

• Installing dependencies
• Running a service locally
• Setting environment variables

Example (Node-based MCP server):

npm installnpm start

Or using Docker:

docker run <mcp-server-image>

Make sure:

• The server is running
• You know the endpoint (URL/port)
• Required credentials are configured

Step 2: Open Claude Code Configuration

In Claude Code:

• Navigate to your configuration file or settings panel
• Locate the section for tooling / MCP / integrations

(Exact location may vary depending on setup)

Step 3: Add MCP Server Entry

You’ll now add a configuration entry that tells Claude Code how to connect to the MCP server.

Example Configuration

{
  "mcpServers": [
    {
      "name": "github",
      "type": "http",
      "url": "http://localhost:3000",
      "auth": {
        "type": "bearer",
        "token": "YOUR_API_TOKEN"
      }
    }
  ]
}

What Each Field Means

• name → Identifier used by Claude Code
• type → Connection type (HTTP/local)
• url → MCP server endpoint
• auth → Authentication details

Step 4: Configure Authentication

If your MCP server requires authentication:

• Add API keys or tokens
• Ensure permissions are correct
• Avoid exposing secrets in plain text

Depending on the server, this could include:

• Bearer tokens
• API keys
• OAuth credentials

Step 5: Test the MCP Server

Once configured, test the integration.

Try prompts like:

• “List repositories from GitHub”
• “Run tests in this project”
• “Fetch data from database”

If everything is working:

• Claude Code will call the MCP server
• You’ll receive a valid response

If not:

• Check logs
• Verify credentials
• Confirm endpoint is reachable

Common Issues and Fixes

1. MCP Server Not Reachable

Problem: Claude Code cannot connect

Fix:

• Ensure server is running
• Check URL/port
• Verify network access

2. Authentication Errors

Problem: Access denied or invalid token

Fix:

• Regenerate credentials
• Check permission scope
• Ensure correct auth format

3. Permission Failures

Problem: Server responds but actions fail

Fix:

• Verify access levels
• Check service permissions
• Adjust roles as needed

4. Configuration Errors

Problem: MCP server not recognized

Fix:

• Validate JSON syntax
• Ensure required fields exist
• Restart Claude Code if needed

Best Practices for Adding MCP Servers to Claude Code

Once you’ve connected MCP servers to Claude Code, the focus should shift to making your setup secure, reliable, and maintainable.

1. Start with Minimal Permissions

Avoid giving MCP servers unrestricted access.

Instead:

• Use scoped tokens
• Grant only required permissions
• Expand access gradually

This is especially important for:

• Production databases
• Deployment systems
• Internal APIs

2. Use Separate Environments

Always test MCP integrations in development or staging environments before production.

This allows you to:

• Validate configurations safely
• Debug without impacting live systems
• Refine workflows

Once stable, replicate the setup in production with stricter controls.

3. Validate Before Executing Critical Actions

Claude Code can execute multi-step workflows, but not all actions should run unchecked.

Best practices:

• Review planned changes
• Add validation steps for sensitive workflows
• Avoid full autonomy in high-risk environments

4. Monitor MCP Usage

Visibility is key when Claude Code interacts with multiple systems.

Track:

• Which MCP servers are being used
• What actions are executed
• How workflows behave over time

This helps with:

• Debugging
• Auditing
• Improving reliability

5. Keep Configurations Clean and Scalable

As you add more MCP servers, complexity grows.

To manage this:

• Use consistent naming conventions
• Organize configs clearly
• Document integrations

This ensures your setup remains maintainable as your system evolves.

Production Considerations: Scaling MCP Workflows

Setting up one MCP server is simple. Running multiple MCP-powered workflows in production is not.

1. Managing Multiple Integrations

As usage grows, teams integrate multiple MCP servers:

• GitHub
• Databases
• APIs
• Internal tools

Without structure, this leads to:

• Fragmented configurations
• Inconsistent access controls
• Hard-to-manage workflows

2. Enforcing Guardrails

Claude Code can execute powerful actions across systems.

Without proper controls, this introduces risks:

• Unintended changes
• Unauthorized access
• System instability

Teams need:

• Role-based access control
• Action-level restrictions
• Clear execution boundaries

3. Observability and Debugging

Debugging MCP workflows can be difficult without visibility.

You need to understand:

• What Claude Code attempted
• Which MCP server handled the request
• Where failures occurred

Without observability, troubleshooting becomes slow and unreliable.

4. Managing Models, Costs, and Performance

MCP workflows rely on underlying models.

At scale, teams must manage:

• Model selection (latency vs quality)
• Cost across repeated executions
• Performance bottlenecks

This requires centralized control.

Running MCP Workflows in Production with TrueFoundry

Getting an MCP server working locally with Claude Code is relatively straightforward. The real challenge begins when you try to run the same workflows across teams, environments, and production systems.

At that point, teams typically run into a few problems:

• Credentials are scattered across configs and environments
• There’s no clear control over what actions an agent can take
• Debugging failures across MCP calls becomes difficult
• Model usage and costs are hard to track or optimize

This is where a platform like TrueFoundry becomes useful—not as an add-on, but as a control plane for AI-driven workflows.

Centralizing MCP Access and Credentials

In most setups, MCP servers require API keys, tokens, or database credentials. These often end up:

• Hardcoded in configs
• Stored in environment variables
• Managed inconsistently across environments

With TrueFoundry, you can centralize how these credentials are managed and accessed, so:

• Secrets aren’t exposed in local configs
• Access is consistent across dev, staging, and production
• Rotations and updates are easier to handle

Defining What Agents Are Allowed to Do

Claude Code can execute real actions—pushing code, querying data, running commands.

In production, you don’t want every agent to have unrestricted access.

With TrueFoundry, you can define:

• Which MCP servers an agent can use
• What actions are allowed (read vs write, limited scopes, etc.)
• Where approvals or validations are required

This helps prevent situations where an agent:

• Modifies sensitive systems
• Executes unintended workflows
• Causes hard-to-revert changes

Observability Across MCP Calls

When something breaks in an MCP workflow, the hardest part is figuring out where it failed.

Was it:

• The model’s reasoning?
• The MCP server call?
• The downstream system?

TrueFoundry provides visibility into:

• Agent execution steps
• MCP server interactions
• Inputs, outputs, and errors

This makes it much easier to:

• Debug issues
• Audit behavior
• Improve workflows over time

Managing Models and Cost at Scale

Claude Code relies on underlying models, and MCP workflows often involve repeated calls.

As usage grows, teams need to:

• Route requests across models
• Balance cost vs performance
• Monitor usage across teams

TrueFoundry gives you a centralized way to:

• Control which models are used
• Optimize routing strategies
• Track and manage costs

From Local Setup to Team-Wide Workflows

What starts as a simple setup:

“Add MCP server → run task”

Quickly becomes:

“Multiple agents → multiple MCP servers → multiple environments”

TrueFoundry helps standardize this by providing a consistent way to:

• Configure integrations
• Enforce policies
• Scale workflows across teams

MCP lets Claude Code interact with systems.
TrueFoundry ensures those interactions are controlled, observable, and production-ready.

Conclusion

Adding an MCP server to Claude Code is what enables it to move from a powerful coding tool to something much more useful—an agent that can actually interact with your systems and execute real workflows.

With the right setup, Claude Code can go beyond editing code to:

• Push changes to repositories
• Query databases
• Call APIs
• Run commands and validate outcomes

But as soon as you start relying on these workflows beyond local experimentation, the challenge shifts. It’s no longer just about getting an MCP server to work, it’s about managing how these interactions happen across environments, systems, and teams.

That’s where platforms like TrueFoundry become important. They provide a way to bring structure to MCP-based workflows, handling access control, visibility, and scaling, so teams can use tools like Claude Code reliably in production. Ultimately, MCP is what unlocks capability, but the real value comes from how well you can operate and scale those capabilities in real-world systems.