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 Authorization header is dropped.

The steps, in order, are the same twelve MCPatch checks. The 12 checks lists what each one tests.

#Checklist

RequirementWhy
Public HTTPS URL on port 443, no trailing slash, no secret in the query stringNon-standard ports and slash handling cause silent failures; URLs end up in logs.
Public A (IPv4) record, no private addresses in public DNSClaude rejects names with any private address.
A certificate from a public CA, with the full chain, valid for the exact hostA missing intermediate certificate is the most common TLS failure.
No redirect on the MCP path; no bot challenge or WAF rule in front of itClaude cannot solve a challenge and drops credentials on a cross-host redirect.
POST /mcp answers initialize with JSON or an event stream, within 10 sThis is the handshake.
tools/list returns an array of tools with valid names and schemasOtherwise 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 endpointThese are the five sign-in steps.
https://claude.ai/api/mcp/auth_callback allowed as a redirect URIIt 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:

server.ts
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

initialize, from outside your network
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.

  1. Sign-in discovery. Claude calls /mcp without credentials and expects 401 with a WWW-Authenticate header pointing at your protected resource metadata.
  2. Authorization server metadata. It reads the metadata of the first server listed there.
  3. Client registration. It registers itself (dynamic client registration) or identifies itself with a client ID metadata document.
  4. Sign-in page. It sends the user to your authorization endpoint with an S256 PKCE challenge and a resource parameter equal to your connector URL.
  5. Token endpoint. It posts the code, as a form body, to get an access token, and then calls /mcp with Authorization: Bearer ....

1. The 401 and the resource metadata

Express
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:

/.well-known/oauth-authorization-server
{
  "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"]
}
  • issuer must equal the entry in authorization_servers.
  • Claude always sends S256 PKCE, so list it.
  • Offer a registration_endpoint (dynamic client registration, RFC 7591) that accepts application/json and public clients, and keeps https://claude.ai/api/mcp/auth_callback as a redirect URI. Or advertise "client_id_metadata_document_supported": true with "none" in token_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:

Express
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

WhereWhat goes wrongWhat to do
CloudflareBot 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 proxiesThe 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 startsThe first request takes longer than 10 seconds.Keep an instance warm and make startup light.
Redirectsapex 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 networkClaude connects from the internet, so a private address can never work.Expose it on a public address, or use a tunnel.
Host validationThe 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.listChanged and send notifications/tools/list_changed after 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.