Third-party sign-in for a remote MCP server

The brief

The server exposes a B2B platform’s admin API as MCP tools, so the people who already work in that platform’s web console can investigate their own account from Claude. Locally it runs on the workstation, with the credentials kept there. Remotely it is a Claude custom connector on a host the platform’s owner runs — and that is where identity stops being a config value.

Three constraints shaped everything that follows:

• People act as themselves. No shared account. The upstream’s own records name the person, and what they can see is what the upstream lets them see.
• No identity provider. Not on the table — and it would not have helped: the only system that knows these users and their passwords is the platform itself.
• No stored passwords. A server that keeps platform passwords becomes the most interesting thing on the network to break into.

The platform adds one rule of its own, common in older admin consoles: one session per user. A new login ends the previous one, wherever it was. Hold on to that; it decides most of the design.

Why the usual answers don’t fit

Most MCP auth guides start from “you already have an identity provider”. Here is how the usual options fared against the brief.

The shape of it

The trick is that there are two credentials, and they never meet. Claude holds tokens your server issued, which mean nothing to the upstream. Your server holds the session cookie the upstream issued, which Claude never sees. A token is only a pointer to a person; the person’s row holds the upstream session. Everything else on this page is about keeping those two in step.

1 · Discovery: how Claude finds your sign-in

Claude starts with nothing but the URL someone pasted into the connector dialog. It finds the rest the way the MCP authorization spec says: call /mcp without a token, get a 401 with a pointer, follow the pointer.

The two documents in full. Nothing in them is exotic; the details are where it breaks.

// GET /.well-known/oauth-protected-resource/mcp   (RFC 9728)
{
  "resource": "https://mcp.example.com/mcp",
  "authorization_servers": ["https://mcp.example.com"],
  "scopes_supported": ["mcp"],
  "bearer_methods_supported": ["header"]
}

// GET /.well-known/oauth-authorization-server     (RFC 8414)
{
  "issuer": "https://mcp.example.com",
  "authorization_endpoint": "https://mcp.example.com/authorize",
  "token_endpoint": "https://mcp.example.com/token",
  "registration_endpoint": "https://mcp.example.com/register",
  "revocation_endpoint": "https://mcp.example.com/revoke",
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "code_challenge_methods_supported": ["S256"],
  "token_endpoint_auth_methods_supported": ["none"],
  "client_id_metadata_document_supported": true,
  "authorization_response_iss_parameter_supported": true,
  "scopes_supported": ["mcp"]
}

• The resource must equal the URL the user typed, path included. Compare canonical forms: lower-case scheme and host, no default port, no trailing slash, no fragment.
• Claude chooses CIMD only when both flags are there: client_id_metadata_document_supported: true and "none" in token_endpoint_auth_methods_supported. Miss one and it falls back to dynamic registration without telling you why.
• A request with no token gets no error code (RFC 6750 §3.1), only WWW-Authenticate: Bearer resource_metadata="…". And it has to be a 401: Claude ignores that header on a 200.
• Mount /authorize, /token and /register at the origin root. When discovery fails, Claude falls back to treating your origin as the authorization server. At the root, that failure still lands somewhere that works.

2 · Who is asking: CIMD, DCR, or an id you hand out

Before anyone signs in, the server has to know which client is asking and where it may send the code back. Claude’s connector dialog offers three ways, and a server that wants to work with more than one MCP client supports all three. Every client is public: no secret, and PKCE on every authorization instead.

CIMD is the recommended path, and the one with a sharp edge: the client tells your server which URL to fetch, which is the textbook definition of server-side request forgery. Fetch it like you mean it:

• https only, and the document’s own client_id must equal the URL it came from;
• resolve the host yourself and refuse loopback, private, link-local and the other special ranges — for every address it resolves to;
• no redirects, a 5 KB cap, a 5-second timeout; cache by Cache-Control, within bounds you choose;
• on the sign-in page, show the host of the client_id URL, never the name the document gives itself. Anyone can publish a document that says “Claude”.

Node’s net.BlockList has a trap here, found the first time the server fetched the real document:

// A BlockList rule for ::ffff:0:0/96 also matches every plain IPv4
// address, so it refused claude.ai itself. Unwrap mapped addresses
// (::ffff:10.0.0.1, and the hex form ::ffff:a00:1) and check them as IPv4.
const ipv4 = mappedIpv4(address) ?? (isIPv4(address) ? address : undefined);
const refused = ipv4 !== undefined
  ? blocked.check(ipv4, 'ipv4')
  : blocked.check(address, 'ipv6');

3 · The sign-in page: forward once, then forget

This is the one page in the flow you write yourself, and the one where people type a password for another system. The server sends those credentials to the upstream’s login once, asks who the person is and which account they belong to, stores the session cookie it got back, and redirects to the client with an authorization code. The password does not outlive the request.

The account check comes after the login, because the account is only known once the upstream has accepted the password. That has a cost worth stating: a person whose account this server does not serve has still spent a login — and, on a one-session platform, their console tab.

4 · Tokens: opaque, hashed, rotated

The authorization server and the resource server are one process sharing one database, so JWTs buy nothing: no other service needs to verify a token without asking. Opaque random tokens, stored only as their SHA-256, make verification one indexed lookup and revocation a DELETE.

// Opaque, random, and only ever stored as a hash.
const token = randomBytes(32).toString('base64url');
db.prepare(
  'INSERT INTO oauth_token (token_sha256, kind, grant_id, user_id, expires_at) ' +
  'VALUES (?, ?, ?, ?, ?)',
).run(sha256(token), 'refresh', grantId, userId, now + 30 * DAY);

// Refresh: spend the presented token. If it was already spent,
// someone else holds a copy, so the whole grant goes.
const spent = tokens.spendRefresh(presented);
if (spent.outcome === 'replayed') tokens.revokeGrant(spent.record.grantId);
if (spent.outcome !== 'spent') return oauthError(400, 'invalid_grant');

• Access tokens last an hour, refresh tokens thirty days, and every refresh rotates. Claude refreshes on a 401, and up to five minutes before expiry.
• A second use of a refresh token or an authorization code revokes the whole grant. One of the two presenters is not the client.
• Every refresh asks the upstream whether the session still lives, with the cheapest authenticated call it offers. An ended session answers invalid_grant at the refresh, before anyone asks a question.
• /token reads application/x-www-form-urlencoded, which is what Claude sends; /register reads JSON. A framework that parses JSON only answers 415, and the connection fails without much of a clue.
• The cheap extras: RFC 7009 revocation, and iss in the authorization response (RFC 9207), which the 2026-07-28 revision of the MCP spec recommends.

5 · Every tool call: token → person → upstream session

On /mcp, the SDK’s requireBearerAuth does the HTTP half — parse the header, check expiry and audience, answer with the right challenge — and calls your verifier for the rest:

import { OAuthError, OAuthErrorCode, requireBearerAuth } from '@modelcontextprotocol/server';

const gate = requireBearerAuth({
  resourceMetadataUrl,                 // where the RFC 9728 document lives
  expectedResource: new URL(mcpUrl),   // tokens are bound to /mcp
  verifier: {
    async verifyAccessToken(token) {
      const record = tokens.find(sha256(token));          // a hash lookup
      if (!record || !sessions.holds(record.userId)) {
        throw new OAuthError(OAuthErrorCode.InvalidToken, 'Sign in again');
      }
      return {
        token,
        clientId: record.clientId,
        scopes: ['mcp'],
        expiresAt: Math.floor(record.expiresAt / 1000),
        extra: { userId: record.userId },                  // → per-request context
      };
    },
  },
});

The verified AuthInfo reaches the MCP server factory, which builds a per-request context: the person, their account, a logger bound to both, and a session object that sends upstream calls with that person’s cookie and applies every Set-Cookie it gets back, so a sliding expiry keeps sliding.

One upstream session per person, shared by all their connections — every chat, every device. On a one-session platform that is not a design choice: two sessions for the same person would simply keep ending each other.

6 · When the upstream ends the session

Upstream sessions end on their own schedule: an idle timeout, a password change, or — on a one-session platform — the same person logging into the web console. Your tokens know none of this. Left alone, Claude keeps presenting a valid access token that points at a dead session, and every tool call fails politely.

So the upstream’s 401 is the source of truth, and the server acts on it in the request that finds it:

Races, and the generation counter

Two connections of one person; one signs in again while the other’s call is in flight. The in-flight call gets a 401 from the upstream — but the session did not end, it was replaced. A generation number on the session row tells the two apart: a 401 under an older generation is retried once with the current session, and only a 401 under the current one ends anything. The end itself is conditional, so a late failure cannot undo a fresh sign-in:

-- End the session only if it is still the one this call used.
-- A sign-in that replaced it meanwhile has bumped the generation.
UPDATE user_session
   SET cookie = NULL, generation = generation + 1, ended_at = :now
 WHERE user_id = :user AND generation = :seen;

-- ...and in the same transaction, only if a row was updated:
DELETE FROM oauth_token WHERE user_id = :user;

A 403 is ambiguous. It can mean the session is gone, or that this person’s role cannot read that route. Ask a route everyone can read, with the same cookie, and end the session only if that fails too. Otherwise a permissions gap logs people out.

Design decisions & honest trade-offs

Field notes: what broke, so yours doesn’t

Each of these cost somewhere between ten minutes and an afternoon. Roughly in that order, worst first.

1. 1
   Reconnect needs a 401.

   Claude re-authenticates on an HTTP 401 only — not on an isError tool result, not on a WWW-Authenticate header attached to a 200. If the upstream session dies mid-call, the HTTP answer to that call has to be the 401.

2. 2
   CIMD needs two flags.

   client_id_metadata_document_supported: true and "none" in token_endpoint_auth_methods_supported. With either missing, Claude quietly registers through DCR instead.

3. 3
   no-referrer breaks your own form.

   With Referrer-Policy: no-referrer, browsers post the sign-in form with Origin: null, and an Origin check then refuses it. same-origin keeps the header and leaks nothing.

4. 4
   Localhost validation behind a tunnel.

   The SDK’s Host and Origin checks are built for a server on localhost. Behind a tunnel or reverse proxy the browser’s form arrives with your public host: allow that host explicitly, and only it.

5. 5
   net.BlockList and ::ffff:0:0/96.

   The IPv4-mapped rule matches every IPv4 address, including the one you are trying to reach. Unwrap mapped addresses and check them as IPv4.

6. 6
   Don’t rate-limit /register like a login.

   Registrations arrive from Anthropic’s egress range (160.79.104.0/21) for every user of every organisation, two per Connect. A per-address limit there throttles everyone at once. Guard against floods instead, and keep per-person limits for the sign-in form, which comes from the person’s own browser.

7. 7
   X-Forwarded-For has more than one author.

   Take the entry your own proxy appended, counting from the right. Some cloud load balancers append their own address after the client’s, which quietly turns a per-address limit into one shared by everybody.

8. 8
   resource is compared exactly.

   Canonicalise before comparing, on /authorize and on /token. Claude sends the canonical form of the URL the user typed; the user typed whatever they liked.

9. 9
   Two body formats.

   /token is form-urlencoded, /register is JSON. One body parser for both answers 415 to one of them.

10. 10
    Discovery is cached.

    Claude caches the discovery documents for about five minutes, keyed by URL. Change the metadata, then wait, before deciding the change didn’t work.

11. 11
    Double-clicks happen.

    A double click on Sign in posts the form twice, and the browser abandons the first. Pass the request’s abort signal into the upstream call, so the abandoned login stops instead of racing the second.

How it’s tested

Every case runs at the HTTP-app seam, in memory, against a stand-in upstream that behaves like the real one — one session per user, so a second login really does end the first, and refusals in the platform’s real shapes.

Then a live run with the real Claude connector through a tunnel, against the platform’s sandbox: connect, wrong password, sign in, ask, log in to the console in another tab, ask again. That run found the 401 problem above, which no test had: the tests asserted the behaviour I had designed, not the behaviour Claude has.