How to Add an MCP Server to Claude Code (claude mcp add)

To add an MCP server to Claude Code, run claude mcp add in your terminal. For a remote server, the whole command is claude mcp add --transport http <name> <url>. Claude Code saves the entry, connects to the server, and you can check it with claude mcp list. This guide covers remote and local servers, auth headers, scopes, .mcp.json, and fixes.

claude mcp add --transport http mcpifex https://mcp.mcpifex.com/mcp \
--header "Authorization: Bearer mcpx_YOUR_API_KEY"

That is the MCPifex gateway with an API key in the header. Replace mcpx_YOUR_API_KEY with a key from the portal. Syntax below was checked against the Claude Code MCP documentation on Oct 30, 2026. For the broader picture of how Claude and MCP fit together, see Claude MCP explained.

How do I add a remote MCP server to Claude Code?

A remote server lives at a URL, so Claude Code needs the transport, a name you choose, and the URL. Run it from a normal terminal, not inside a running claude session:

claude mcp add --transport http <name> <url>

--transport http selects Streamable HTTP, the recommended transport for remote servers. The short flags are -t for transport, -H for header, -e for env and -s for scope. An older transport, sse, still exists but the documentation marks it deprecated, so use http wherever the server offers it. Claude Code tries HTTP first and switches to SSE when the server does not accept it, which needs Claude Code v2.1.265 or later. If you want the background on what a remote server is, read remote MCP server.

How do I add an MCPifex server to Claude Code?

MCPifex runs the MCP server for you and gives you one endpoint, https://mcp.mcpifex.com/mcp, for every server you set up. Create an instance in the portal, choose which tools are allowed, copy the API key, then run the command shown at the top of this page. The key starts with mcpx_. Claude Code sends it on every request in the Authorization header. Instance setup is covered in instances and tools and key handling in API keys and authentication. You can also start from the Claude connection page.

How do I pass an API key or token to a remote server?

Use --header and repeat it for each header the server needs:

claude mcp add --transport http secure-api https://api.example.com/mcp \
--header "Authorization: Bearer your-token"

Keep keys out of the URL where the server accepts a header. A key in a URL ends up in shell history, logs and screenshots. For servers that use OAuth instead of a static key, add the server without a header, then run /mcp inside a session to sign in, or run claude mcp login <name> from the shell.

How do I add a local (stdio) MCP server?

A stdio server runs as a subprocess on your machine. Claude Code starts it with the command you give. The -- separator matters here: everything before it belongs to Claude Code, and everything after it is passed to the server untouched.

claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
-- npx -y airtable-mcp-server

Two details trip people up. First, --env accepts several KEY=value pairs, so if the server name comes straight after --env, the CLI reads the name as another pair and rejects it. Put another option, such as --transport stdio, between them as above. Second, a local server needs its runtime (Node, Python or Docker) installed and kept up to date by you. If you would rather not do that, a hosted server avoids it. See build versus buy for MCP hosting.

What are the local, project and user scopes?

Scope decides where the entry is stored and who sees it. Set it with --scope (or -s) when you add a server.

ScopeLoads inShared with teamStored in

local (default)

Current project only

No

~/.claude.json

project

Current project only

Yes, through version control

.mcp.json in the project root

user

All your projects

No

~/.claude.json

claude mcp add --transport http mcpifex --scope user https://mcp.mcpifex.com/mcp \
--header "Authorization: Bearer mcpx_YOUR_API_KEY"

If the same server name exists in more than one place, Claude Code uses the highest-precedence entry whole and does not merge fields. The order is local, then project, then user, then plugin-provided servers, then claude.ai connectors. Use user for a server you want everywhere, local for a personal experiment, and project for a server your whole team should have.

What does a .mcp.json file look like?

Project scope writes to a .mcp.json file in your repository root. You can also write it by hand. Do not commit a real key. The file supports ${VAR} and ${VAR:-default} expansion in command, args, env, url and headers, so each teammate supplies the key from their own environment:

{
"mcpServers": {
"mcpifex": {
"type": "http",
"url": "https://mcp.mcpifex.com/mcp",
"headers": { "Authorization": "Bearer ${MCPIFEX_API_KEY}" }
}
}
}

Always include "type": "http" for a URL entry. An entry with a url and no type is read as a stdio server and fails. For safety, Claude Code asks you to approve project-scoped servers the first time it sees them in an interactive session. To reset those choices, run claude mcp reset-project-choices. If you already have the JSON for a server, claude mcp add-json <name> '<json>' adds it directly. Pass just the server object, not the mcpServers wrapper. Cursor and other editors use a similar file, covered in add an MCP server to Cursor.

How do I list, inspect and remove MCP servers?

claude mcp list # all servers with health status
claude mcp get mcpifex # details for one server
claude mcp remove mcpifex # delete a server
claude mcp login mcpifex # run the OAuth flow from the shell
claude mcp logout mcpifex # clear stored credentials

Inside a session, type /mcp to see status, authenticate, reconnect or switch a server off. Statuses read Connected, Needs authentication, Failed to connect, or Pending approval for project servers you have not approved yet. After you change a server, start a new session or reconnect from /mcp so Claude Code picks up the change.

Why won't my MCP server connect?

Start with claude mcp list, which shows which server failed and how. Then work down this list:

• Needs authentication or 401. The key is missing, mistyped or revoked. Check the header text for stray quotes or a missing Bearer prefix, then create a new key if needed.
• Failed to connect on an HTTP server. Confirm the URL ends in the path the server expects (MCPifex uses /mcp) and that you passed --transport http.
• URL entry treated as stdio. In .mcp.json, add "type": "http".
• Local server exits at startup. Run the command after -- by itself in the terminal to see its error. Missing runtimes and bad environment variables are the usual causes.
• Slow server times out at startup. Raise the startup timeout, for example MCP_TIMEOUT=10000 claude.
• Output is cut off. Tool output is limited to 25,000 tokens by default. Raise it with MAX_MCP_OUTPUT_TOKENS=50000 if you need larger results.
• Server missing after you added it. You may have added it at local scope in a different project folder. Run claude mcp list from the folder you expect, or re-add with --scope user.

More fixes for MCPifex endpoints are in the troubleshooting guide.

How do I control which MCP tools Claude Code can use?

Claude Code names every MCP tool mcp__<server>__<tool>, and you use those names in permission rules. According to the permissions documentation, mcp__puppeteer__* matches every tool from the puppeteer server, and a full name matches one tool. Add allow rules in .claude/settings.json to skip prompts for tools you trust, and deny rules for tools you never want called:

{
"permissions": {
"allow": ["mcp__mcpifex__query"],
"deny": ["mcp__mcpifex__execute"]
}
}

Tool names depend on the server and the name you chose when adding it, so check them in /mcp first. Permission rules apply inside Claude Code only. With MCPifex you can also restrict tools at the gateway, per instance, so a write tool stays off for every client that uses the key. New servers start with write tools disabled. Read more in controlling what AI agents can reach and the MCP security checklist.

Which MCP servers can I add to Claude Code first?

MCPifex has five hosted servers live today, and each one uses the same endpoint and command pattern:

• PostgreSQL: query, inspect and describe your database. The write tool is off by default.
• Google Search Console: 19 tools for performance, URL inspection, indexing and sitemaps.
• Google Trends: interest over time, related queries and trending searches. No credentials needed.
• App Store Connect: 88 tools for apps, TestFlight, reviews and reports. 38 write tools are off by default.
• WhatsApp: 61 tools for chats, contacts and messages, on the Pro plan and up.

Browse them in the marketplace. The Free plan includes 3 instances with no card. Outside MCPifex, the official Model Context Protocol site lists the open standard these servers follow, and the transports specification defines stdio and Streamable HTTP.

← Back to guides