Claude Code MCP Server Configuration: Complete Guide

One of the biggest misconceptions about Claude Code is that connecting an MCP server requires manually editing configuration files.

It doesn't.

Modern versions of Claude Code include built-in commands for adding, managing, inspecting, and removing MCP servers. In many cases, you can connect an MCP server without ever opening a JSON file. The CLI handles validation, configuration, and storage automatically, making the setup process much simpler and less error-prone than editing configuration files by hand.

This guide walks through the complete configuration process used by experienced Claude Code users.

By the end, you'll know how to:

• add local stdio MCP servers
• connect remote HTTP MCP servers
• import existing Claude Desktop servers
• configure project-specific servers
• understand .mcp.json
• configure authentication
• test the connection
• troubleshoot common configuration problems

Rather than focusing on theory, this guide follows the exact workflow most developers use in practice.

How Claude Code Discovers MCP Servers

Claude Code doesn't communicate directly with external APIs.

Instead, it discovers one or more configured MCP servers.

Those servers expose Tools, Resources, and Prompts that Claude can invoke automatically.

The architecture looks like this:

Claude Code
      │
      ▼
Configured MCP Server
      │
      ▼
Authentication
      │
      ▼
REST API / Database / SaaS

The important point is that Claude Code only needs to know how to reach the MCP server.

Everything else—including authentication, API calls, retries, validation, and business logic—is handled by the MCP server itself.

Step 1 — Decide Which Type of MCP Server You're Connecting to

Claude Code supports several MCP server types.

The two most common are:

Local stdio MCP Servers

These servers run as local processes.

Claude Code starts them automatically when needed and communicates using standard input and output.

Typical examples include:

• local development tools
• filesystem servers
• Git utilities
• custom internal tooling

Remote HTTP MCP Servers

Remote servers run independently and expose an HTTP endpoint.

Examples include:

• hosted SaaS integrations
• enterprise gateways
• cloud-hosted MCP servers
• shared team deployments

Remote servers are usually the preferred choice for production environments because multiple developers and AI clients can reuse the same deployment.

Step 2 — Add an MCP Server

The recommended approach is to use the Claude Code CLI.

For a local stdio server:

claude mcp add my-server \
  --command node \
  --args dist/server.js

For a remote HTTP server:

claude mcp add-json weather-api '{
  "type":"http",
  "url":"https://example.com/mcp"
}'

Claude Code validates the configuration and stores it automatically.

Afterwards, verify that the server was added:

claude mcp list

If you're configuring your own server rather than connecting to an existing one, see:

→ How to Connect Claude to Any API with MCP

To inspect a specific server:

claude mcp get my-server

Using the CLI instead of editing JSON manually reduces configuration mistakes and follows the workflow recommended in the official Claude Code documentation.

Step 3 — Understand Configuration Scopes

One of the most confusing aspects of Claude Code is that MCP servers can be configured at different scopes.

Choosing the correct scope makes collaboration much easier and avoids configuration conflicts between projects.

In general, Claude Code supports three common configuration levels:

User Scope

A user-scoped server is available across all of your local projects.

Typical examples include:

• GitHub MCP
• Slack MCP
• Notion MCP
• Xero MCP

If you're configuring one of these services, these guides will help:

→ GitHub MCP: Setup, Security, Tools and Production Guide

→ Slack MCP Server: Complete Guide

→ Xero MCP Server: Complete Guide

These servers become part of your everyday development environment.

Project Scope

Project-scoped servers are only available inside a specific repository.

This is usually the best choice when:

• the project depends on internal APIs
• environment variables differ between projects
• teammates should share the same MCP configuration

Project-level configuration makes onboarding significantly easier because everyone works with the same MCP servers.

Local Development Scope

Sometimes you only need an MCP server temporarily while developing or debugging.

For example:

• testing a new Tool
• experimenting with authentication
• validating Resources
• debugging Prompts

Once development is complete, the server can be removed without affecting other projects.

For more information about testing, see:

→ Test a Local MCP Server

Step 4 — Understanding MCP Configuration Files

Although the Claude Code CLI is the recommended way to manage MCP servers, you may still encounter JSON-based configuration in project repositories, examples, and shared development environments.

Depending on the workflow and Claude Code version, project-specific MCP configuration may be stored in files such as .mcp.json or managed through Claude Code itself. Understanding these configuration formats makes troubleshooting and collaboration much easier.

A typical configuration looks like this:

{
  "mcpServers": {
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-github"
      ]
    }
  }
}

Most configurations contain four core elements:

• transport type
• command
• arguments
• optional environment variables

Remote servers typically replace the command section with an HTTP endpoint.

HTTP Configuration

Example:

{
  "mcpServers": {
    "crm": {
      "type": "http",
      "url": "https://api.company.com/mcp"
    }
  }
}

Modern Claude Code also accepts streamable-http, which aligns with the current MCP transport specification.

Environment Variables

Never place secrets directly inside configuration files.

Instead, reference environment variables.

Example:

{
  "env": {
    "API_KEY": "${API_KEY}"
  }
}

This approach makes it possible to:

• rotate credentials
• keep secrets out of Git
• use different credentials across environments
• simplify CI/CD deployments

For larger deployments, combine this with your existing secrets manager or CI environment variables. Claude Code also supports defining environment variables through its settings, where appropriate.

Step 5 — Configure Authentication

Different MCP servers require different authentication methods.

The most common are:

API Keys

Ideal for:

• internal APIs
• development
• simple SaaS integrations

Keep API keys outside the configuration whenever possible.

OAuth

OAuth is common for:

• Slack
• GitHub
• Google Drive
• HubSpot
• Xero

Instead of storing permanent credentials, users authorize access through an OAuth flow.

If you're deploying OAuth-enabled servers, these guides may help:

→ Slack MCP Server: Complete Guide

→ Xero MCP Server: Complete Guide

HTTP Headers

Some hosted MCP servers expect authentication headers.

For example:

Authorization: Bearer YOUR_TOKEN

Claude Code supports passing headers through MCP configuration when required by the server implementation.

Step 6 — Verify the Configuration

After adding a server, don't immediately start using it for production work.

Verify that everything works correctly.

A practical validation workflow looks like this:

Add Server

↓

List Servers

↓

Inspect Configuration

↓

Start Claude Code

↓

Discover Tools

↓

Execute Safe Tool

↓

Verify Responses

↓

Use in Production

Before connecting the server to real workflows, check:

• authentication
• transport
• available Tools
• Resources
• Prompts
• latency
• error handling

For a deeper validation process, see:

→ MCP Inspector: Complete Guide

→ Test MCP Server Online

→ Verify Any MCP Server

These tools help you identify configuration mistakes before they become production issues.

Step 7 — Troubleshooting Common Configuration Problems

Most Claude Code MCP issues are not caused by bugs in Claude itself.

Instead, they usually come from small configuration mistakes.

The good news is that most problems can be diagnosed systematically.

Claude Code Cannot See My MCP Server

Symptoms:

• no Tools appear
• Claude ignores the server
• Tool discovery returns nothing

Possible causes:

• incorrect server registration
• invalid configuration
• server failed to start
• unsupported transport
• incorrect command path

Start by verifying the registered servers:

claude mcp list

Then inspect the server configuration:

claude mcp get my-server

If the server looks correct, verify that it actually starts without errors before troubleshooting Claude Code itself.

Server Starts, but No Tools Are Available

If Claude connects successfully but discovers zero Tools, the problem is usually inside the MCP server rather than Claude Code.

Verify:

• Tool registration
• initialize response
• tools/list implementation
• server logs

Testing with Inspector makes this much easier.

→ MCP Inspector: Complete Guide

Authentication Fails

Typical symptoms:

• Unauthorized
• Forbidden
• Invalid API Key
• OAuth errors

Check:

• API keys
• OAuth configuration
• environment variables
• token expiration
• HTTP headers

Most authentication failures originate from the API behind the MCP server—not Claude Code.

Environment Variables Are Missing

One of the most common deployment mistakes is assuming Claude automatically passes environment variables.

Always verify:

• variable names
• variable values
• shell configuration
• deployment environment
• Docker configuration

If the MCP server cannot read its environment variables, authentication usually fails before Tool execution begins.

HTTP Server Cannot Connect

Verify:

• HTTPS
• endpoint URL
• firewall
• reverse proxy
• TLS certificates
• server availability

You can also test the endpoint independently before connecting Claude.

→ Test MCP Server Online

Local stdio Server Fails to Start

Typical causes:

• incorrect executable
• missing dependencies
• wrong working directory
• invalid command arguments

Try running the command manually before connecting it to Claude Code.

If it doesn't work in the terminal, it won't work through MCP either.

Production Best Practices

Once your configuration works locally, you're ready to prepare it for production.

The following practices consistently lead to more reliable deployments.

Keep MCP Servers Small

Avoid exposing hundreds of endpoints.

Instead, expose focused business capabilities.

Examples:

✅ Search Customer

✅ Create Invoice

✅ Find Repository

Instead of:

❌ Generic API Wrapper

Smaller Tool sets improve discoverability and reduce model confusion.

Never Store Secrets in Configuration Files

Configuration files should describe servers—not contain credentials.

Store secrets in:

• environment variables
• cloud secret managers
• CI/CD secrets
• operating system credential stores

This keeps projects safer and makes collaboration much easier.

Test Before Every Deployment

Every production deployment should validate:

• initialize
• Tool discovery
• Resources
• Prompts
• Tool execution
• authentication
• error handling

Don't wait until Claude reports failures.

Test independently first.

Monitor Your MCP Server

Monitor:

• uptime
• response time
• Tool failures
• authentication failures
• API latency
• dependency health

Good monitoring dramatically reduces troubleshooting time.

Reuse Existing MCP Servers

Before building a custom integration, check whether one already exists.

Examples include:

• GitHub
• Slack
• Xero
• Linear
• Google Drive

Reusing proven MCP servers reduces maintenance while improving reliability.

Configuration Checklist

Before using an MCP server in Claude Code, verify:

✅ Server registered

✅ Transport configured

✅ Authentication working

✅ Environment variables available

✅ Tools discovered

✅ Resources available

✅ Prompts loaded

✅ Tool execution verified

✅ Logging enabled

✅ Health checks passing

✅ Monitoring configured

✅ Security reviewed

Related Guides

Continue learning with these guides:

• What Is an MCP Server?
• Claude MCP Setup Guide
• OpenAPI to MCP: Complete Guide
• How to Connect Claude to Any API with MCP
• TypeScript MCP Server Starter
• Test a Local MCP Server
• MCP Inspector: Complete Guide
• Test MCP Server Online
• Running MCP in Production
• How to Secure an MCP Server
• Verify Any MCP Server
• Production MCP Server Templates

Final Thoughts

Configuring an MCP server in Claude Code is no longer a matter of manually editing configuration files.

Modern Claude Code provides built-in commands for registering, managing, and inspecting MCP servers, making setup significantly easier while reducing configuration mistakes.

Whether you're connecting a local development server, a hosted enterprise gateway, or your own production API, the overall workflow remains the same:

1. Choose the appropriate transport.
2. Register the server.
3. Configure authentication.
4. Verify the connection.
5. Test Tool discovery.
6. Validate Tool execution.
7. Monitor the deployment.

Following this process results in integrations that are easier to maintain, more secure, and reusable across projects and teams.

Official References

This guide is based on the official Claude Code documentation, Anthropic documentation, and the Model Context Protocol specification.

• Claude Code MCP Documentation
• Model Context Protocol Documentation
• Model Context Protocol Specification
• Anthropic MCP Connector

Ready to Configure Your MCP Server?

Once your server is configured, don't stop there.

Validate that it behaves correctly before relying on it in production.

Use Test MCP Server Online for a quick compatibility check, or run a complete production assessment with Verify Any MCP Server.

If you're starting from scratch, explore the Production MCP Server Templates to build a secure, production-ready MCP server much faster.

Looking for production-ready MCP servers?

Browse the Verified MCP Directory to explore real deployments, compare security reports, and discover enterprise-ready MCP servers.