Developer guide
Build a connector
How to build a remote MCP server that Claude connects to on the first try: what Claude requires at each step, working examples and the hosting traps that cause "Couldn't reach the MCP server".
#How Claude connects
Claude connects to a custom connector from Anthropic's servers, not from your computer. That is the source of most surprises.
- It connects over the public internet, from the range
160.79.104.0/21. A server that only works on your laptop, your VPN or your office network cannot be reached. - IPv4 only and HTTPS only. Every address your host name resolves to must be public, or the whole name is refused.
- It talks Streamable HTTP: JSON-RPC messages POSTed to one endpoint (usually
/mcp). - Discovery, registration and token requests get 10 seconds to answer. Tool lists and first responses too.
- It does not follow redirects to other hosts with your credentials: the
Authorizationheader is dropped.
The steps, in order, are the same twelve MCPatch checks. The 12 checks lists what each one tests.
#Checklist
| Requirement | Why |
|---|---|
| Public HTTPS URL on port 443, no trailing slash, no secret in the query string | Non-standard ports and slash handling cause silent failures; URLs end up in logs. |
| Public A (IPv4) record, no private addresses in public DNS | Claude rejects names with any private address. |
| A certificate from a public CA, with the full chain, valid for the exact host | A missing intermediate certificate is the most common TLS failure. |
| No redirect on the MCP path; no bot challenge or WAF rule in front of it | Claude cannot solve a challenge and drops credentials on a cross-host redirect. |
| POST /mcp answers initialize with JSON or an event stream, within 10 s | This is the handshake. |
| tools/list returns an array of tools with valid names and schemas | Otherwise Claude has nothing to call, or hides the tools. |
| If you need sign-in: 401 + WWW-Authenticate, protected resource metadata, authorization server metadata with S256 PKCE, dynamic client registration or client ID metadata, form-encoded token endpoint | These are the five sign-in steps. |
| https://claude.ai/api/mcp/auth_callback allowed as a redirect URI | It is where Claude receives the sign-in result. |
#The MCP endpoint
Claude sends initialize, then notifications/initialized, then tools/list, always as POST requests with Accept: application/json, text/event-stream. Answer each request with application/json or an event stream. Answer the notification with 202 and no body. If you issue an mcp-session-id, accept it on the follow-up requests.
A minimal stateless server with the official TypeScript SDK (version 1.x), following the SDK's own stateless example:
import express from 'express'
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js'
import { z } from 'zod'
const app = express()
app.use(express.json())
app.post('/mcp', async (req, res) => {
// a fresh server per request: no session in memory, so it works behind any number of instances
const server = new McpServer({ name: 'my-server', version: '1.0.0' })
server.tool('ping', 'Replies with pong. Use it to check the connection.', { text: z.string().optional() }, async () => ({
content: [{ type: 'text', text: 'pong' }],
}))
const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined })
res.on('close', () => { transport.close(); server.close() })
await server.connect(transport)
await transport.handleRequest(req, res, req.body)
})
// this server is stateless, so there is no stream to open or session to end
app.get('/mcp', (_req, res) => res.status(405).end())
app.delete('/mcp', (_req, res) => res.status(405).end())
app.listen(3000)Test it yourself
curl -sS -i https://mcp.example.com/mcp \
-H 'content-type: application/json' \
-H 'accept: application/json, text/event-stream' \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}'You should see a 200 (or 401 if you require sign-in), a content type of application/json or text/event-stream, and a result containing protocolVersion. Run it from a machine outside your own network, such as a cloud shell, not your laptop on the same LAN.
#Sign-in (OAuth)
If your server needs the user to sign in, Claude runs this flow. Each numbered item is a step MCPatch tests.
- Sign-in discovery. Claude calls
/mcpwithout credentials and expects401with aWWW-Authenticateheader pointing at your protected resource metadata. - Authorization server metadata. It reads the metadata of the first server listed there.
- Client registration. It registers itself (dynamic client registration) or identifies itself with a client ID metadata document.
- Sign-in page. It sends the user to your authorization endpoint with an S256 PKCE challenge and a
resourceparameter equal to your connector URL. - Token endpoint. It posts the code, as a form body, to get an access token, and then calls
/mcpwithAuthorization: Bearer ....
1. The 401 and the resource metadata
const BASE = 'https://mcp.example.com'
function requireAuth(req, res, next) {
if (isValid(req.headers.authorization)) return next() // your token check
res
.status(401)
.set('WWW-Authenticate', `Bearer resource_metadata="${BASE}/.well-known/oauth-protected-resource/mcp"`)
.json({ jsonrpc: '2.0', error: { code: -32001, message: 'Unauthorized' }, id: null })
}
app.use('/mcp', requireAuth)
app.get('/.well-known/oauth-protected-resource/mcp', (_req, res) => {
res.json({
resource: `${BASE}/mcp`, // must match the connector URL exactly
authorization_servers: ['https://auth.example.com'], // Claude uses only the first
})
})2 and 3. Authorization server metadata
Whoever issues tokens has to publish discovery metadata (RFC 8414, or OpenID configuration) that includes at least this:
{
"issuer": "https://auth.example.com",
"authorization_endpoint": "https://auth.example.com/authorize",
"token_endpoint": "https://auth.example.com/token",
"registration_endpoint": "https://auth.example.com/register",
"response_types_supported": ["code"],
"code_challenge_methods_supported": ["S256"]
}issuermust equal the entry inauthorization_servers.- Claude always sends S256 PKCE, so list it.
- Offer a
registration_endpoint(dynamic client registration, RFC 7591) that acceptsapplication/jsonand public clients, and keepshttps://claude.ai/api/mcp/auth_callbackas a redirect URI. Or advertise"client_id_metadata_document_supported": truewith"none"intoken_endpoint_auth_methods_supported. - If you need pre-registered clients instead, users have to enter a client ID under "Use your own OAuth client".
5. The token endpoint
Claude posts application/x-www-form-urlencoded, not JSON. A token route that only parses JSON answers 415 and every sign-in fails at the last step. For bad codes return 400 with a JSON error:
app.use('/token', express.urlencoded({ extended: false }))
app.post('/token', async (req, res) => {
const grant = await exchange(req.body) // your code exchange
if (!grant) return res.status(400).json({ error: 'invalid_grant' })
res.json({ access_token: grant.token, token_type: 'Bearer', expires_in: 3600, refresh_token: grant.refresh })
})#Hosting traps
| Where | What goes wrong | What to do |
|---|---|---|
| Cloudflare | Bot Fight Mode, a managed challenge or a WAF rule answers with a challenge page (403 or 429). Claude cannot solve it, so it never reaches your app. | Exempt the MCP path and /.well-known/ from bot protection and rate limiting, or allowlist 160.79.104.0/21. |
| nginx and other proxies | The proxy buffers the event stream, so the initialize result never arrives. | Set proxy_buffering off for the MCP path, and disable compression for it. |
| Serverless (Vercel, Lambda, Netlify) | Sessions kept in memory are lost between instances (404 right after initialize). Some platforms cannot serve /.well-known at the root. | Run stateless, or keep sessions in shared storage. Point resource_metadata at a URL your app can serve, and add a rewrite for /.well-known/*. |
| Cold starts | The first request takes longer than 10 seconds. | Keep an instance warm and make startup light. |
| Redirects | apex to www, http to https, a missing or extra slash. | Register the final URL as the connector URL. |
| Tunnels (ngrok, Cloudflare Tunnel) | A free tunnel URL changes, or interstitial pages appear. | Use a stable host name and a tunnel that serves your path directly. |
| Localhost, VPN, home network | Claude connects from the internet, so a private address can never work. | Expose it on a public address, or use a tunnel. |
| Host validation | The SDK's DNS-rebinding protection answers 403 Invalid Host for names it does not know. | Add your public host name to the allowed hosts. |
#Keep your tools stable
- Add tools and parameters rather than renaming or removing them. Clients that loaded the old list keep calling the old shape.
- Make new parameters optional.
- Declare
capabilities.tools.listChangedand sendnotifications/tools/list_changedafter a deploy. - Tool names: 1 to 64 letters, numbers, underscores or dashes, no spaces, no duplicates.
- Write descriptions for the AI that reads them, and nothing else. Text that tells the AI to hide things or to ignore its own instructions is flagged by tool-description scanners, and by users.
#Verify before you ship
Run MCPatch against the deployed URL, from outside your network. Fix the first failing step, deploy, and check again until the verdict is a pass. The recipes show how to run the same check in CI.