Connect a custom MCP server to Claude Desktop (step by step)

Local vs. remote — pick remote unless you have a reason

Most MCP tutorials wire up a local STDIO server: Claude Desktop spawns a process on your machine and talks to it over stdin/stdout. That works, but it is per-machine — every teammate repeats the setup, secrets live in local config files, and nothing works from a second device. A remote server over Streamable HTTP is one URL that every installation shares, with auth handled by OAuth instead of plaintext keys in a JSON file.

# Local (STDIO) — runs on your machine, per-machine setup
"command": "npx", "args": ["-y", "@your/mcp-server"]

# Remote (Streamable HTTP) — hosted, one URL for every machine
"url": "https://my-tools-a1.mcp.buildmymcpserver.com/mcp"

Step 1 — get a server URL

You need a live MCP endpoint. If you already run one, use its URL. If not, you can generate one from a prompt or fork a working one from the template gallery — either way you end up with an OAuth-protected URL like https://my-tools-a1.mcp.buildmymcpserver.com/mcp.

Step 2 — add the server to Claude Desktop

1. Open Claude Desktop settings and go to the connectors/MCP section (on recent versions: Settings → Connectors → Add custom connector), or edit claude_desktop_config.json directly.
2. Add the server entry:

{
  "mcpServers": {
    "my-tools": {
      "url": "https://my-tools-a1.mcp.buildmymcpserver.com/mcp",
      "auth": "oauth2"
    }
  }
}

3. Restart Claude Desktop. Config is read at startup, not live.

Step 3 — the OAuth flow on first use

The first time Claude touches the server it will receive a 401 — that is correct behavior, not an error. The client then discovers the authorization server, registers itself via Dynamic Client Registration, and opens a browser window for consent. You approve once; the client stores the token and refreshes it silently afterwards.

Under the hood this is the OAuth 2.1 handshake the MCP spec requires for remote servers: PKCE so the code exchange cannot be intercepted, and Resource Indicators (RFC 8707) so a token issued for this server cannot be replayed against another. Details in the OAuth documentation.

Step 4 — verify the tools are there

• Open a new conversation and check the tools/connectors icon — your server should be listed with its tools.
• Ask Claude directly: “Use the search_pages tool to find X.” Naming the tool forces Claude to attempt the call instead of answering from memory.
• Watch your server's dashboard logs — you should see the tool call arrive with latency and status.

Troubleshooting

One server, every client

The same URL works in Cursor, VS Code Copilot, Continue.dev and ChatGPT custom connectors — the point of hosting a remote MCP server is that the client config is the only per-client step left. If you hit a case this guide does not cover, the docs FAQ collects the rarer ones.