> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wolfia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Wolfia MCP Server: OAuth, Direct Connections & Gateways

> How Wolfia's MCP server handles OAuth: Dynamic Client Registration, PKCE, redirect URI rules, connecting directly or through a gateway like Runlayer, and fixing the 'Invalid redirect URI' error.

## 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](/how-to/mcp-server). 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.

<Note>
  **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.
</Note>

## 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:

<Steps>
  <Step title="Discovery">
    The client reads Wolfia's published OAuth metadata and learns every endpoint it needs. No values are hardcoded or shared out-of-band.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Token exchange">
    The client exchanges the authorization code at `POST /mcp/token` for a bearer access token and a refresh token.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## 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:

```json theme={null}
{
  "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.                                |

<Warning>
  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.
</Warning>

## 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](/how-to/mcp-server).)

## 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.

<Steps>
  <Step title="Point the gateway upstream at Wolfia">
    Configure the gateway's upstream MCP server as `https://api.wolfia.com/mcp/`.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Sign in once">
    The first connection opens a browser for your Wolfia sign-in. After approval, the gateway holds the tokens and proxies authenticated traffic to Wolfia.
  </Step>
</Steps>

<Note>
  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.
</Note>

## 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](#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.

### Sign-in succeeds but tools do not appear

* 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.