Remote MCP servers: how to connect one, authenticate, and limit what it can do

A remote MCP server runs on someone else's infrastructure and speaks MCP's Streamable HTTP transport at a URL. Your client connects to it over the network, so there's nothing to install. If you haven't decided whether you want a remote server or a local one, local vs remote MCP servers covers the tradeoff.

I'll use Microsoft Learn's server at https://learn.microsoft.com/api/mcp for every step. Microsoft's overview page says "there's no authentication required", so you can follow along without an account.

Prerequisites

• Claude Code, Cursor or the Claude desktop app. I ran the Claude Code steps on 2.1.322.
• curl, for Step 1.
• For Claude Desktop: a claude.ai account. The Free plan allows one custom connector.

Step 1: Check that the server answers

Before you touch a client config, send the server an initialize request yourself. If this fails, no client will do better:

curl -s -X POST https://learn.microsoft.com/api/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}'

The reply comes back as a server-sent event. The parts that matter:

"protocolVersion":"2025-06-18"
"serverInfo":{"name":"Microsoft Learn MCP Server","version":"1.0.0"}

A 401 here with a WWW-Authenticate header means the server wants OAuth, which Step 5 covers. Opening the URL in a browser tells you nothing, since a GET can return 405.

Step 2: Add it to Claude Code

claude mcp add --transport http mslearn https://learn.microsoft.com/api/mcp
claude mcp get mslearn

mslearn:
  Scope: Local config (private to you in this project)
  Status: ✔ Connected
  Type: http
  URL: https://learn.microsoft.com/api/mcp

Add --scope project to write it to .mcp.json for the whole team instead. Claude Code then shows it as ⏸ Pending approval until each person approves it in a session. Adding MCP servers to Claude Code covers the scopes.

Step 3: Add it to Cursor

Cursor has no add command. Put the entry in ~/.cursor/mcp.json for every project, or .cursor/mcp.json for one:

{
  "mcpServers": {
    "mslearn": {
      "url": "https://learn.microsoft.com/api/mcp"
    }
  }
}

An entry with a url is a remote server. Quit and reopen Cursor if it doesn't appear under Customize. The Cursor tutorial has the rest of the file format.

Step 4: Add it to Claude Desktop

Claude Desktop doesn't take remote servers in claude_desktop_config.json. That file is for local servers. A remote server is a custom connector:

1. Go to Customize > Connectors.
2. Select Add, then Add custom connector.
3. Enter a name and the URL, then click Continue.
4. Keep any authentication option marked Detected. For a server with no login, like this one, the option is No sign-in.
5. Click Add.

On Team and Enterprise plans an Owner adds it under Organization settings > Connectors, and each member then clicks Connect. The steps are from Anthropic's custom connector docs. If you sign in to Claude Code with the same claude.ai account, it loads your connectors too, and claude mcp list shows them with a claude.ai prefix.

Step 5: Sign in with OAuth or an API key

Remote servers that need a login use one of two schemes. API keys vs OAuth covers which to prefer, and how MCP authorization works covers the OAuth flow itself.

OAuth. Add the server with no credentials. In Claude Code, run /mcp in a session or claude mcp login <name> from the shell, and a browser opens. Cursor runs the same flow when it connects. In Claude Desktop, pick Sign in now or Sign in when needed. If the provider makes you register a client first, pass it in: --client-id and --client-secret in Claude Code, an auth object with CLIENT_ID and CLIENT_SECRET in Cursor, and Use your own OAuth client in Claude Desktop.

An API key in a header. In Claude Code, use single quotes so your shell leaves the variable alone:

claude mcp add --transport http my-api https://mcp.example.com/mcp \
  --header 'Authorization: Bearer ${MY_API_KEY}' --scope project

That wrote the reference into .mcp.json unexpanded, and Claude Code fills it in from each person's environment at startup:

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

Cursor's syntax is "Authorization": "Bearer ${env:MY_API_KEY}" under headers. Claude Desktop has a Request headers section in the connector dialog, which Anthropic lists as a beta that not every organization has yet. It stores the value and sends it exactly as typed, so include the Bearer prefix.

Step 6: Limit the tools each agent can call

The Learn server has three tools. I asked Claude Code, in print mode, to list them:

mcp__mslearn__microsoft_code_sample_search
mcp__mslearn__microsoft_docs_fetch
mcp__mslearn__microsoft_docs_search

To take one away for a single run:

claude -p "..." --disallowedTools "mcp__mslearn__microsoft_code_sample_search"

The same prompt then listed only microsoft_docs_fetch and microsoft_docs_search. For a rule that lasts, put the name in permissions.deny in a settings file. For a subagent, list what it may use in its tools frontmatter, such as mcp__mslearn__microsoft_docs_search. In Claude Desktop, open the connector under Customize > Connectors and set a tool's permission to Blocked.

These limits live in the client. The server will still run every tool for anyone holding the URL and the key, and an agent started without the flag gets all of them. To make one rule hold across clients and agents, put a gateway between them and the server. In Statio you connect a remote server by URL and grant each person or agent the tools they need. Each agent signs in with its own token, and every call it makes is logged under its name. MCP permissions compares that with the other ways to limit tools, and the MCP allowlist tutorial covers blocking servers you haven't approved.

Conclusion

You checked a remote server with curl, connected it to three clients, set up both kinds of sign-in, and took a tool away from one agent.

To remove the test server from Claude Code, run claude mcp remove mslearn -s local.

• Local vs remote MCP servers, if you're still deciding which kind to run.
• MCP stdio vs Streamable HTTP for how the transport itself works.
• Debug an MCP server that won't connect when Step 1 fails.