Connect an MCP client

Add one URL to your client. Sign in once in a browser. Your agent gets up to 17 RiffAds tools.

Server URL

https://mcp.riffads.com

No API key. MCP is OAuth 2.1 only. Keys (sk_live_...) are for the REST API and the CLI.
The workspace needs a paid plan. Without one, tools refuse with required_plan.
Want a first video right away? Go to the MCP quickstart.

Add the server

Open this link to get the add dialog prefilled:

Prefilled connector dialog

https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=RiffAds&connectorUrl=https%3A%2F%2Fmcp.riffads.com

By hand: Settings, Connectors, Add custom connector. Paste https://mcp.riffads.com. Save.

Use the URL exactly

https://mcp.riffads.com. No path, no trailing slash. A wrong URL means no sign-in window.

The first tool call opens a browser on app.riffads.com.
Sign in with Google, or email and password.
Approve. You only see a consent screen if the client sends prompt=consent (Claude does not). There you pick the workspace and spend or read only.

Check the connection

Call riffads_ping. No arguments. Spends nothing.

riffads_ping result

{
    "ok": true,
    "user_id": "...",
    "organization_id": "org_...",
    "workspace": "Acme",
    "plan": "launch",
    "mode": "spend",
    "can_spend_credits": true,
    "server_time": "2026-09-17T10:28:41.002Z"
}

workspace: the workspace this connection uses.
can_spend_credits: false: read only. The 5 spend tools are missing.

Which workspace it uses

An MCP token is a person, not a workspace. The connection holds the workspace.

Your account	What happens
One workspace	Binds on first use.
More than one, no consent screen	Nothing binds. Every call refuses with `connection_not_configured`.
Client showed a consent screen	You picked it there.
No workspace	Every call refuses with `no_workspace`.

connection_not_configured

{
    "ok": false,
    "code": "connection_not_configured",
    "message": "This RiffAds account has more than one workspace, so this connection does not know which one to spend from. Choose one at https://app.riffads.com/connections, then try again.",
    "retryable": false,
    "credits_charged": 0,
    "connect_url": "https://app.riffads.com/connections"
}

Retrying changes nothing. Pick the workspace at app.riffads.com/connections, then call again.

Read or spend

Mode	Tools	Can do
`read`	12	Browse, estimate, read generations and runs.
`spend`	17	Plus `submit_generation`, `generate_talking_actor`, `run_workflow`, `create_upload`, `finalize_upload`.

New connections can spend, unless you chose read only.
Uploads count as spend tools.
Change the mode at app.riffads.com/connections. Anyone can narrow their own. Only owners and admins can widen.
After a change, refresh the client's tool list. A stale list calling a spend tool gets read_only_connection.

OAuth discovery (custom clients)

Most clients do this for you. Building your own:

Call with no token. You get 401:

WWW-Authenticate

Bearer error="invalid_token", error_description="Missing Authorization header", resource_metadata="https://mcp.riffads.com/.well-known/oauth-protected-resource"

Fetch resource_metadata:

GET https://mcp.riffads.com/.well-known/oauth-protected-resource

{
    "resource": "https://mcp.riffads.com",
    "authorization_servers": ["https://app.riffads.com"],
    "scopes_supported": ["openid", "profile", "email", "offline_access"],
    "bearer_methods_supported": ["header"],
    "resource_name": "RiffAds"
}

Read authorization_servers[0]. Do not hardcode it. Fetch its /.well-known/oauth-authorization-server for the authorize, token and registration endpoints.
Register (dynamic registration works), authorize in a browser, exchange the code.
Send Authorization: Bearer <access token> on every call.

Scopes gate nothing on MCP. The connection mode decides what a token can call.

Per address, before any token: 10 registrations per 10 minutes, 120 requests a minute on the MCP endpoint. Over either: 429 with Retry-After and no JSON-RPC body.

Token problems answer 401 with a plain OAuth body:

`error_description`	Fix
`Missing Authorization header`	Send the token.
`Invalid Authorization header format, expected 'Bearer TOKEN'`	Use the `Bearer` scheme.
`Unknown, revoked or expired access token`	Authorize again.
`Token has expired`	Refresh, or authorize again.
`Access token has no usable expiry`	Authorize again.
`Access token is not bound to a client`	Authorize again.

Troubleshooting

Symptom	Cause	Fix
No sign-in window	Wrong URL, or not a streamable HTTP client	URL exactly `https://mcp.riffads.com`
Every tool answers `connection_not_configured`	Several workspaces, none picked	Pick one at app.riffads.com/connections
Only 12 tools	Read only connection	Allow spending, refresh the tool list
`not_authorized`	Token revoked or bad, or account blocked	Reconnect and sign in again
`workspace_unavailable`	Workspace deleted, or you left it	Reconnect, pick a workspace you are in
`no_workspace`	Account has no workspace	Finish setup at app.riffads.com, reconnect
`required_plan`	Plan does not include the agent API	The message names the plan that does
`429` with `Retry-After` during setup	Per-address limit	Wait, register once

Disconnecting deletes the tokens. The agent must reconnect from scratch. Work already running finishes.
Switching workspace in the browser does not move a connection.
Tool refusals are JSON with code, message, retryable, credits_charged. Branch on code. See errors.