Wolfia MCP Server: OAuth, Direct Connections & Gateways

Overview

This is the in-depth reference for authenticating to the Wolfia MCP server. If you just want to connect Claude, Cursor, or Windsurf with one line, start with the MCP server guide. Read this page when you are:

Connecting a client directly to https://api.wolfia.com/mcp/ (no mcp-remote shim).
Putting the Wolfia MCP server behind a gateway or proxy (Runlayer, Cloudflare AI Gateway, an internal MCP gateway, etc.).
Debugging an OAuth error such as {"detail":"Invalid redirect URI"}.
Building your own MCP client and need the exact OAuth contract.

The single most important thing to know: Wolfia’s MCP server uses the standard OAuth 2.1 flow with Dynamic Client Registration (DCR). There is no manual allowlist of redirect URIs or origins. Clients register themselves automatically at connect time. Nobody at Wolfia needs to (or can) “whitelist” your redirect URI by hand. If a client is configured correctly, it just works.

How authentication works

The Wolfia MCP server is a standards-compliant OAuth 2.1 resource and authorization server. A compliant MCP client performs the whole handshake automatically:

Discovery

The client reads Wolfia’s published OAuth metadata and learns every endpoint it needs. No values are hardcoded or shared out-of-band.

Dynamic Client Registration

The client calls POST /mcp/register with the redirect URI it owns. Wolfia issues a fresh client_id on the spot. This is the step that replaces any manual allowlisting.

Authorization with PKCE

The client opens GET /mcp/authorize in a browser. You sign in with your existing Wolfia account (SSO or email) and approve access. PKCE (S256) protects the exchange.

Token exchange

The client exchanges the authorization code at POST /mcp/token for a bearer access token and a refresh token.

Authenticated calls

The client calls the MCP endpoint at https://api.wolfia.com/mcp/ with Authorization: Bearer <access_token>. Tools run scoped to your account and your organization’s permissions.

Discovery endpoints

Point any compliant client at the MCP base URL and it discovers the rest from these well-known documents:

Metadata document	URL
Protected resource metadata	`https://api.wolfia.com/.well-known/oauth-protected-resource`
Authorization server metadata	`https://api.wolfia.com/.well-known/oauth-authorization-server`

The authorization server metadata advertises, among other fields:

authorization_endpoint: https://api.wolfia.com/mcp/authorize
token_endpoint: https://api.wolfia.com/mcp/token
registration_endpoint: https://api.wolfia.com/mcp/register
code_challenge_methods_supported: ["S256"]
response_types_supported: ["code"]
grant_types_supported: ["authorization_code", "refresh_token"]

Endpoint reference

Step	Method & path	Notes
Register	`POST https://api.wolfia.com/mcp/register`	Dynamic Client Registration (RFC 7591). Public client, `token_endpoint_auth_method: none`.
Authorize	`GET https://api.wolfia.com/mcp/authorize`	Requires `code_challenge`, `code_challenge_method=S256`, `redirect_uri`, `response_type=code`.
Token	`POST https://api.wolfia.com/mcp/token`	`grant_type=authorization_code` (with `code` + `code_verifier`) or `grant_type=refresh_token`.
MCP endpoint	`https://api.wolfia.com/mcp/`	Streamable HTTP transport (stateless; responses are JSON, not SSE), JSON-RPC 2.0. Send `Authorization: Bearer <token>`.

Dynamic Client Registration

POST /mcp/register accepts the standard RFC 7591 fields, including redirect_uris, client_name, client_uri, grant_types, response_types, and scope. It returns a fresh client identity:

{
  "client_id": "mcp_xxxxxxxxxxxxxxxxxxxxxx",
  "client_id_issued_at": 1750000000,
  "redirect_uris": ["https://your-client.example.com/oauth/callback"],
  "grant_types": ["authorization_code"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none"
}

Because the client supplies its own redirect_uris at registration, you do not file a request with Wolfia to add a redirect URI. Registration is the allowlist.

Token lifetimes

Token	Lifetime
Access token	30 days
Refresh token	90 days
Authorization code	10 minutes

When the access token expires, the client uses the refresh token at /mcp/token to obtain a new one without a fresh browser sign-in.

Redirect URI rules

When a client registers or authorizes, the redirect_uri it provides must satisfy these rules. This is the entire policy:

Redirect URI	Allowed?
`https://your-app.example.com/oauth/callback`	Yes. Non-localhost URIs must use HTTPS.
`http://localhost:8080/callback`	Yes. `localhost`, `127.0.0.1`, and `[::1]` may use HTTP (for local development).
`http://your-app.example.com/callback`	No. Non-localhost over plain HTTP is rejected.
`ftp://...` or any non-HTTP(S) scheme	No. Only `http` and `https` schemes are accepted.

A redirect_uri that does not meet these rules returns {"detail":"Invalid redirect URI"} with HTTP 400. The fix is always to send a valid HTTPS redirect URI (or a localhost URI in dev), not to ask Wolfia to make an exception. There is no exception path because there is no manual allowlist.

Connecting directly (streamable HTTP)

If your client speaks remote MCP over streamable HTTP natively, connect straight to the endpoint and let the client run the OAuth handshake:

https://api.wolfia.com/mcp/

The client will discover the OAuth metadata, register dynamically, open a browser for sign-in, and cache the resulting tokens. No shim is required. (Clients that only speak stdio should use the mcp-remote approach described in the MCP server guide.)

Connecting through a gateway or proxy

MCP gateways such as Runlayer, Cloudflare AI Gateway, or an internal corporate MCP proxy sit between your AI client and Wolfia. In this setup, the gateway is the OAuth client, and the same DCR flow applies, with one thing to get right.

Point the gateway upstream at Wolfia

Configure the gateway’s upstream MCP server as https://api.wolfia.com/mcp/.

Let the gateway register itself

The gateway performs Dynamic Client Registration on its own, passing the gateway’s own callback URL as the redirect URI (for example https://mcp.yourcompany.tools/oauth/callback). Wolfia issues it a client_id automatically.

Ensure the gateway's callback is HTTPS

The gateway’s redirect URI must be served over HTTPS (see the redirect URI rules above). This is the only requirement, and it is satisfied by every production gateway out of the box.

The first connection opens a browser for your Wolfia sign-in. After approval, the gateway holds the tokens and proxies authenticated traffic to Wolfia.

You do not send Wolfia a list of origins or redirect URIs to add for your gateway. If a gateway integration guide tells you to ask the upstream provider to whitelist https://your-gateway-domain/..., that step does not apply to Wolfia, the gateway registers itself automatically via DCR. The only thing that ever needs to be HTTPS is the gateway’s own callback URL, which you control on the gateway, not on Wolfia.

Authentication options

Method	How	Best for
OAuth (DCR)	Automatic browser sign-in via the flow above	Interactive clients (Claude, Cursor, Windsurf), gateways
API key	Send `Authorization: Bearer <api_key>` to `https://api.wolfia.com/mcp/`	Headless / server-to-server clients that cannot open a browser

If you need an API key for an unattended integration, contact your Wolfia representative.

Rate limits

Authenticated MCP traffic is rate limited per credential and per organization, using a sliding window. Limits are tiered by how expensive the tool is:

Tier	Tools	Per credential (burst)	Per credential (sustained)	Per organization
Heavy	`send_message`	5 / second	20 / minute	80 / minute
Light	All other tools	20 / second	120 / minute	480 / minute

Clients that exceed a limit receive a rate-limit response and should back off and retry.

Troubleshooting

`{"detail":"Invalid redirect URI"}`

This is the most common integration error and it has one root cause: the client sent a redirect_uri that fails the redirect URI rules. Work through these in order:

Is the redirect URI HTTPS? Any non-localhost redirect URI must use https://. A plain http:// callback on a real domain is rejected.
Is it a full, well-formed URL? It must include both a scheme and a host (for example https://host/path). A bare host or a relative path is rejected.
Behind a gateway? Check the gateway’s callback URL, not Wolfia. Make sure the gateway is configured to use its HTTPS callback as the redirect URI and is performing Dynamic Client Registration.
Stale cached registration? Clear the client’s cached MCP auth (for mcp-remote, rm -rf ~/.mcp-auth) and reconnect so it re-registers cleanly.

There is no Wolfia-side allowlist to change, so the fix always lives in the client or gateway configuration.

Restart the client after editing its MCP config.
Confirm the client reached the authenticated MCP endpoint at https://api.wolfia.com/mcp/.
Make sure you signed in with an account that belongs to your Wolfia organization.

Token expired

Access tokens last 30 days and are refreshed automatically using the refresh token. If a client stops working after a long idle period (beyond the 90-day refresh window), trigger a fresh sign-in by clearing the cached tokens and reconnecting.

Requirements

An MCP-compatible client, gateway, or your own OAuth 2.1 client implementation.
A Wolfia account with access to your organization.
For interactive sign-in, a browser available on first connect.

​Overview

​How authentication works

​Discovery endpoints

​Endpoint reference

​Dynamic Client Registration

​Token lifetimes

​Redirect URI rules

​Connecting directly (streamable HTTP)

​Connecting through a gateway or proxy

​Authentication options

​Rate limits

​Troubleshooting

​{"detail":"Invalid redirect URI"}

​Sign-in succeeds but tools do not appear

​Token expired

​Requirements

Overview

How authentication works

Discovery endpoints

Endpoint reference

Dynamic Client Registration

Token lifetimes

Redirect URI rules

Connecting directly (streamable HTTP)

Connecting through a gateway or proxy

Authentication options

Rate limits

Troubleshooting

`{"detail":"Invalid redirect URI"}`

Sign-in succeeds but tools do not appear

Token expired

Requirements