Sign-in for developers

How an AI app signs in: standard OAuth 2.1, found by discovery, with PKCE and dynamic registration.

Cloud, Self-hosted and Embed

A compliant MCP client needs nothing special. This page is for writing one, or finding why one fails.

The flow

Discovery

A call without a token answers 401. Its header points at the metadata, and names the scopes the server’s tools use:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="GoRunner",
  resource_metadata="…/.well-known/oauth-protected-resource/mcp/build",
  scope="workflow:read connection:read run:read workflow:write …"

Protected resource (RFC 9728)

/.well-known/oauth-protected-resource, then the server’s path: /mcp/build, /mcp/tools or a workspace’s own address

Authorization server (RFC 8414)

/.well-known/oauth-authorization-server

For /mcp/build, scope lists the six permissions of Draft, run and publish. For /mcp/tools, it lists workflow:read, run:read and workflow:run. Both documents are at your installation’s address, https://api.gorunner.io on Cloud, which is also the issuer.

Registration

Registration is open and makes a public client, with no secret.

curl -s -X POST "https://api.gorunner.io/oauth/register" \
  -H "Content-Type: application/json" \
  -d '{"client_name": "My agent",
       "redirect_uris": ["http://127.0.0.1/callback"]}'

{
  "client_id": "grc_69866495cb3c0a69d24c77a5aeb3068620b922cd",
  "client_id_issued_at": 1761412345,
  "client_name": "My agent",
  "redirect_uris": ["http://127.0.0.1/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none"
}

Callbacks

1 to 10. One that isn’t allowed is dropped, and the answer lists the ones kept. If none is left, registration fails.

Same app again

The same name, callbacks, logo and site get the same client back: one made in the last 12 hours, or one that already has a connection.

Limit

20 new registrations a day from one address that never lead to a connection.

Logo and site

A logo_uri or client_uri you send comes back in the answer, if it is a web address.

Callbacks

Since v2026.10.22

https

Any host.

http

Only localhost, 127.0.0.1 or [::1]. The port may change between sign-ins; the path may not.

An app’s own

Cursor’s cursor://anysphere.cursor-mcp/oauth/callback, and Raycast’s raycast://mcp-oauth-callback or com.raycast:/oauth. Any other app uses a reverse-DNS form, such as com.example.app:/callback. A self-hosted installation allows more exact app callbacks with OAUTH_EXTRA_REDIRECT_URIS: whole addresses, no query.

Never

A query on an app’s callback, a fragment, or a user name in the address.

Authorize and token

PKCE

S256 only. plain is refused.

Scopes

Any of the ten permissions, and offline_access. None asked for means read only. openid, profile and email are ignored. The person’s choice and role narrow them.

resource

/mcp/build, /mcp/tools, or an address under one. Left out, the token works on both. Anything else is invalid_target.

iss

On every redirect back, success or error. Since v2026.10.22.

The token request

application/x-www-form-urlencoded, with grant_type=authorization_code, code, code_verifier and client_id. A redirect_uri, if sent, must match the authorize request.

Tokens

A registered client always gets a refresh token, with or without offline_access. Since v2026.10.22.

To disconnect, post token as application/x-www-form-urlencoded to /oauth/revoke. Either token ends the whole connection. The answer is 200 with no body, whatever you send, so it can't be used to test a token.

When sign-in is refused

These answers are OAuth's own shape, {"error": "…", "error_description": "…"}, with error a string. The last two rows are in the API's shape instead.

A refresh token that answers invalid_grant will never work again. Stop retrying it, and start the sign-in from the beginning.

At /oauth/authorize, a bad client_id or redirect_uri shows the person a page with 400, and nothing goes back to the app. After those two are known good, an error goes back to the callback as error, error_description, state and iss: unsupported_response_type, invalid_request, invalid_target, invalid_scope, server_error, or access_denied when the person declines. To an app’s own callback (cursor://…), it is a page with a button instead of an automatic redirect, and only for the exact callbacks listed above.

Addresses

/mcp/build

The build server: Build tools

/mcp/tools

Your published workflows as tools

/mcp/build/w/<workspace ID>

One workspace’s own address. API tokens use it.

/mcp/tools/w/<workspace ID>

One workspace’s tools. A credential for another workspace gets 403.

/oauth/register, /oauth/authorize, /oauth/token, /oauth/revoke

The sign-in server

One address may make 120 sign-in requests a minute, discovery included. A self-hosted installation changes it with OAUTH_RATE_LIMIT.

How the servers answer

Sessions

None. Each request stands alone and no Mcp-Session-Id is sent, so every request needs its token.

POST

A request answers 200 with one JSON object, never a stream. A notification answers 202 with no body. Accept must allow both application/json and text/event-stream, or it is 400. Content-Type must be application/json, or it is 415.

GET, DELETE

405 with a working token, because there is no stream to open and no session to end. 401 without one, like every method.

401

No token, or an expired or revoked one. It carries the WWW-Authenticate header above, with error="invalid_token" when a token was sent. Refresh, or sign in again.

MCP-Protocol-Version

A version the server doesn’t know is 400. Left out, the call still works.

A method the server doesn’t have

A JSON-RPC error, -32601, on 200. A tool that fails is isError: true in a 200.

A 401 on GET is normal for a client without a working token. If they repeat with no sign-in after them, that client has lost its connection and needs someone to connect it again.

Related: Choose what an AI app may do · Connect with an API token · Authentication · v2026.10.22