How to add a custom connector to Claude, and fix it when it fails

A Claude connector lets Claude reach another app, read from it and act in it. Anthropic lists ready-made ones in its directory, and you can add any other service yourself if it runs a remote MCP server. That second kind is a custom connector. Adding one takes a couple of minutes, and this guide also covers what each error means when it doesn’t work.

The menu names here come from Anthropic’s help pages as of November 2026. If yours differ, Anthropic’s setup guide has the current ones.

What a connector is

Connectors run on the Model Context Protocol (MCP), an open standard for connecting AI apps to other systems. A service publishes an MCP server, and Claude calls the tools that server offers.

Anthropic’s overview explains the directory in more detail.

What you need

• The server’s URL, from the service’s own docs. It often ends in /mcp.
• A Claude account. Every plan can add custom connectors, and Free allows one.
• On a Team or Enterprise plan, an owner to add it for you.

Add a custom connector

1. Go to Customize → Connectors.
2. Press + Add, then Add custom connector.
3. Enter a name.
4. Paste the server URL and press Continue.
5. Check the authentication settings Claude detected, then press Continue.
6. Press Add.

Before the last step, Claude shows Authentication, OAuth client and Request headers. Leave them as they are unless the service tells you otherwise. Request headers are for a service that gives you an API key instead of a sign-in page.

If the service uses a sign-in, Claude sends you there to approve it. Read what you’re allowing, because that’s what Claude will be able to do.

On Team and Enterprise, an owner adds the connector once under Organization settings → Connectors: press Add, hover over Custom and pick Web. Each member then finds it under Customize → Connectors and presses Connect.

Switch it on in a chat

Adding a connector doesn’t turn it on everywhere. In a chat, press + at the lower left, open Connectors and use the toggle. You can turn each connector on or off for that conversation.

Claude Code works differently

In Claude Code, you add a server from the terminal:

claude mcp add --transport http NAME URL

Then run /mcp in Claude Code and follow the sign-in in your browser. The Claude Code docs cover keys and scopes.

The bigger difference is where the connection comes from. Claude Code connects from your machine, and claude.ai connects from Anthropic’s servers. That’s why a server can work in one and fail in the other.

ChatGPT has its own steps

The idea is the same, and the menus differ. On ChatGPT’s web app, open Plugins, press the plus button and choose Add custom MCP server. You accept a risk warning, then install the plugin before you use it. OpenAI’s guide has each step.

When it fails

Start with the message Claude shows you.

“Couldn’t reach the MCP server”

Claude couldn’t finish connecting. Despite the wording, this isn’t always a network problem.

• Check the URL against the service’s docs, character by character.
• A server on your own network or behind a VPN won’t work, even if you can open it yourself, because the connection comes from Anthropic.
• If the URL is right and the service isn’t yours, tell its support team. A firewall on their side may be blocking Anthropic’s servers.

“Authorization with the MCP server failed”

The sign-in started but didn’t finish. Disconnect the connector under Customize → Connectors and connect it again. If it keeps failing, the URL may redirect to another host, and Claude drops your credentials on that redirect. Ask the service for the exact URL to use.

“Unexpected error while invoking tool”

The connector is fine, and one tool call failed on the server. Try again, and check that your account in that service can do what you asked. If it still fails, send the service the tool name and the time it happened.

The connection times out

The server has to be reachable from the public internet. If yours sits behind a firewall, you can allow Anthropic’s IP addresses.

You can’t add a second connector

The Free plan allows one custom connector. Remove the one you have, or move to a paid plan.

You need to change the URL

You can’t edit a custom connector. Remove it and add it again.

Claude doesn’t use the connector

Check the toggle in that chat, as described above. Then ask for the service by name.

Reporting a failure

A failed connection puts a reference ID in the page address, starting with ofid_. Send it to the service soon after the failure, because it expires.

If you run the server

Anthropic’s troubleshooting guide has a full checklist, including what to do with an ofid_ ID. Test from a real client as well, because we hit two bugs connecting postmoderno that never showed up from the command line:

• A trailing slash. Our server advertised its address without one, the client sent it back with one, and an exact comparison refused it with invalid_target. Compare the canonical form of the URL, not the bytes.
• Origin: null. We sent Referrer-Policy: no-referrer, so the browser sent Origin: null on the consent form, and our origin check rejected it. curl sends whatever origin you give it, so only a browser showed the bug.

Test your connector explains how to try a local server in Claude, and the MCP Inspector lets you call your tools directly.

Keep it safe

Anthropic doesn’t verify custom connectors, and a connector can read, change or delete data, depending on what you allow. So add only servers you trust, read the permissions when you sign in, and save Allow always for tools you know.

Where to go next

If you want Claude to schedule your social posts, the setup guide connects postmoderno to Claude, ChatGPT and other clients. What an MCP post scheduler is explains how that works.

Writing the post yourself first? The free LinkedIn text formatter and X character counter run in your browser.

← all posts