How to Add a Custom Connector in Claude (Apps and Claude Code)

Quick Answer: To add a custom connector in Claude, open Customize > Connectors in the Claude web or desktop app, click + then Add custom connector, paste the remote MCP server URL, click Add and sign in. In Claude Code, run claude mcp add --transport http <name> <url>, then sign in from /mcp (or with claude mcp login <name>) and check the status with claude mcp list.

The rest of this guide covers both paths properly, including the OAuth sign-in most hosted servers use, how to tell whether it worked, and the mistakes that make people think it didn't. Unorderly is the example connector throughout, but the steps are the same for any remote MCP server.

One warning up front. Claude's settings screens get renamed and moved around fairly often. Everything below comes from Anthropic's official documentation as of late September 2026, and each section links to its source. If a menu doesn't match what you see, trust the official custom connectors article over us.

What is a custom connector in Claude?

A custom connector is a remote MCP server that you add to Claude yourself, rather than one you pick from Anthropic's Connectors Directory. MCP (Model Context Protocol) is, in Anthropic's words, "an open standard, created by Anthropic, for AI applications to connect to tools and data." A remote MCP server is one that runs on the internet at a URL, rather than on your laptop.

Once connected, the server hands Claude a set of tools it can call during a conversation. Depending on the server, that might mean reading data, creating or changing records, or taking actions on your behalf. If you want the longer explanation of what sits behind that URL, we've written a separate explainer on what a remote MCP server is.

Anthropic's help centre is careful to separate two kinds of connection, and it's worth knowing which one you're dealing with:

• Remote connectors (including custom connectors) are cloud services you reach by URL. Anthropic's article on when to use desktop and web connectors says they work across all Claude surfaces: web, mobile, Cowork, Desktop and Claude Code.
• Desktop extensions and local MCP servers run on your own computer and are only available in Claude Desktop and Claude Code, not on the web or mobile.

This guide is about the first kind. If your server has a public https:// URL, you're in the right place.

Why this matters

Your agent is only as useful as what it can reach. Without connectors, Claude can reason and write, but it can't look anything up in your tools or put its results anywhere other than the chat window. A custom connector closes that gap for any service that offers an MCP server, not just the ones Anthropic has already listed.

It also changes how credentials work. With a well-built remote server, you don't paste API keys into a chat or a config file. You sign in through OAuth, approve access in the service's own login page, and Claude gets a token scoped to what you approved. Anthropic's help article puts it plainly: this "allows Claude to interact with the application on your behalf, without Claude ever seeing your actual password."

What you need before you start

Before you touch any settings, check you have the pieces below. Most failed setups trace back to one of these rather than to the steps themselves.

What you need	Claude apps (web and desktop)	Claude Code
The server's URL	A remote MCP server URL, reachable over the public internet	The same URL, reachable from the machine running Claude Code
An eligible plan or role	Custom connectors are listed for Free, Pro, Max, Team and Enterprise. Free is limited to one. On Team and Enterprise, only Owners can add them	A working Claude Code install that you've logged in to
An account with the service	Needed for the OAuth sign-in	Needed for the OAuth sign-in
OAuth client ID and secret	Only if the server asks for them (under "Advanced settings")	Only if the server doesn't support dynamic client registration (--client-id, --client-secret)
Where you'll use it	Switched on per conversation from the "+" menu	Chosen by scope: local (default), project or user

A note on plans, because it's the question people ask most. Anthropic's custom connectors article, last updated in August 2026, says: "Custom connectors using remote MCP are available on Claude, Cowork, and Claude Desktop for users on Free, Pro, Max, Team, and Enterprise plans. Free users are limited to one custom connector." That's the official position as we write this. Plan features change, so check the article if you're making a buying decision on it.

For the example connector, you'll need your Unorderly MCP URL, which is shown in the app. We'll write it as https://<your-unorderly-mcp-url> below. Swap in the real one from your account.

Step-by-step: add a custom connector in the Claude apps

These steps are for claude.ai in a browser and the Claude Desktop app, which share the same connector settings. They come straight from Anthropic's custom connectors article. The article frames them as the steps "for Pro and Max plans"; Team and Enterprise have an extra Owner step, covered after this list.

1. Open the connector settings. Go to Customize > Connectors (on the web, that's claude.ai/customize/connectors). If you can't find it, the settings layout has probably moved again. One of Anthropic's own articles still calls it "Settings → Connectors", so look for either.

2. Start a custom connector. Click +, then Add custom connector. This is different from browsing the directory: you're telling Claude about a server it doesn't already know.

3. Paste the server URL. Enter your connector's remote MCP server URL, for example https://<your-unorderly-mcp-url>. Copy it from the service rather than typing it; a stray space or a missing path segment is the most boring way to lose ten minutes.

4. Only use Advanced settings if told to. There's an optional Advanced settings link where you can enter an OAuth Client ID and OAuth Client Secret. Most servers built for Claude handle this for you, so leave it blank unless the server's own docs say otherwise. Unorderly is one of those: paste the URL, leave Advanced settings empty, and sign in and approve access when Claude asks.

5. Click Add, then connect and sign in. Click Add to save the connector. Anthropic notes that you'll "typically go through an OAuth authentication process to securely sign in to the application and grant specific permissions." If the connector shows a Connect button in the list, click it. A sign-in page from the service opens; for our example, you sign in with your Unorderly account and approve access.

6. Switch it on in a conversation. Connectors are enabled per chat. Click the + button in the lower left of the chat box, then Connectors, and flip the toggle for your new connector. Anthropic's article describes exactly this: "You'll see your configured connectors with toggles allowing you to enable/disable them per conversation."

7. Trim the tools you don't need. Anthropic suggests using the "Search and tools" menu to "disable any tools that aren't relevant to the current conversation or that you don't want Claude to be able to invoke." When Claude asks to use a tool, read the request. The help article's advice is to only click "Allow always" for a server and tool "that you trust to run unsupervised."

On a Team or Enterprise plan

On Team and Enterprise, members can't add custom connectors themselves. Per the same article, an Owner or Primary Owner goes to Organization settings > Connectors, clicks Add, hovers over Custom, selects Web, enters the remote MCP server URL (plus optional OAuth client details under Advanced settings) and clicks Add.

After that, each member goes to Customize > Connectors, finds the connector (it usually carries a "Custom" label) and clicks Connect to sign in with their own account. Anthropic's reasoning is that this "ensures that Claude can only access tools and data that the individual user has access to." Adding the connector for the organisation doesn't sign anyone in on their behalf.

What about the mobile app?

Connectors you've set up work in Claude on iOS and Android too. Anthropic's article on using connectors says installing connectors on mobile "is currently in beta" and that "Claude Desktop and web remain the primary path for custom connectors." So set it up on the web or desktop, then use it wherever you like.

Step-by-step: add a remote MCP server in Claude Code

Claude Code has its own MCP configuration, managed from the terminal. Everything here comes from Anthropic's Claude Code MCP reference and the MCP quickstart.

1. Add the server from your terminal. Run this in a normal shell, not inside a claude session:

claude mcp add --transport http unorderly https://<your-unorderly-mcp-url>

The general form is claude mcp add --transport http <name> <url>. The name (unorderly here) is one you make up; Claude Code uses it to label the server's tools and in commands like claude mcp remove. Anthropic's docs describe HTTP as "the recommended option for connecting to remote MCP servers." Names can only contain letters, numbers, hyphens and underscores.

2. Choose the scope. By default the server is added at local scope: private to you and active only in the current project. If you want it everywhere, add --scope user:

claude mcp add --transport http unorderly --scope user https://<your-unorderly-mcp-url>

Use --scope project only when you want to share the server with your team through a .mcp.json file in the repo. Claude Code will ask each person to approve project-scoped servers the first time it sees them.

3. Check the status. Run:

claude mcp list

For a server that uses OAuth, you'll see ! Needs authentication straight after adding it. The quickstart is explicit that this is expected: "the next step completes the sign-in."

4. Sign in from /mcp. Start Claude Code with claude, then type /mcp. Select your server, press Enter and choose Authenticate. Your browser opens to the service's sign-in page; sign in with your Unorderly account and approve access. Back in Claude Code, the server's status changes to connected.

5. Or sign in from the shell. If you'd rather not open a session, claude mcp login runs the same OAuth flow from your terminal:

claude mcp login unorderly

On a machine with no browser, such as over SSH, the command prints the authorisation URL instead. Open it on your own computer, then paste the full redirect URL back at the prompt. Anthropic notes you need an interactive terminal for that paste step (so connect with ssh -t), and you can force this mode with --no-browser.

6. Use it once, on purpose. Ask Claude for something that needs the server, and name the server in the prompt the first time. The quickstart suggests this so you know the answer came through the new server and not another tool. Approve the permission prompt if Claude Code asks, and look for tool calls labelled with the server name.

Two other options exist but you usually won't need them: --header "Authorization: Bearer <token>" for servers that use a static token instead of OAuth, and --client-id, --client-secret and --callback-port for servers that need pre-registered OAuth credentials.

Already added it in claude.ai? You might be done

There's a shortcut here that a lot of guides miss. The Claude Code docs say that if you're logged in to Claude Code with a claude.ai account, connectors you've added in claude.ai "are automatically available in Claude Code." Add and authenticate the connector in claude.ai, then run /mcp in Claude Code and it should appear with an indicator showing it came from claude.ai.

The catch: this only works when your active login is a claude.ai subscription. If you're using an ANTHROPIC_API_KEY, an apiKeyHelper, or a provider such as Amazon Bedrock, those connectors aren't loaded. The docs suggest running /status to confirm which authentication method is active.

How to check it worked

"I added it" and "it works" are different states, and the tools give you ways to tell them apart. Here's what the Claude Code status indicators mean, taken from the MCP quickstart:

Status in claude mcp list	What it means	What to do
✔ Connected	Ready to use	Nothing; try a prompt
! Needs authentication	Reachable, but needs a browser sign-in (or a token)	Authenticate from /mcp or run claude mcp login <name>
! Connected · tools fetch failed	Connected but couldn't list its tools	Run claude mcp get <name> for the error detail
✘ Failed to connect	The server didn't respond	Check the URL, then claude mcp get <name> for the issue line
✘ Connection error	The connection attempt threw an error	Check the URL and your network, then retry from /mcp

Inside a session, /mcp shows the tool count next to each connected server, which is a handy sanity check. If a server you expected has zero tools, something is off on the server side. The docs also note that when a connection fails, claude mcp get <name> shows an Issue: line with the HTTP status or error code.

In the Claude apps there's no status command, and Anthropic's article doesn't spell out a verification step. In practice, three signs tell you it's working:

• The connector no longer asks you to connect or sign in under Customize > Connectors.
• It appears with a toggle under + > Connectors in a chat.
• When you ask for something that needs it, Claude makes a tool call from that connector, and you can see it in the reply.

For the Unorderly example, a good first test is to ask your agent to set up a simple workspace and view. If the connector is live, you'll see calls to tools like get_setup_skill, create_workspace and put_surface, and the view shows up in the app the next time you open it or pull to refresh.

What good looks like

A healthy connector setup is quiet. You add the URL once per client, sign in once, and after that you mostly forget about it until you need to revoke access. Here's the checklist we'd use to call a setup done:

• The server URL is copied exactly from the service and uses https://.
• In Claude Code, claude mcp list shows ✔ Connected, at the scope you meant (usually user for a personal tool you want everywhere).
• In the Claude apps, the connector is connected, and you've switched it on only in the conversations that need it.
• You've read the permissions on the OAuth consent page rather than clicking through.
• You've disabled tools you don't want Claude calling, and you only use "Allow always" for tools you trust unsupervised.
• You know how to undo it: Remove under Customize > Connectors in the apps; claude mcp remove <name>, claude mcp logout <name> or Clear authentication in /mcp in Claude Code.

Worth knowing: removing a remote server in Claude Code also deletes the OAuth tokens it stored for it, and in the apps, editing a custom connector means removing it and adding it again.

Mistakes to avoid

Pointing Claude at a server only you can reach. In the Claude apps, the connection doesn't come from your computer. Anthropic's article says Claude connects "from Anthropic's cloud infrastructure, rather than from your local device", even in Claude Desktop, so the server "must be reachable over the public internet from Anthropic's IP ranges." A server on localhost, behind a VPN or on a private corporate network simply won't connect, however well it works in your own browser. The fix is to host it publicly or allowlist Anthropic's IP addresses.

Filling in Advanced settings or headers "just in case". Adding an OAuth client ID the server didn't ask for, or a --header "Authorization: ..." on top of an OAuth server, can break the sign-in. The Claude Code docs note that if you configured an Authorization header and the server rejects it, Claude Code "reports the connection as failed instead of falling back to OAuth." Leave these empty unless the server's docs tell you to use them.

Adding the server at the wrong scope. Claude Code's default local scope means the server exists only in the project you were in when you ran the command. Open another project and it's gone, which looks exactly like a broken setup. Use --scope user for personal tools, and don't define the same name at two scopes with different URLs; Claude Code will warn about the conflict, and you'll end up signing in twice.

Treating any MCP server as trustworthy. Custom connectors connect Claude to services "that haven't been verified by Anthropic." The help article warns that "malicious MCP servers may include hidden instructions that try to make Claude perform unintended actions", and that server developers can change tool behaviour without warning. Only connect servers from organisations you trust, and read what the consent page is asking for. If you're building your own server, Anthropic's building custom connectors docs are the place to start.

Forgetting to switch it on in the chat. In the Claude apps, adding a connector doesn't turn it on for every conversation. If Claude seems to ignore your shiny new connector, check the toggle under + > Connectors before you start debugging anything else.

What happens during the OAuth sign-in

You don't need to know this to add a connector, but it helps when something goes wrong. The MCP authorization specification defines the flow for HTTP-based servers, and it's built on OAuth 2.1.

In plain terms: Claude calls the server without a token, the server replies 401 Unauthorized and points to its authorisation server, and Claude opens your browser at the sign-in page. When you approve, Claude receives a token and sends it with every request. The spec says clients and servers "SHOULD support" dynamic client registration, which is why you usually don't need a client ID.

Two details from the spec explain behaviour you'll notice. First, PKCE is mandatory, which protects the sign-in redirect from being hijacked. Second, the token is bound to the specific server URL, so a token for one server can't be reused against another. That's also why the Claude Code docs say it stores OAuth sign-ins per endpoint: change the URL and you'll be asked to sign in again. Tokens are, per Anthropic, "stored securely and refreshed automatically", and if a refresh is rejected, Claude Code shows a notice pointing you to Re-authenticate in /mcp.

Custom connector vs Claude Code at a glance

If you use both, it's worth remembering where each setting lives:

Task	Claude apps (web and desktop)	Claude Code
Add the server	Customize > Connectors, then "+" and "Add custom connector"	claude mcp add --transport http <name> <url>
Sign in	Connect, then sign in on the service's page	/mcp then Authenticate, or claude mcp login <name>
Turn it on	Per conversation under "+" > "Connectors"	Available in every session at its scope
Check status	Look for the toggle and a tool call in a reply	claude mcp list, claude mcp get <name>, /mcp
Revoke or remove	Remove under Customize > Connectors	Clear authentication in /mcp, claude mcp logout <name>, claude mcp remove <name>

How Unorderly helps

Unorderly is a good first custom connector because the payoff is easy to see. It's an iPhone app (it adapts to iPad) where your agent publishes live dashboards: you add one remote MCP server URL to Claude, sign in once with your Unorderly account, and your agent can build workspaces and views from native widgets like KPIs, charts, tables, kanban boards, to-dos and approvals. No API keys get pasted into a chat.

Each view shows which agent wrote it and when, so you can check your agent's work on your phone instead of scrolling back through a chat log. Approvals you tap in the app go to your own webhook, which only you can set. If that sounds useful, our walkthrough on building a live dashboard with Claude picks up where this guide ends, and how it works covers the rest. Unorderly is pre-launch, with a waitlist, and free to start.

Frequently asked questions

How do I add a custom connector in Claude?

In the Claude web or desktop app, go to Customize > Connectors, click +, choose Add custom connector, paste the remote MCP server URL and click Add. Then connect and sign in, and switch the connector on for a conversation from the + menu. On Team and Enterprise plans, an Owner adds the connector first and members then click Connect.

Which Claude plans can use custom connectors?

Anthropic's help article, last updated in August 2026, says custom connectors using remote MCP are available on Free, Pro, Max, Team and Enterprise plans, and that Free users are limited to one custom connector. Plan details change, so check the official article before you rely on it.

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

Run claude mcp add --transport http <name> <url> in your terminal, outside a Claude Code session. Add --scope user if you want the server in every project rather than just the current one. Then run claude mcp list to see its status.

How do I sign in to an OAuth MCP server in Claude Code?

Start Claude Code, type /mcp, select the server and choose Authenticate. Your browser opens for the sign-in and you approve access there. You can also run claude mcp login <name> from your shell, and add --no-browser when you're on a machine without a browser, such as over SSH.

How do I know my custom connector is working?

In Claude Code, claude mcp list should show the server as ✔ Connected, and /mcp shows the tool count next to it. In the Claude apps, the connector should appear with a toggle under + > Connectors in a chat. In both, ask for something that needs the connector and look for a tool call from it in the reply.

Do I have to add the same connector twice to use it in Claude Code?

Not necessarily. Anthropic's Claude Code docs say that if you log in to Claude Code with a claude.ai account, connectors you added and authenticated in claude.ai are automatically available and show up in /mcp. That only applies when your active login is a claude.ai subscription, not an API key or a third-party provider.

Why won't my custom connector connect?

The most common reason in the Claude apps is that the server isn't reachable from the public internet, because Claude connects from Anthropic's cloud rather than your computer. In Claude Code, run claude mcp get <name> to see the error detail. An expired sign-in shows as needing authentication and is fixed by re-authenticating from /mcp.

Can I add Unorderly to Claude as a custom connector?

Yes. Unorderly gives you one remote MCP server URL, shown in the app. You add it as a custom connector in the Claude apps, or with claude mcp add --transport http in Claude Code, then sign in once with your Unorderly account. It's currently pre-launch with a waitlist; the FAQ has the details.