How to Add a Remote MCP Server to Claude Code and Claude Desktop

The Model Context Protocol (MCP) is how Claude talks to external tools: databases, APIs, file systems, and services like ArtifactDeploy. This guide explains how to add a remote MCP server — one running on the internet rather than on your machine — to Claude Code and Claude Desktop, using ArtifactDeploy as a worked example.

Local vs. remote MCP servers

• Local (stdio) servers run as a process on your computer. Claude starts them and talks over standard input/output. Good for access to local files.
• Remote servers run as a web service. Claude connects over HTTP. Nothing to install or update, and they work across devices.

Remote servers today generally use the Streamable HTTP transport (the older HTTP+SSE transport is being phased out). Authentication is either OAuth — the client discovers the server’s sign-in flow automatically — or a token sent in a header such as Authorization: Bearer ….

Adding a remote server to Claude.ai (web, desktop and mobile)

Claude’s apps support remote servers as custom connectors, which authenticate with OAuth:

1. Open Settings → Connectors and choose Add custom connector.
2. Enter a name and the server URL — for ArtifactDeploy, https://mcp.artifactdeploy.com/mcp.
3. Click Connect. Claude registers itself with the server, opens the server’s sign-in page, and receives a token once you approve.
4. Enable the connector for a chat from the tools menu.

Connectors added on claude.ai also appear in Claude Desktop and mobile. Availability depends on your Claude plan, and on Team or Enterprise workspaces an owner may need to add the connector first.

Adding a remote server to Claude Code

Claude Code has a built-in command for this. For servers that support OAuth, add the URL and then run /mcp inside Claude Code and choose Authenticate:

claude mcp add --transport http --scope user artifactdeploy https://mcp.artifactdeploy.com/mcp

For servers that use a static token — or for headless machines where no browser is available — pass a header instead:

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

Choosing a scope

• --scope local (default): only you, only in the current project.
• --scope project: saved to .mcp.json in the repo so teammates get it too — don’t commit secrets; use environment variables instead.
• --scope user: you, in every project. Best for personal tools like deploy.

Checking it worked

Run claude mcp list in your terminal, or type /mcp inside Claude Code to see each server’s status and tools. Remove a server with claude mcp remove <name>.

Claude Desktop with a static token (advanced)

If a server supports OAuth, add it as a custom connector as described above. For servers that only accept a header token, Claude Desktop can reach them through the open-source mcp-remote bridge, which runs locally via npx and forwards requests to the remote URL.

1. Install Node.js 18 or newer.
2. Open Settings → Developer → Edit Config in Claude Desktop.
3. Add an entry under mcpServers:

{
  "mcpServers": {
    "artifactdeploy": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://mcp.artifactdeploy.com/mcp",
        "--header", "Authorization:${AUTH_HEADER}"
      ],
      "env": { "AUTH_HEADER": "Bearer YOUR_API_KEY" }
    }
  }
}

Putting the header value in env and referencing it as ${AUTH_HEADER} avoids problems with the space in “Bearer <token>” on Windows. Save, then fully quit and reopen Claude Desktop. A tools indicator appears in the chat input when the server is connected.

Security best practices

• Use one key per device or app so you can revoke a single one if it leaks.
• Never commit tokens to Git. For project-scoped config, reference environment variables.
• Review tool calls. Claude asks for permission before calling tools; read what it is about to send, especially for tools that delete or publish.
• Only connect servers you trust. A remote server sees whatever Claude sends to its tools.

Troubleshooting

With a server connected, try it: build something with Claude and say “deploy this”. The ArtifactDeploy docs list every tool and parameter.