Claude Code MCP Setup Guide: Config, Servers, Scopes

Quick setup

Claude Code can connect to remote HTTP servers and local stdio servers. For a remote server, use:

claude mcp add --transport http example-server https://example.com/mcp

Then verify the connection:

claude mcp list

Inside an interactive Claude Code session, run:

/mcp

The /mcp panel shows connection status, authentication requirements, and the tools exposed by each server.

The current official Claude Code MCP documentation recommends HTTP for remote cloud services. Local stdio remains appropriate for packages that need direct access to local files, processes, browsers, or development services. Legacy remote SSE is deprecated when an HTTP endpoint is available.

Claude Code MCP server types

Choose the transport based on where the capability must run. A hosted remote server is not automatically safer than a local package, and a local package is not automatically private: both can receive sensitive context and execute powerful tools.

Use the best MCP servers comparison to shortlist current provider and developer tools before installing a package from an old configuration example.

How to add an MCP server to Claude Code

Step 1: verify the server and its tools

Start with the provider's current documentation or source repository. Confirm:

• who operates or maintains the server
• whether it is local or remote
• which tools can read or change data
• which OAuth scopes, API keys, or backend credentials it receives
• how access is revoked
• whether unused tool groups can be disabled

The Anthropic Directory provides reviewed connectors, while the official MCP Registry provides broader metadata discovery. Neither removes the need to inspect the exact account, permissions, and tools enabled in your environment.

Step 2: choose the MCP scope

Claude Code has three user-configurable scopes:

Local is the default. Use project scope when the server definition belongs to the repository and can be safely shared without embedded credentials. Use user scope for a personal documentation or workflow server required across projects.

Scope controls where the server loads; it does not grant backend permissions. The connected SaaS account, API token, database role, and server-side policy remain separate boundaries.

Step 3: add a remote HTTP server

Use the server's remote MCP URL:

claude mcp add --transport http project-api https://api.example.com/mcp

To make the definition available to everyone using the repository:

claude mcp add --transport http --scope project project-api \
  https://api.example.com/mcp

For a fixed bearer token, add a header:

claude mcp add --transport http \
  --header "Authorization: Bearer YOUR_TOKEN" \
  project-api https://api.example.com/mcp

Do not commit a real token to .mcp.json. Prefer OAuth when the provider supports it, or reference an environment variable in a shared project configuration.

Step 4: add a local stdio server

For a local package, place Claude Code options before the server name and separate the executable with --:

claude mcp add --transport stdio local-tool -- \
  npx -y example-mcp-package

Everything after -- is passed to the local server. Without that separator, Claude Code may interpret the package's flags as its own options.

Local servers run with the authority of the current user and can inherit credentials or filesystem access from their environment. Pin a reviewed package version for team workflows and avoid running an unknown package against a production credential.

Step 5: authenticate

Remote HTTP servers commonly use OAuth or a fixed authorization header.

For OAuth, add the server without a token, open Claude Code, and run:

/mcp

Select the server and complete the browser login. Claude Code marks remote servers that return an authentication response in the /mcp panel so you can start the supported browser flow.

For API-key authentication, verify the header name and format against the server's current documentation. A 401 usually indicates a missing or rejected credential; a 403 can indicate either authentication or insufficient permission.

Step 6: verify before real work

Run:

claude mcp list
claude mcp get project-api

Then use /mcp to confirm the server is connected and inspect its tool count. Begin with a harmless read-only request. Name the server and action explicitly so the tool choice is easy to review.

For a write-capable server, request one operation that policy should deny. A successful read proves connectivity; a denied write proves that at least one important boundary is working.

Claude Code MCP config with .mcp.json

Project-scoped servers are stored in .mcp.json at the repository root. A remote HTTP server requires an explicit type:

{
  "mcpServers": {
    "project-api": {
      "type": "http",
      "url": "${PROJECT_MCP_URL:-https://api.example.com/mcp}",
      "headers": {
        "Authorization": "Bearer ${PROJECT_MCP_TOKEN}"
      }
    }
  }
}

Claude Code supports ${VAR} and ${VAR:-default} expansion in project configuration. Keep the endpoint definition in Git when it is safe to share, but inject credentials through each developer's environment or an approved secret-management workflow.

Do not omit "type": "http". A URL without a type can be interpreted as an invalid stdio definition rather than a remote server.

A local project server uses stdio fields:

{
  "mcpServers": {
    "local-tool": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "example-mcp-package"]
    }
  }
}

Claude Code asks users to approve project-scoped servers. A cloned repository cannot silently approve its own MCP configuration, but the user must still inspect the command, URL, environment references, and tools before accepting it.

Add a server with claude mcp add-json

Use add-json when a server requires fields that are easier to express as one JSON object:

claude mcp add-json project-api \
  '{"type":"http","url":"https://api.example.com/mcp","headers":{"Authorization":"Bearer YOUR_TOKEN"}}'

For a shared repository, use --scope project and remove fixed secrets before committing the resulting .mcp.json.

Claude Code MCP examples

GitHub MCP server

GitHub's hosted MCP endpoint can be added with a fine-grained personal access token:

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

Restrict the token to the required repositories and permissions. Reading code, creating issues, and merging pull requests should not receive the same default grant.

Hosted PostgreSQL or OpenAPI through datamcp

Full disclosure: datamcp is our product.

datamcp publishes a remote HTTP MCP endpoint for PostgreSQL 12+ or an OpenAPI 3.x / supported Swagger or Redoc source. Add a generated link to Claude Code with its API key:

claude mcp add --transport http \
  --header "Authorization: Bearer YOUR_DATAMCP_API_KEY" \
  app-source "https://api.datamcp.app/api/mcp/YOUR_CONNECTION_ID"

The backend credential remains on the datamcp connection rather than in Claude Code. For PostgreSQL, each link can be read-only, read-write, full-access, or custom by table and operation; the database role remains an additional boundary. PostgreSQL query activity and denied operations are available for review.

For OpenAPI, datamcp exposes four schema-aware tools for endpoint discovery, schema inspection, and approved calls. Read Only permits visible GET and HEAD operations; upstream API authorization remains responsible for resource and tenant access. OpenAPI calls do not currently appear in the datamcp activity log.

Use the Claude PostgreSQL MCP integration for the product path or OpenAPI to MCP for REST APIs.

For the complete database workflow, including PostgreSQL roles, datamcp link permissions, queries, denial tests, and a maintained local alternative, follow the Claude Code PostgreSQL MCP guide.

Claude Code MCP troubleshooting

Server does not appear

• Run claude mcp list and claude mcp get SERVER_NAME.
• Confirm the server was added from the intended project directory.
• Check whether the definition is local, project, or user scoped.
• Verify that .mcp.json has the root mcpServers object.
• For a remote entry, include "type": "http" or "type": "streamable-http".

Project server is pending approval

Open Claude Code interactively in the repository and accept the workspace trust and MCP approval prompts after reviewing the configuration. A project file copied from another repository should remain pending until the user approves it.

Local server fails to start

• Run the configured command directly in a terminal.
• Confirm node, npx, uvx, Docker, or another required runtime is installed.
• Keep Claude Code flags before the server name and package arguments after --.
• Check that required environment variables are available to the spawned process.
• Pin a working package version if a latest release changed its command or schema.

Remote server returns 401 or 403

• Open /mcp and complete or repeat OAuth authentication.
• Confirm the API key or bearer token has not expired or been revoked.
• Verify the header name and Bearer prefix.
• Check whether the authenticated account has the required provider scope.
• Remove a rejected fixed Authorization header if the server expects OAuth instead.

Server connects but tools are missing

• Inspect the server inside /mcp.
• Confirm the provider account can access the required project or resource.
• Check whether tool groups are disabled by server configuration or organization policy.
• Remove a duplicate server definition at a higher-precedence scope.
• Reconnect after changing OAuth scopes or backend permissions.

Claude Code MCP FAQ

How do I add an MCP server to Claude Code?

Run claude mcp add --transport http NAME URL for a remote HTTP server or claude mcp add --transport stdio NAME -- COMMAND ARGS for a local server. Then run claude mcp list and use /mcp inside Claude Code to authenticate and verify tools.

Where is the Claude Code MCP config stored?

Project-scoped configuration is stored in .mcp.json at the repository root. Local and user scopes are stored in ~/.claude.json; local entries are associated with the project where they were added, while user entries load across projects.

Does Claude Code use mcp.json or .mcp.json?

Claude Code uses .mcp.json with a leading dot for project-scoped servers. Cursor uses .cursor/mcp.json, so copying a file path between the two clients does not work even when the server definition itself is similar.

Should I use local, project, or user scope?

Use local for private experiments in one project, project for a reviewed secret-free definition shared with the repository, and user for personal tools needed across projects. Scope controls loading and sharing, not the server's backend permissions.

Can Claude Code connect to a remote MCP server?

Yes. Add a remote server with --transport http. Claude Code supports OAuth for compatible HTTP servers and fixed or dynamically generated request headers for other authentication schemes.

How many MCP servers should I add?

Start with the smallest set used in active workflows. GitHub plus documentation and one system of record is often enough. Add another server only when it removes a recurring context switch, and disable tools that the current project does not need.

For the next step, compare the best MCP servers for Claude Code, follow the Claude Code PostgreSQL tutorial, or connect a hosted PostgreSQL MCP server with one database and one MCP link on the Free plan.