MCP setup guide

Claude Desktop

Claude Desktop connects to remote MCP servers through Custom Connectors in Settings. The connection belongs to the Claude account, not to a project config file.

Paths checked against the client's docs · November 2026

Surfaces

macOS · Windows

Scope

Account connector

Settings configSettings > Connectors
Installer agentclaude-desktop
1 / How it works

How Claude Desktop handles MCP

Claude Desktop connects to remote MCP servers through Custom Connectors in Settings. The connection belongs to the Claude account, not to a project config file.

Account connector. This client has no project-level MCP path, so the setup writes the global config.

Best for

Chat workflows where you want the same remote tools in every conversation.

Installer flag-a claude-desktop
2 / Where it goes

Where the MCP config lives

The installer writes this file for you. Use the paths below when you want to inspect, edit, or remove a server by hand.

Settings
Settings > Connectors

Use Add custom connector for a remote MCP server.

Paths are per user, not per project. On Windows, ~ means your user folder; use %USERPROFILE% in Explorer or PowerShell.

3 / Install

Add a custom connector

Claude Desktop adds remote servers through Settings, not through a terminal command. Use the hosted endpoint from the server page.

  1. 01

    Find the endpoint

    Open a server page and copy its hosted endpoint. Do not use a local command or an npm package name for a remote server; those are different connection types.

    Open the MCP directory
  2. 02

    Add the connector

    Open Claude Desktop, choose Settings, open Connectors, and select Add custom connector. Paste the hosted endpoint. Complete the provider sign-in when asked.

    Open Claude settings

    Claude Desktop uses account-level Custom Connectors. The server is not stored in a project JSON file.

    1. 1
      Open Claude Desktop and sign in

      Use the account that should own the connector. Connectors follow that account across chats.

    2. 2
      Open Settings, then Connectors

      Select Settings from the app menu. In Settings, choose Connectors or Customize to see the installed connectors.

    3. 3
      Choose Add connector, then Add custom connector

      Select Add connector in the Connectors toolbar, then choose Add custom connector. If the app shows a connector store instead, use the custom connector option rather than a prebuilt listing.

    4. 4
      Enter the name and remote MCP URL

      Give the connector a recognizable name and paste the provider's hosted MCP endpoint. Use the Streamable HTTP endpoint shown on the server page.

      Remote MCP endpoint
      https://mcp.example.com/mcp
    5. 5
      Complete sign-in and verify the tools

      Finish the provider sign-in if Claude opens a browser. Return to a chat, open the connector menu, and confirm that the expected tools appear. If Claude asks before a tool call, approve only the tools you need.

    If you use more than one Claude account, add the connector separately to each account. Removing the connector from the account removes it from that account's chats.

    Claude Desktop Add custom connector dialog with cloudflare-code-mode and the MCP server URL filled in.Open larger view
    Open Settings, choose Connectors, use Add connector, then Add custom connector. Enter a name and the remote MCP URL, then select Continue.View full size

    The Add custom connector dialog opens with fields for the connector name and MCP server URL.

    If Add connector is missing, update Claude Desktop. Remote MCP servers are account connectors, not entries in claude_desktop_config.json.

    Full screenshot
    Claude Desktop Add custom connector dialog with cloudflare-code-mode and the MCP server URL filled in.
  3. 03

    Authorize if the provider asks

    The first connection may open a browser for OAuth. Sign in with the provider and approve only the scopes you need. If the server uses an API key, create it in the provider's dashboard and add it through the client's auth flow or config.

    Never paste a provider token into a project config you will commit. Prefer the client's secret store or a user-level config for credentials.

  4. 04

    Reload and verify

    Open Settings, choose Connectors, and confirm the custom connector shows its tools.

    Then ask for a task, not a tool: “Find the open issues assigned to me” or “Summarize the latest release.” The client decides which advertised tool to call.

4 / Use

What changes in the chat

Once the server is connected, its tools appear in the client's tool list. You still talk to the agent normally; MCP is plumbing, not a different chat interface.

Read

“Find the customer notes mentioning the migration and summarize the blockers.”

Write

“Create a draft page with this outline, but do not publish it yet.”

Investigate

“Check the failed deployment and list the last three changes that touched it.”

Verify

“Which MCP tools do you have available for this task?”

If the agent ignores the server, check that the server is enabled and that its tools are approved. Some clients require a per-tool confirmation before the first call.

5 / Troubleshooting

When it does not connect

The server is missing

Confirm the file exists at the path above, the JSON or TOML is valid, and you restarted the client or opened a new session.

It connects but tools are empty

Enable the server in the client's MCP UI, approve its tools, and check that the provider has not revoked your token.

OAuth keeps reopening

Remove the server from the client, revoke the app's access in the provider's account settings, then add it again.

A project server is ignored

Some clients require you to trust the folder before loading project MCP config. Trust the repository, then start a new session.

6 / Notes

What to watch for in Claude

  • Remote MCP servers in Claude Desktop use Custom Connectors, not claude_desktop_config.json.
  • Claude may ask you to sign in to the provider before the first tool call.
  • Return to a chat and open the connector menu to confirm the tools.
7 / Remove

Remove or reset the server

Remove the server when it is no longer needed, or reset it when a credential or connection state gets stuck.

  1. Open Settings, then Connectors.
  2. Find the custom connector and choose Remove or Disconnect.
  3. Return to a chat and confirm that the connector's tools are gone.

Remove the connector, sign out and back in if the connection stays stale, then add it again.

Sources

Official documentation

Client behavior changes. These links are the source of truth for paths, flags, and approval behavior.

Next setup guideCodex