Test your connector changedconnectors/building/testing
Nearest release: v2.1.283, published under an hour after upstream edited the page. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Upstream edited this page at 25 Sep 2026 18:00 UTC, give or take a minute or two: the time comes from Anthropic’s own sitemap rather than from a commit. This site recorded the change at 22 Oct 2026 18:07 UTC.
Upstream edited
Recorded here
Lines+10added
Lines−10removed
From line
4
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits4to this page, all time
The whole hunk
from line 4, old and new numbered
/
from line 4
44
55You test an MCP server against the real Claude client by adding it to Claude as a custom connector. There is no separate staging environment, so you test in production. Custom connectors use the exact same runtime as directory connectors, and what works as a custom connector will work after publication.
66
7This page is for developers with a running server, whether it's deployed or still on your machine. It covers adding the server to Claude, validating it with MCP Inspector, detecting Claude as the client, and preparing test credentials for directory review. If a connection fails while you test, [Troubleshoot your connector](/docs/connectors/building/troubleshooting) walks through each error message.
7This page is for developers with a running server, whether it's deployed or still on your machine. It covers adding the server to Claude, validating it with MCP Inspector, detecting Claude as the client, and preparing test credentials for directory review. If a connection fails while you test, [Troubleshoot your connector](/docs/connectors/building/troubleshooting.md) walks through each error message.
88
99## Test in Claude as a custom connector
1010
11To test your server the way users will reach it, add it to your own Claude account as a custom connector by its URL. Any Claude account can do this, on Free, Pro, Max, Team, or Enterprise; [Add a connector that isn't in the directory](/docs/connectors/custom/add-unlisted#add-a-connector-by-url) has the steps for each plan, starting from [**Customize > Connectors**](https://claude.ai/customize/connectors).
11To test your server the way users will reach it, add it to your own Claude account as a custom connector by its URL. Any Claude account can do this, on Free, Pro, Max, Team, or Enterprise; [Add a connector that isn't in the directory](/docs/connectors/custom/add-unlisted.md#add-a-connector-by-url) has the steps for each plan, starting from [**Customize > Connectors**](https://claude.ai/customize/connectors).
1212
1313Once the connector is added, check these:
1414
1515* **The connection**: the connector shows **Connected** under **Your connectors**. If it shows **Connect** or **Reconnect** instead, sign-in didn't finish, and [Debug connection failures](#debug-connection-failures) covers the usual causes
1616* **Your tools**: open the connector's page and look under **Tool permissions**. Every tool your server advertises should be listed with the name and description you gave it, because those are what Claude reads when it decides to call a tool
17* **A real call**: in a chat, turn the connector on from **+ > Connectors**, ask for something that needs one of your tools, and approve the call when Claude asks. Confirm on your server that the request arrived with the arguments you expected, and in Claude that the result reads well. [Use the connector in a conversation](/docs/connectors/getting-started#use-the-connector-in-a-conversation) shows what the user sees at each point
17* **A real call**: in a chat, turn the connector on from **+ > Connectors**, ask for something that needs one of your tools, and approve the call when Claude asks. Confirm on your server that the request arrived with the arguments you expected, and in Claude that the result reads well. [Use the connector in a conversation](/docs/connectors/getting-started.md#use-the-connector-in-a-conversation) shows what the user sees at each point
1818
1919### Test a local server
2020
2121Claude reaches your server from Anthropic's infrastructure, so a server running on your machine needs a public URL. Expose it with a tunnel such as [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/) or `ngrok`, then add the tunnel URL as a custom connector. This is the recommended pattern for iterating on MCP Apps as well.
2222
23If your server uses the TypeScript SDK's `createMcpExpressApp()`, as the [quickstart server](/docs/connectors/building/quickstart) does, its DNS rebinding protection accepts only `localhost`, `127.0.0.1`, and `[::1]` in the `Host` header. A request that arrives with the tunnel's hostname in that header gets `403` with `Invalid Host: <hostname>`, and the connection fails. While you test through the tunnel, pass the tunnel's hostname in `allowedHosts`, replacing `abc123.example.com` with your tunnel's hostname:
23If your server uses the TypeScript SDK's `createMcpExpressApp()`, as the [quickstart server](/docs/connectors/building/quickstart.md) does, its DNS rebinding protection accepts only `localhost`, `127.0.0.1`, and `[::1]` in the `Host` header. A request that arrives with the tunnel's hostname in that header gets `403` with `Invalid Host: <hostname>`, and the connection fails. While you test through the tunnel, pass the tunnel's hostname in `allowedHosts`, replacing `abc123.example.com` with your tunnel's hostname:
2424
2525```js theme={null}
2626const app = createMcpExpressApp({ allowedHosts: ['localhost', '127.0.0.1', 'abc123.example.com'] });
from line 58
5858
5959Use server-side logging on your end and the MCP Inspector to diagnose connection failures. An `initialize` timeout commonly has one of these causes:
6060
61* **Slow OAuth endpoints**: keep discovery, registration, and token responses under ten seconds, as described in [endpoint latency](/docs/connectors/building/authentication#endpoint-latency)
61* **Slow OAuth endpoints**: keep discovery, registration, and token responses under ten seconds, as described in [endpoint latency](/docs/connectors/building/authentication.md#endpoint-latency)
6262* **Strict `Origin`-header validation**: an overly strict check rejects Anthropic's requests
6363* **Firewalls**: a firewall drops Anthropic's egress traffic
6464
65If your infrastructure logs show `403 Forbidden` responses your application didn't generate, your CDN or WAF is likely blocking Anthropic's traffic. See [firewall or WAF blocks traffic from Anthropic](/docs/connectors/building/troubleshooting#firewall-or-waf-blocks-traffic-from-anthropic) for the fix.
65If your infrastructure logs show `403 Forbidden` responses your application didn't generate, your CDN or WAF is likely blocking Anthropic's traffic. See [firewall or WAF blocks traffic from Anthropic](/docs/connectors/building/troubleshooting.md#firewall-or-waf-blocks-traffic-from-anthropic) for the fix.
6666
67For a structured walkthrough of the "Couldn't reach the MCP server" and "Authorization failed" errors, see [Troubleshoot your connector](/docs/connectors/building/troubleshooting). It includes DNS resolution checks, OAuth discovery diagnostics, and how to find the `ofid_` reference ID to include in a support request.
67For a structured walkthrough of the "Couldn't reach the MCP server" and "Authorization failed" errors, see [Troubleshoot your connector](/docs/connectors/building/troubleshooting.md). It includes DNS resolution checks, OAuth discovery diagnostics, and how to find the `ofid_` reference ID to include in a support request.
6868
6969## Next steps
7070
71* [Troubleshoot your connector](/docs/connectors/building/troubleshooting): diagnose each error message Claude shows for a failed connection or tool call
72* [Plugin structure and testing](/docs/plugins/build): bundle your tested connector with skills so people install both together
73* [Publish to the directory](/docs/directory/publish): submit your connector for review and listing
71* [Troubleshoot your connector](/docs/connectors/building/troubleshooting.md): diagnose each error message Claude shows for a failed connection or tool call
72* [Plugin structure and testing](/docs/plugins/build.md): bundle your tested connector with skills so people install both together
73* [Publish to the directory](/docs/directory/publish.md): submit your connector for review and listing
7474
No line in this hunk matches that.