How to add an MCP server to Claude Code

Claude Code gets its tools from MCP servers. This is the short, complete guide to adding them: the command, the scopes, authentication, sharing with a team, and the enterprise variant. For what MCP servers are, see What is an MCP server?; for which ones to add, see best MCP servers for teams and for marketing.

The command

Everything goes through claude mcp add. Two transports:

Remote server (HTTP). The vendor gives you a URL.

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

Local server (stdio). You give the command that starts it, after a -- separator.

claude mcp add --transport stdio filesystem -- npx -y @modelcontextprotocol/server-filesystem ~/projects

Environment variables for a local server go before the command with -e:

claude mcp add --transport stdio gsc -e GSC_SERVICE_ACCOUNT_FILE=~/.config/gcloud/gsc.json -- gsc-mcp

Useful companions:

claude mcp list          # every configured server and its status
claude mcp get hubspot   # details of one server
claude mcp remove hubspot

Scopes: local, project, user

Where a server is stored decides who gets it.

Use project for servers the whole team should have (the issue tracker, the docs, the internal API). Commit .mcp.json. Claude Code asks each person to approve project servers on first use, which is a sensible safety check against a malicious commit adding a server.

Use user for your personal tools. Use local when you are trying something out.

A project .mcp.json looks like this:

{
  "mcpServers": {
    "linear": { "type": "http", "url": "https://mcp.linear.app/mcp" },
    "db": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@bytebase/dbhub", "--dsn", "${DB_DSN}"]
    }
  }
}

Environment variable references like ${DB_DSN} are expanded at runtime, so secrets stay out of git.

Authenticating remote servers

Remote servers use OAuth. After adding one, start a session and run:

> /mcp

You get a list of servers with their connection status. Select the server, choose Authenticate, and a browser window opens for login. Tokens are stored securely and refreshed automatically. /mcp is also where you go when a server shows as disconnected.

Using the tools

Once connected, the server's tools appear to the model automatically. Ask for something that needs them and Claude Code proposes a tool call; you approve it the first time, and can choose "always allow" for read-only tools you trust. Prompts published by a server appear as slash commands. Resources can be referenced with @server:resource in your message.

Permissions for MCP tools are managed alongside other permissions: /permissions shows and edits what is allowed, and the same settings can be committed in .claude/settings.json for the team.

Troubleshooting

Local server fails to start. Run the exact command in your terminal. Nine times out of ten it is a missing binary, a wrong path or an unset environment variable.

Remote server disconnected. /mcp, authenticate again. Corporate proxies and TLS inspection can block the OAuth callback; set HTTPS_PROXY and trust the corporate certificate.

Tools do not appear. Check claude mcp list shows the server as connected, and that the session was started after you added it.

Too many tools. Each server's tool descriptions consume context on every turn. Forty servers is not a plan. Keep the project list to what the project needs.

The company version

claude mcp add per developer works for a team of five. Beyond that, servers, credentials and approvals need to live in one place. Claude Code supports two things that make this possible: enterprise-managed settings that can pin the allowed servers, and a configurable base URL that routes all traffic through a gateway.

With a gateway, every developer has one server configured, the gateway, and gets the approved servers through it with per-user policy, centrally held credentials and a full log. Walma AI Hub is that gateway for Claude Code, Codex and Cursor, running in the customer's own EU region. See What is an MCP gateway? or book a walkthrough.