Connect from claude.ai with OAuth, no token to paste

What you do

In claude.ai open Settings → Connectors → Add custom connector and paste https://runicflow.ai/api/mcp as the URL (a trailing slash is fine). claude.ai opens Runic’s authorization page. If you are not signed in, the sign-in card appears first and brings you back. The consent card — “Runic / Connect an application”, “Claude wants to access your Runic account”, “Signed in as you@example.com. Not you? Switch account” — lists what it will allow: “Read your documents” (list, read, search, lint, render and export every process flow and sequence diagram in your account) and “Create and edit documents” (write, create, rename and restore documents, and create public share links; every edit is snapshotted first, so it can be undone). Below it: “You will be sent back to <host>. The access lasts until you revoke it under Settings → Claude & MCP; the application refreshes it on its own.” — the host being the callback address the client registered. Press Allow (Deny sends the client an access_denied error and nothing else). That is the whole setup; no token is copied anywhere.

What happens behind the click

claude.ai first calls the endpoint without credentials and gets a 401 whose WWW-Authenticate header names the resource metadata document. It reads /.well-known/oauth-protected-resource (also at the path-suffixed /.well-known/oauth-protected-resource/api/mcp that 2025-06-18 clients try first) and /.well-known/oauth-authorization-server, which name Runic as the authorization server, the scopes read and write, PKCE S256 as the only challenge method, and the four endpoints: /oauth/authorize, /api/oauth/token, /api/oauth/register and /api/oauth/revoke. It registers itself with dynamic client registration — client name “Claude”, redirect URIs, no secret; Runic issues public clients only, substitutes “none” for a requested client_secret_post, and returns the same client for the same name and redirect set, so reconnecting never piles up registrations. Then it sends you to /oauth/authorize with a PKCE challenge and a state.

Your Allow mints a single-use authorization code (10-minute life, stored hashed) and the browser carries it back to claude.ai, which exchanges it at /api/oauth/token with its PKCE verifier for an access token (runic_…, one hour) and a refresh token (runicr_…, 30 days). Every refresh rotates the pair and restarts the 30 days; a refresh token that is replayed after rotation, or an authorization code presented twice, revokes the whole grant family, which is how a leaked token cannot be used quietly alongside the real client. Requests may also carry a resource indicator, which must equal the MCP endpoint. Consents are limited to 30 an hour per user, registrations to 100 an hour per address.

Where it shows up, and how to end it

The connection is a row under Settings → Claude & MCP named “OAuth · Claude” — in general “OAuth · <client name as registered>” — with a scope pill (“read-only” or “read · write”), a violet “oauth” pill, the created and last-used dates and an expiry note: “access expires <date time>” while the access token is live, “access expired, renews on next use until <date>” while only the refresh token is, “expired” after that. Each refresh replaces the row. Revoke kills access and refresh together and the rotation trail with them; the client’s next call gets a 401 and it will ask you to reconnect. A client can also revoke itself at /api/oauth/revoke. Deleting the account or suspension removes every token, code and grant. At most 20 OAuth rows are kept per account — past that the oldest is dropped, and rows whose refresh token has expired are swept on each new issue; they do not count toward the five personal tokens.

Other OAuth clients

Nothing in the flow is specific to claude.ai. Any client that implements the MCP authorization spec — Claude Desktop’s remote servers, MCP Inspector, an agent of your own — discovers, registers and signs in the same way. Registration accepts up to 10 redirect URIs of at most 2,048 characters each, either absolute https addresses or http://localhost, http://127.0.0.1 and http://[::1] on any port for desktop clients, with no fragment and no userinfo; a registered loopback URI may come back on any port. A client that instead takes a URL and headers can still use a personal token with Authorization: Bearer. If the authorization page shows an error card — “Unknown client”, “Redirect URI not registered”, or “Invalid request (<error>)” — nothing was sent anywhere; a “Continue to <host>” link carries the error back to the application only when you click it, so an attacker cannot use Runic as a redirector.

What it costs and what it can do

The Runic server calls no model; claude.ai’s model, on your Claude plan, runs the tools and prompts. So a connector conversation never touches Runic’s monthly AI budget or a key you stored. What claude.ai can do is exactly the MCP tool set: read, search and lint; write, create, rename, restore and share when the grant carries write scope; render diagrams inline; run the six prompts. A client that asks for the read scope alone gets a read-only grant and the five write tools answer with the read-only sentence.

How to use it

1. 1
   Add the connector

   claude.ai → Settings → Connectors → Add custom connector → paste https://runicflow.ai/api/mcp.
2. 2
   Sign in to Runic if asked

   The authorization page sends you through /login and back. “Switch account” on the consent card signs you out and returns to the same request if the wrong account is shown.
3. 3
   Read the scopes and press Allow

   “Read your documents” and “Create and edit documents” are listed with what each allows. Deny sends claude.ai an access_denied error and grants nothing.
4. 4
   Use it

   Ask Claude to list your documents, audit one, or render it; the reply carries the diagram. Claude renews its access on its own.
5. 5
   Check or revoke the connection

   Settings → Claude & MCP lists it as “OAuth · Claude” with scope and expiry. Revoke ends access and refresh together.

Commands & shortcuts

Tips

• Reconnecting after a Revoke is the same three clicks; the client re-registers idempotently and asks for consent again.
• If you share a computer, use “Switch account” on the consent card before pressing Allow — the grant goes to the account shown.
• An “access expired, renews on next use” note is normal between conversations: the client refreshes the moment it next calls.
• For a connector that should only read, the client has to ask for the read scope; with a personal token you decide with the Read-only checkbox.

Questions