dev.to walkthrough maps the OAuth 2.1 handshake for remote MCP servers

The problem remote MCP servers create

According to a walkthrough published on dev.to, most teams run into MCP authentication later than they should. A local server launched over stdio simply reuses whatever is already on the machine, such as an AWS_PROFILE setting, a DOCKER_HOST variable or tokens sitting in a config directory. The moment a server needs to be shared across a company, that inheritance disappears: a remote server speaking Streamable HTTP behind a real hostname has to prove the identity of every caller. The protocol's answer is OAuth 2.1 with PKCE, metadata discovery and bearer tokens, and the article walks through the exact requests a client makes so that Claude Desktop, Cursor and VS Code connect without manual workarounds.

Why the token-in-the-URL shortcut fails

The tempting approach is appending a token to the MCP endpoint URL. As the dev.to piece explains, it survives five minutes and then fails every security review. URLs get recorded in proxy logs, browser histories and Referer headers. Rotating the token means redistributing a new URL to everyone. There is no audience restriction, so a token captured for one server can be replayed against other internal hosts. And any bespoke header scheme condemns you to per-client documentation forever. Because every MCP client implements the same standard flow, implementing it once means every compliant client works.

How a client finds its way in

The handshake starts, per the article, when a protected resource answers an unauthenticated request with a 401 and a WWW-Authenticate header pointing at a well-known protected-resource document. That document names the resource, its authorization servers, the supported bearer methods and the available scopes. The client then fetches the authorization server's own metadata document to learn the authorize, token and registration endpoints. Auth0, Okta, Keycloak and AWS Cognito already expose these documents, so the job is configuring routes rather than writing an auth server from scratch.

Registration and PKCE

MCP clients are not pre-registered apps. On first connect they call the registration endpoint and receive a client ID. Public clients deliberately get no secret, since a desktop app cannot keep one; OAuth 2.1 leans on PKCE instead. The client generates a code verifier and its SHA-256 challenge, sends the user to the authorization endpoint, and after consent exchanges the returned code while proving it holds the verifier. If a provider disables dynamic registration, the author notes, you can issue a client ID out of band and pass it to users in the MCP URL configuration; the rest of the flow is unchanged.

The resulting access token travels in the Authorization header on every JSON-RPC request. The sample token response in the article shows a 900-second expiry, and the author argues access tokens should live minutes, not weeks, with the refresh token as the long-lived credential that can be revoked server-side without touching the client.

Scopes and failure modes

Flat read/write scopes age badly once a server exposes twenty tools across several services, the article warns. Scope by capability instead, separating tool listing, read-only calls, state-changing calls and server administration, and enforce the check on every call. Reject an unauthorized invocation with a structured JSON-RPC error naming the missing scope rather than letting an agent discover the boundary by breaking something.

Four mistakes account for most support tickets, according to the author: metadata served over HTTP or with a trailing-slash mismatch, where the issuer must match exactly; loopback redirect URIs missing from the allow list, which makes desktop login impossible; tokens lacking an audience claim in multi-tenant setups; and clock skew treated as fatal, where at least 60 seconds of leeway on expiry validation is advised. The recommended test path is to verify the loop without an AI client first, using curl for the metadata, a browser for the authorization flow and direct initialize and tools/list calls with the token, before driving the OAuth dance interactively with the MCP Inspector.

Why it matters

As teams publish OpenAPI documents as hosted MCP servers, authentication is what separates a demo from real infrastructure: documentation can stay public while the tools that touch live systems sit behind OAuth with per-user scopes and audit logs. Getting the standard flow right once means current and future compliant clients connect without custom integration work, which is what turns an MCP endpoint into something an organisation can actually operate.