Shipping an MCP Server to Claude's Directory: What Broke

An API key you paste into a client is enough for Cursor. It is not enough for Claude's directory or for ChatGPT, because there is nowhere to paste one — those catalogs require your MCP server to handle sign-in itself. A solo developer who just shipped that change published the list of things that broke, and most of them are not in any OAuth tutorial.

The failures are small and silent

When a request arrived without credentials, the server returned HTTP 200 with an error message in the body. A client that supports sign-in never starts the flow on a 200 — it needs a real 401 plus a WWW-Authenticate header pointing at /.well-known/oauth-protected-resource. Without that header, per the writeup, "the client just says the connection failed and gives you nothing else to go on."

Then two metadata files have to be exactly right. The resource value in oauth-protected-resource must be the exact URL people connect to: the author notes that "a missing www or an extra slash at the end is enough to break it, and nothing tells you why." The second file, oauth-authorization-server, lists the authorize, token and registration endpoints and declares PKCE with S256.

Dynamic client registration is not what Claude uses

Most tutorials get this wrong by age. The author expected dynamic client registration, "because that's what the older examples show." Claude never called it. Instead, per the writeup, Claude sends a client id that is a URL; you fetch that URL and get a small document with the client's name and return address. ChatGPT does the same with its own document.

A server aiming at both catalogs supports two paths at once: Client ID Metadata Documents (declared with client_id_metadata_document_supported: true) for Claude and ChatGPT, and dynamic registration for clients that still use it. The author says dynamic registration is worth keeping anyway — they watched another company pull a catalog submission because their server lacked it.

ChatGPT added one more trap. Its document lists token_endpoint_auth_method: "private_key_jwt" with ["none", "private_key_jwt"] as supported; a server that only accepts none as the method rejects those users. The fix was to accept any client that lists none as supported and treat it as a public client with PKCE.

Two details that bite after you ship

Terminal clients like Claude Code listen on http://localhost and pick a new port every time, so comparing the return address as an exact string makes sign-in work once, then fail. The author points at RFC 8252: for localhost, ignore the port.

Turning sign-in on took an existing listing down. A directory that health-checks the server hourly calls it with no credentials — which used to return 200 and now returns 401 — and marked it unhealthy. Nothing was broken. The author found out by email, then had to authorise a test account in that directory's dashboard. If you are listed anywhere, check your listings the day you flip authentication on.

Claude's review scan also checks tool annotations. Every tool has to declare readOnlyHint, destructiveHint and openWorldHint, and the scan flagged an "update post" tool marked as not destructive — editing a post can overwrite a caption you cannot get back.

The listing is not the win

The distribution numbers landed, then went nowhere. The author reports a best-ever day of 12 sign-ups, 10 of them from Claude — "more than I usually get in a week." Two days later, exactly one of the 12 had connected a social account.

The reason is structural, not a conversion-rate problem. You find the product in Claude's directory, approve the consent screen, and get sent straight back to Claude. As the author puts it: "You now have a Fuxux account and you have never seen Fuxux. No onboarding." Ask the assistant to schedule a post and there is nothing to post to.

The fixes so far are modest: a tool called with no accounts connected now says what to do next instead of returning an empty list, plus one email after approval. The advice is the part worth keeping — test the flow as someone who has never visited your site, because in a directory, that is who shows up.