Short answer: There are three ways to add an MCP server to Claude. Remote servers go into Claude on the web or desktop as a custom connector (Settings, Connectors, Add custom connector, paste the URL, sign in). Claude Code takes a remote server with one command, claude mcp add --transport http name url, plus a header for API-key servers. Local servers that run on your machine go into Claude Desktop's claude_desktop_config.json. This guide covers all three, with the exact menus and commands as of November 2026, then troubleshooting.
Updated November 2026. Avocado AI publishes this blog and runs a remote MCP server, which appears as the worked example in one section below. The steps come from Anthropic's documentation and apply to any server.
What is an MCP server, and why add one to Claude?
The Model Context Protocol is an open standard, created by Anthropic, that lets an AI application connect to tools and data. An MCP server is the piece that exposes those tools: "search my tickets", "read this database", "generate an image". Claude discovers the tool list when a chat starts, decides when a request needs a tool, and calls it. Without a server, Claude can only talk; with one, it can act.
Two kinds of servers exist, and the kind decides where you add it:
- Remote servers run on a URL and speak Streamable HTTP. They are added as connectors in Claude web and desktop, or with claude mcp add in Claude Code. Sign-in is usually OAuth; some use an API key sent as a Bearer header.
- Local servers run as a process on your computer and talk over stdio. They are added through Claude Desktop's config file or claude mcp add in Claude Code. The claude.ai web app cannot see them.
Anthropic's connector article states that remote connectors are brokered through your Claude account and connect from Anthropic's cloud, not your device, so the server must be reachable on the public internet.
Which Claude surface supports which kind of server?
| Claude surface | Remote server (URL) | Local server (process) | Where it is configured |
|---|---|---|---|
| claude.ai (web) | Yes, custom connector | No | Customize, Connectors |
| Claude Desktop | Yes, custom connector | Yes | Connectors for remote; claude_desktop_config.json for local |
| Claude mobile apps | Yes, same connectors as web | No | Synced from your account |
| Claude Code (terminal) | Yes | Yes | claude mcp add, .mcp.json, ~/.claude.json |
| Cowork | Yes | No | Connectors |
Source for the web, desktop, mobile and Cowork rows: Getting started with custom connectors using remote MCP. Source for the Claude Code row: Connect Claude Code to tools via MCP.
How do I add a remote MCP server to Claude web or desktop?
Custom connectors are available on Free, Pro, Max, Ultra, Team and Enterprise plans. Free accounts can add one custom connector. On Pro or Max:
- 1. Go to Customize, then Connectors. (Older builds label the first item Settings; it is the same screen.)
- 2. Click + Add, then Add custom connector.
- 3. Enter a name and the server's remote MCP URL, then click Continue.
- 4. Review the detected authentication settings and click Continue.
- 5. Under Authentication, choose Sign in now, Sign in when needed, or No sign in.
- 6. Under OAuth client, keep "Use Claude's published identity (Recommended)" unless the server's docs say otherwise.
- 7. If the server uses an API key or bearer token instead of OAuth, add it under Request headers.
- 8. Click Add, then sign in when prompted.
To use the connector in a conversation, click the + button at the lower left of the chat, choose Connectors, and switch the toggle on. Each connector has its own per-chat toggle.
On Team and Enterprise plans an Owner or Primary Owner adds the connector first under Organization settings, Connectors, Add, Custom, Web. Members then find it under Customize, Connectors and click Connect to sign in individually.
How do I add an MCP server in Claude Code?
Claude Code manages servers from the terminal with the claude mcp command. Anthropic recommends the HTTP transport for remote servers.
Remote server with OAuth:
claude mcp add --transport http notion https://mcp.notion.com/mcp
Then run /mcp inside Claude Code to complete the browser sign-in, or run claude mcp login notion from the shell.
Remote server with an API key or token:
claude mcp add --transport http secure-api https://api.example.com/mcp --header "Authorization: Bearer your-token"
Note the order: --transport before the name, and the name before the URL. If you set an Authorization header, a 401 or 403 is reported as a connection failure instead of starting an OAuth prompt, so remove the header if the server actually wants OAuth.
Local server (stdio):
claude mcp add --transport stdio myserver -- npx -y some-mcp-package
Everything after the double dash is the command that starts the server. Pass environment variables with --env KEY=value, and put another option such as --transport stdio between --env and the server name, or the CLI reads the name as a pair.
Scopes. --scope local (the default) keeps the server private to the current project in ~/.claude.json. --scope project writes it to .mcp.json in the repo root so your team gets it through version control. --scope user makes it available in all your projects. For project scope, reference secrets as ${API_KEY} in the headers and keep the real key in your environment; Claude Code expands ${VAR} and ${VAR:-default} in url, headers, command, args and env. A project-scoped .mcp.json entry looks like this:
{"mcpServers": {"shared-server": {"type": "http", "url": "https://example.com/mcp", "headers": {"Authorization": "Bearer ${API_KEY}"}}}}
Managing servers:
- claude mcp list shows every configured server and its status.
- claude mcp get name shows one server's details.
- claude mcp remove name removes it.
- /mcp inside a session shows status and lets you authenticate; /mcp reconnect all retries failed servers.
The SSE transport still exists but Anthropic marks it deprecated; on recent versions --transport http falls back to SSE automatically if the server does not accept HTTP.
How do I add a local MCP server to Claude Desktop?
Local servers are configured by editing a JSON file. The steps below are from the MCP quickstart for Claude Desktop users.
- 1. Install Node.js if the server needs it (most published servers run with npx).
- 2. Open the Claude menu in your system menu bar (not the settings inside the chat window) and choose Settings.
- 3. Open the Developer tab and click Edit Config. This creates or opens the file at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows, or ~/.config/Claude/claude_desktop_config.json on Linux.
- 4. Add the server under mcpServers. The quickstart's filesystem example, with your own paths:
{"mcpServers": {"filesystem": {"command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/username/Desktop", "/Users/username/Downloads"]}}}
- 5. Save, then quit and restart Claude Desktop completely.
- 6. Click the "Add files, connectors, and more" control at the lower left of the input box, hover Connectors, choose Manage connectors, and select the server to see its tools.
Paths must be absolute. Servers that need an API key take it in an env object inside the server entry. Each tool call asks for your approval before it runs.
Worked example: a remote image and video server in all three places
Disclosure: this is our server. We use it here because the setup is the same for any remote server that supports both OAuth and API keys, so you can see both paths side by side. The endpoint is https://mcp.avocadoai.co/api/mcp and it is included on every paid Avocado AI plan.
| Surface | What you do | Auth |
|---|---|---|
| Claude web or desktop | Customize, Connectors, Add custom connector, paste the endpoint, Add, sign in with your Avocado account | OAuth |
| Claude Code | claude mcp add --transport http avocado-ai https://mcp.avocadoai.co/api/mcp --header "Authorization: Bearer YOUR_KEY" | API key from your Avocado API keys page |
| Codex, Cursor, Windsurf, Hermes, any client | Add the endpoint under MCP servers with the same Bearer header | API key |
Once connected, Claude sees 60+ tools in five groups: generate (images, video, music, sound effects, speech), brand (extract and apply your Brand DNA), campaign canvas (Flows), publish (posts, scheduling and Meta Ads with the Connectors add-on) and account (credits, job status, a free models_list). A first prompt that shows the loop: "Generate a 9:16 TikTok ad of our protein powder on a gym bench, morning light." The image is saved to your workspace, and "now a 5 second Seedance 2.5 video from that" chains into generate_video. If you prefer a terminal, the Avocado CLI wraps the same tools.
Troubleshooting: tools not showing, auth loops and scopes
| Symptom | Likely cause | Fix |
|---|---|---|
| Connector added but Claude never calls it | The chat started before the connector existed, or the per-chat toggle is off | Start a new chat; click + at the lower left, Connectors, switch it on |
| Connector will not connect from claude.ai | The server is not reachable from the public internet (VPN, firewall, localhost) | Expose it publicly or allowlist Anthropic's IPs; local servers only work in Desktop and Claude Code |
| Sign-in page loops back without connecting | The server does not support OAuth, or Claude's published identity is not accepted | Re-add the connector with No sign in plus a Request header, or choose Register automatically under OAuth client |
| Claude Code: 401 after adding a token | Wrong key, trailing newline in the value, or a credential variable that reads as empty | Check the key, clean whitespace; note ANTHROPIC_API_KEY and similar names read as empty in a remote server's headers |
| Claude Code: "has a url but no type" | A JSON entry with a url and no transport | Add "type": "http" (or "sse") to the entry |
| Claude Code: Pending approval | A project-scoped .mcp.json server has not been approved | Run claude interactively and approve it, or reset with claude mcp reset-project-choices |
| Same server name behaves differently per project | The name exists in several scopes with different URLs | Remove the extras with claude mcp remove name --scope scope |
| Claude Desktop: server missing after restart | JSON syntax error, relative paths, or npx failing | Validate the JSON, use absolute paths, run the npx command by hand, read ~/Library/Logs/Claude/mcp*.log (macOS) or %APPDATA%\Claude\logs (Windows) |
| Tool calls fail silently | The server crashes on the call | Check mcp-server-NAME.log, rebuild the server, restart |
| Advanced research ignores a tool | Research cannot invoke local MCP servers and calls remote tools without approval | Use a remote server; disable write tools before research |
Two scope rules worth memorising for Claude Code. First, precedence when one name is defined in several places: local, then project, then user, then plugin-provided servers, then claude.ai connectors. Second, fields are not merged across scopes, so a header set at user scope does not apply to a project-scope entry with the same name.
Security checklist before you add any server
- Read the tool list after connecting. A server that asks for file or email access it does not need is a red flag.
- Never commit a real key. With --scope project, reference ${API_KEY} in .mcp.json and keep the value in your shell environment.
- Prefer OAuth for remote servers where it exists. You can revoke access in Claude's connector settings without rotating a key.
- Turn off write tools during research. Claude can call connector tools without asking during advanced research.
- Approve project servers knowingly. Project-scoped servers need interactive approval for a reason: someone else wrote that .mcp.json.
FAQ
What does "claude mcp add" do?
It registers an MCP server with Claude Code and stores it in a scope: ~/.claude.json for local and user scope, or .mcp.json in the repo for project scope. It accepts --transport http, sse or stdio, --header for request headers, --env for environment variables, and --scope to choose where it lives.
Can I add an MCP server to Claude on the free plan?
Yes. Anthropic's connector article lists Free among the supported plans, limited to one custom connector. Local servers in Claude Desktop and servers in Claude Code are not limited by plan.
Why do my tools only appear in new chats?
Claude loads a connector's tool list when a conversation starts. Add or change a server, then open a fresh chat.
Do remote connectors work in the Claude mobile app?
Yes. Remote connectors are tied to your Claude account and connect from Anthropic's cloud, so they are available on claude.ai, Claude Desktop, Cowork and the mobile apps. Local servers from claude_desktop_config.json are not.
Can one MCP server be shared with my whole team?
In Claude Code, use --scope project to commit a .mcp.json. On Claude Team and Enterprise, an Owner adds the connector once and each member signs in individually.
Which transport should a new server use?
Streamable HTTP for anything remote. SSE is deprecated in Claude Code, and WebSocket entries can only be added through add-json or .mcp.json.
Next step
Pick the surface you actually work in, add one server that solves a real job, and open a new chat. If that job is product images, video and voiceovers for a brand, the Avocado MCP server is a two-minute connector on every paid plan from Intro at 19.99 EUR a month.