Authentication

The Orisu MCP endpoint accepts two auth modes. Both end up at the same set of tools. The only difference is how the bearer token is obtained.

Current public endpoint. The Orisu MCP server lives at https://api.orisu.ai/mcp. The same URL is shown in your Orisu dashboard under Settings → Connectors → MCP — that page always reflects the production endpoint for your account, even if this doc is briefly out of date after a rebrand or region change.

OAuth (chat clients)

When you add Orisu as a connector in Claude or ChatGPT, the host runs an OAuth flow against the Orisu web app. You sign in, see a consent screen listing the scopes the connector needs, approve, pick a workspace (if you have multiple), and the host now holds a refresh token. Every MCP call attaches a bearer token derived from it. The flow:

Host fetches /.well-known/oauth-authorization-server from the API
Host dynamically registers itself as an OAuth client (Dynamic Client Registration)
Browser opens to the Orisu consent screen: you sign in (if needed) and approve scopes
Host receives an authorization code, exchanges it at the token endpoint
Host caches the access + refresh tokens; refreshes silently when access tokens expire

The first consent binds the connector to one of your workspaces. If you belong to multiple, you can rebind later by removing + re-adding the connector.

API keys (scripts)

For server-to-server use (cron jobs, internal tooling, custom MCP hosts), generate an API key from your Orisu dashboard → Settings → API Keys. The key format is pk_live_*. Send it as a Bearer token to the same endpoint:

curl -X POST <YOUR_MCP_ENDPOINT> \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer pk_live_xxxxxxxxxxxxxxxxxx' \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

API keys carry a fixed scope set you choose at creation time. They never expire (revoke + reissue to rotate). Keys are bound to a single organization, so pick the right org when generating.

Scopes

Scope	Allows
`agents:read`	List agents, read graphs, validate specs, port resolution, model suggestions, cost estimates
`agents:write`	Create / replace / update / clone / delete agents, restore versions, manage shares
`runs:read`	List runs, wait for runs, read `orisu://runs/{id}`
`runs:execute`	Trigger runs, cancel runs
`apps:read`	List apps, read app metadata
`apps:execute`	Trigger apps, publish apps, submit reviews
`assets:write`	Upload assets via the connector
`openid`	Required for OAuth flow (identity)
`offline_access`	Required for OAuth refresh tokens

The OAuth consent screen requests the minimum scopes the connector needs to be useful. For API keys, only include the scopes the script actually needs. A read-only monitoring script doesn’t need agents:write or runs:execute.

Errors

If a tool needs a scope you don’t have, the call fails with a typed error:

{
  "code": "SCOPE_MISSING",
  "message": "trigger_run requires 'runs:execute' but the bearer carries: agents:read, runs:read",
  "next_action": "Ask the user to reconnect Orisu and grant 'runs:execute', or use an Orisu API key (pk_live_*) whose scope set includes runs:execute."
}

See Errors for the full code list.

Quickstart

Add the connector to Claude or ChatGPT.

Errors

Auth errors and how to recover from them.

Get started

Reference

Operations

Authentication

OAuth (chat clients)

API keys (scripts)

Scopes

Errors

See also

Quickstart

Errors

​OAuth (chat clients)

​API keys (scripts)

​Scopes

​Errors

​See also

Quickstart

Errors

OAuth (chat clients)

API keys (scripts)

Scopes

Errors

See also