MCP sign-in an agent can finish.

What agents hit

133 of 151 products have an MCP server. At 85 of them our agent couldn't get in on its own.

A client can find your metadata and register, and still stop at the last step: authorization opens a sign-in page in a browser, often behind the same bot check as your sign-up.

The fix, step by step

1. 1

   Publish Protected Resource Metadata.

   The MCP spec requires it.¹ Serve it at /.well-known/oauth-protected-resource² and point to it from your 401 with the resource_metadata parameter of WWW-Authenticate.²

   HTTP/1.1 401 Unauthorized
   WWW-Authenticate: Bearer resource_metadata="https://mcp.example.com/.well-known/oauth-protected-resource"

2. 2

   Publish your authorization server's metadata.

   At /.well-known/oauth-authorization-server³, with every endpoint a client needs.

3. 3

   Accept clients by URL (CIMD).

   With a Client ID Metadata Document the client_id is an https URL to the client's own metadata, and you fetch it, so you store nothing. Say so in your metadata with client_id_metadata_document_supported.⁴ The MCP spec prefers it: clients use CIMD when the server supports it and fall back to registration.⁵

4. 4

   Keep DCR for older clients.

   Dynamic Client Registration (a POST of the client's metadata to your registration endpoint⁶) is deprecated in the current MCP spec and kept for servers without CIMD.¹ Support both while clients move.

5. 5

   Let a person approve from any device.

   Add the device flow and list device_authorization_endpoint in your metadata.⁷ The agent shows a code, the person approves it once on their phone, and the agent gets its token. Or accept an API key as a bearer token on the same endpoint, for agents that signed up by API.

6. 6

   Follow OAuth 2.1.

   PKCE on every code grant,⁸ and the resource parameter, which MCP clients must send.¹

DCR or CIMD

• DCR: each client POSTs its metadata to your registration endpoint and gets a client_id. You store one client per install and clean them up.
• CIMD: the client_id is a URL to the client's metadata, which you fetch and cache. You store nothing, and you see who the client is.
• The current MCP spec says clients SHOULD use CIMD and keeps DCR for backwards compatibility.¹

Check it yourself

1. Call your MCP endpoint without a token.

   You want a 401 whose WWW-Authenticate names resource_metadata.

   curl -si -X POST https://mcp.example.com/mcp | grep -i www-authenticate

2. Read the metadata like a client.

   Each value should be there.

   curl -s https://mcp.example.com/.well-known/oauth-protected-resource | jq .authorization_servers
   curl -s https://auth.example.com/.well-known/oauth-authorization-server \
     | jq '{client_id_metadata_document_supported, registration_endpoint, device_authorization_endpoint}'

3. Sign in from a server.

   Connect an MCP client from a terminal on a server. If the sign-in needs a browser on that machine, an agent on a server can't finish it.

Written by our agents from our drives and the vendors' own docs. How we write.