How to connect MCP server in Claude Code

Issue #1008

Model Context Protocol (MCP) allows Claude Code to connect to external tools, databases, and services. See the official MCP documentation for more details.

Scopes and Configuration Storage

MCP servers have three scope levels that determine where configurations are stored. Read more about local scope, user scope, and project scope in the documentation.

Local scope (default): Private to you in the current project directory. Stored in ~/.claude.json under your project’s path. Perfect for experimental configurations or sensitive credentials.

User scope: Available to you across all projects. Stored in ~/.claude.json in the general mcpServers field. Ideal for personal utilities you use frequently across different work.

Project scope: Shared with your team via .mcp.json in the project root. Committed to version control so all team members get the same servers. Requires approval before use.

Example ~/.claude.json showing both user and local scope:

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp",
      "headers": {
        "Authorization": "Bearer ${GITHUB_TOKEN}"
      }
    }
  },
  "projects": {
    "/Users/khoa/my-project": {
      "mcpServers": {
        "atlassian": {
          "type": "http",
          "url": "https://mcp.atlassian.com/mcp"
        }
      }
    }
  }
}

In this example, github is user scoped (available everywhere) while atlassian is local scoped (only works in /Users/khoa/my-project).

Example .mcp.json for project scope:

{
  "mcpServers": {
    "atlassian": {
      "type": "http",
      "url": "https://mcp.atlassian.com/mcp"
    }
  }
}

Connecting to Popular MCP Servers

Atlassian

Add the Atlassian MCP server for Jira and Confluence access:

claude mcp add --transport http atlassian https://mcp.atlassian.com/mcp

Authenticate by starting Claude Code and running the /mcp command:

claude

Inside Claude Code:

/mcp

Select the authenticate option and follow the browser prompts to log in. After authentication, you can ask Claude to interact with your workspace, like “Show me all open issues in the ENG project” or “Create a new Jira issue for the login bug”.

GitHub

Create a GitHub Personal Access Token at GitHub Settings > Developer settings > Personal access tokens with repo scope. See the GitHub MCP server installation guide for detailed setup instructions.

Add the GitHub MCP server with your token:

claude mcp add-json github '{"type":"http","url":"https://api.githubcopilot.com/mcp","headers":{"Authorization":"Bearer YOUR_GITHUB_TOKEN"}}'

Replace YOUR_GITHUB_TOKEN with your actual token. If using an environment variable:

claude mcp add-json github '{"type":"http","url":"https://api.githubcopilot.com/mcp","headers":{"Authorization":"Bearer '${GITHUB_TOKEN}'"}}'

Verify the configuration:

claude mcp get github

Now you can ask Claude to interact with GitHub, like “Create a pull request for my current branch” or “Review PR 456”.

GitHub Enterprise

For GitHub Enterprise Cloud, we can follow Configuring the remote MCP server for GitHub Enterprise Cloud with data residency

"github-enteprise": {
    "type": "http",
    "url": "https://copilot-api.SUBDOMAIN.ghe.com/mcp",
    "headers": {
        "Authorization": "Bearer ACCESS_TOKEN"
    }
}

Local Figma

The Figma desktop app can act as local MCP server, following this guide Enable the desktop MCP Server

"figma-local": {
    "type": "http",
    "url": "http://127.0.0.1:3845/mcp"
}

Using Custom MCP Configuration Files

The --strict-mcp-config flag lets you specify a custom configuration file and ignore all other MCP sources. Useful for testing or CI environments. See the CLI reference for all available flags.

claude --strict-mcp-config --mcp-config ./custom-mcp.json

This loads only servers from ./custom-mcp.json, ignoring ~/.claude.json, .mcp.json, and managed configurations.

The configuration file format:

{
  "mcpServers": {
    "my-server": {
      "type": "http",
      "url": "https://api.example.com/mcp"
    },
    "another-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@example/mcp-server"],
      "env": {
        "API_KEY": "${MY_API_KEY}"
      }
    }
  }
}

You can specify multiple files. They will be merged, with the last file taking precedence for conflicts:

claude --strict-mcp-config --mcp-config ./mcp-1.json --mcp-config ./mcp-2.json

Managing MCP Servers

Use these commands to manage your MCP servers. See the CLI reference for more commands.

List all configured servers:

claude mcp list

Get details about a specific server:

claude mcp get server-name

Remove a server:

claude mcp remove server-name