MCP OAuth and authentication explained

MCP OAuth authorizes an AI client to use a protected remote MCP server on a user’s behalf. The client signs in through an authorization flow, receives tokens and uses them for server requests; that does not automatically grant every upstream tool permission. AIPx uses OAuth for its agent endpoints and separate account connections for the services behind them.

What is MCP OAuth

The HTTP authorization model is defined in the MCP 2026-07-28 specification. Authorization is optional for MCP implementations; when an HTTP server supports it, that model describes the expected flow. Stdio servers normally obtain credentials from their environment instead of running the same transport-level login.

The specification references OAuth 2.1 as an IETF draft. Calling it a finished OAuth 2.1 RFC would misstate its status. MCP combines that model with published mechanisms for bearer tokens, resource indicators and metadata discovery.

For setup, identify the actual protected server first. An AIPx MCP endpoint is not the Gmail API or a GitHub endpoint. A client authenticates to AIPx, and AIPx uses the connected account’s authorization to call the upstream provider. Those credentials have different recipients and purposes.

MCP authentication vs authorization

Authentication establishes who is making a request or signing in. Authorization decides what that identity may access. Product interfaces often call the whole browser flow “authentication,” but a successful sign-in is only one part of the permission decision.

Layer	Question	AIPx example
User sign-in	Which user is approving the connection?	Sign in to the appropriate AIPx account
Client authorization	May this client use the protected endpoint?	OAuth for the agent MCP URL
Gateway policy	May this agent use this account tool?	Allow, Confirm or Hide
Upstream authorization	May the connected account perform the operation?	Provider OAuth grant or account credential

A tool may be absent because of Hide, even after successful OAuth. A tool may be available but fail because the provider account lacks access. A Confirm-marked tool requests client review through metadata even when the token is valid; actual approval depends on the client. Keep those explanations separate during troubleshooting.

How the MCP OAuth 2.1 flow works

At a high level, a remote connection moves from resource discovery to browser consent, then token-based requests. The client should use the server’s metadata rather than guessing endpoints from a copied tutorial.

1. The client requests the protected MCP endpoint and receives an authorization challenge when needed.
2. It reads protected-resource metadata to identify the authorization server.
3. It discovers that authorization server’s endpoints and capabilities.
4. It obtains a client ID through a supported registration mechanism.
5. It starts the authorization request with PKCE and the intended resource.
6. The user signs in and approves the requested connection.
7. The client exchanges the returned code using its PKCE verifier.
8. It calls the MCP server with a bearer access token and refreshes authorization as supported.

Protected-resource metadata lets a resource tell clients which authorization servers it uses. It is a separate document from authorization-server metadata, which describes such things as token and authorization endpoints. This separation matters when an operator hosts the resource and authorization server at different locations. The mechanism is documented in RFC 9728.

For AIPx, use the dashboard endpoint exactly:

https://dash.aipx.run/mcp/AGENT_ID

Do not remove the agent path because another example uses /mcp at the domain root. The identifier is part of the resource you intend to authorize.

PKCE binds the code exchange

PKCE gives the client a verifier associated with the authorization request. The authorization server checks the verifier during the code exchange, reducing the value of an intercepted code to another process. AIPx implements the S256 challenge method.

The verifier belongs to the specific login attempt. It is not an upstream API key, a shared account password or a value to paste into a project configuration. If you implement a client, keep the request state and verifier together and do not reuse them casually across attempts. The core construction and interception threat are described in RFC 7636.

Dynamic client registration in MCP

Dynamic client registration gives a client a registration path without requiring a developer to manually provision each installation. AIPx exposes a registration endpoint and implements this flow along with authorization-code and refresh-token handling.

The current MCP model also supports pre-registration and prefers Client ID Metadata Documents where supported. DCR is retained as a deprecated compatibility option, not a mandatory mechanism for every MCP server. AIPx’s verified implementation is DCR with PKCE; this page does not claim that AIPx implements Client ID Metadata Documents.

When choosing a client, check whether its registration behavior is compatible with the endpoint. A browser login error before consent can indicate metadata or registration mismatch rather than an expired provider account. Adding more tool permissions will not repair that earlier stage.

Avoid assuming that a registered client ID itself grants tool access. Registration describes the client. The user’s authorization and the endpoint’s access rules still decide what calls can occur.

MCP OAuth security

Tokens need an intended recipient. Resource indicators tell the authorization server which protected resource the client wants to access, helping bind the issued token to that resource. A token intended for another service should not become valid simply because a gateway can forward requests to that service. See RFC 8707 for the resource-indicator model.

In AIPx, client OAuth and upstream service authorization remain separate. Do not paste a GitHub token into an AIPx client configuration as a replacement for the browser flow. Do not treat the agent URL as a bearer secret. It identifies a protected resource, while the OAuth token authorizes requests to it.

Common mistake	Why it matters	Better check
Guessing the token endpoint	The URL may belong to a different issuer	Use discovered metadata
Reusing an upstream token	Its audience and privileges differ	Authenticate the client to the gateway
Sharing tokens in repository config	Other readers can acquire access	Keep credentials in the client’s protected storage
Accepting an unexpected redirect	The login may not return to the intended client	Verify the registered callback and flow
Treating OAuth as tool policy	Login does not describe every permitted action	Review agent account and tool rules

A bearer credential should be protected in storage and transit. Avoid including it in chat prompts, logs, example URLs or checked-in configuration. Exact redirect matching and a bound code exchange matter because an otherwise convenient login can send authorization information to the wrong destination.

OAuth also does not decide whether content returned by a tool is trustworthy. An authenticated document can contain malicious instructions. Keep external content as task data and enforce the reachable tool boundary independently. The MCP security guide covers that wider issue.

Claude MCP OAuth

For Claude’s remote AIPx connection, add the agent URL through the connector interface and complete the sign-in it requests. For terminal use, register the HTTP server in Claude Code and inspect authentication through /mcp. Follow the Claude connection guide for its current interface.

Do not configure a local stdio server expecting the same remote browser flow. Do not infer that remote connectors can reach a local development endpoint because you opened Claude Desktop on the same laptop. Connection placement and authentication are separate questions; the remote server guide covers reachability.

If a browser sign-in works but a tool call fails, inspect the failure stage. The client may be authorized to AIPx while the upstream connection has expired or lacks the necessary provider access. If only one tool is missing, inspect its gateway rule before repeating OAuth.

How AIPx handles MCP authentication

For HTTP consumers, the agent OpenAPI interface uses a separate key-protected route. Keep that credential model distinct from client MCP OAuth.

The verified AIPx implementation exposes protected-resource and authorization-server metadata, client registration, authorization and token endpoints. It supports PKCE S256, authorization-code exchange and refresh tokens. Client authorization applies to the selected agent resource rather than substituting for all connected account credentials.

Connect the upstream service account in AIPx, configure the agent’s tools, then authenticate the client to the agent endpoint. Confirm communicates an approval hint to the client; its actual review behavior is client-dependent. Hide is enforced server-side, independently of a valid token. The access-control guide explains those per-tool rules, and the gateway guide shows how account connections are shared.

For generic agents that use HTTP operations rather than MCP, AIPx also exports an agent-specific OpenAPI 3.1 document with calls protected by X-API-Key. That is a separate interface and credential model. It should not be confused with the MCP OAuth flow or with importing arbitrary API specifications.

Diagnose the boundary that failed

A registration or callback error belongs to the client-to-AIPx login. A hidden operation belongs to agent policy. A provider denial belongs to the upstream connection. An unexpected result needs inspection of account selection and tool arguments in the audit. Begin with the smallest failing stage and avoid broadening access as a universal remedy.

AIPx adds another operator to trust, and hosted access depends on network and upstream availability. For a broader comparison of keys, service credentials and agent identities, see AI agent authentication. Connect free.