# Setup (/mcp/setup) Add one URL to your AI client, then sign in in a browser. There is no API key. The workspace needs a paid plan or an active trial. API keys are only for the [REST API](/api/authentication) and the [CLI](/cli/setup). ## Add the server [#add-the-server] **Claude** Web or desktop. This link opens the "add connector" dialog with RiffAds already filled in: [Add RiffAds to Claude](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 the server URL, save. **Claude Code** Run this in a terminal: ```bash title="Terminal" claude mcp add --transport http riffads https://mcp.riffads.com ``` Or commit this file to share the server with everyone on a repo. Each person still signs in as themselves. ```json title=".mcp.json" { "mcpServers": { "riffads": { "type": "http", "url": "https://mcp.riffads.com" } } } ``` For ready-made ad steps, add the [Agent Skills](/skills/setup) plugin. **Cursor** This link opens Cursor with RiffAds ready to install: [Install in Cursor](https://cursor.com/en/install-mcp?name=riffads&config=eyJ0eXBlIjoiaHR0cCIsInVybCI6Imh0dHBzOi8vbWNwLnJpZmZhZHMuY29tIn0%3D) By hand: add this to `~/.cursor/mcp.json` (every project) or `.cursor/mcp.json` (one project). ```json title="mcp.json" { "mcpServers": { "riffads": { "type": "http", "url": "https://mcp.riffads.com" } } } ``` **VS Code** For Copilot agent mode. This link opens VS Code with RiffAds ready to install: [Install in VS Code](vscode:mcp/install?%7B%22name%22%3A%22riffads%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.riffads.com%22%7D) By hand: add this to `.vscode/mcp.json`. VS Code uses `servers`, not `mcpServers`. ```json title=".vscode/mcp.json" { "servers": { "riffads": { "type": "http", "url": "https://mcp.riffads.com" } } } ``` **ChatGPT** ChatGPT adds custom connectors in developer mode, on the web. 1. Open the connector settings with the link below. 2. Add a custom connector. 3. Paste the server URL and save. [Open ChatGPT connector settings](https://chatgpt.com/#settings/Connectors) **Any client** Most clients take the `mcpServers` file from the Cursor tab. The transport is streamable HTTP and stateless: `POST` a JSON-RPC 2.0 body with `Accept: application/json, text/event-stream`. Old clients that only speak HTTP+SSE cannot connect. > **Use the URL exactly** > > Paste the server URL exactly as shown at the top: no path and no trailing slash. A wrong URL means no sign-in window. ## Sign in [#sign-in] 1. The first time your client connects, it opens a browser on `app.riffads.com`. 2. Sign in with Google, or with email and password. 3. Approve. With one workspace, the connection uses it from now on. If a RiffAds consent screen appears, pick the workspace there, then **Generate and spend credits** or **Read only**. ## Pick a workspace [#pick-a-workspace] | Your account | What happens | | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------- | | One workspace | The connection uses it from the first call. Nothing to do | | Several workspaces, and no consent screen | Every ask is refused until you pick one. The refusal (`connection_not_configured`) links to the page below | | No workspace yet | Every ask is refused (`no_workspace`). Finish setting up a workspace in the app, then reconnect | To pick one, open your connections page and switch to the workspace you want. Then press **Use (workspace name)** or **Read only** next to the waiting agent. ## Read or spend [#read-or-spend] | Mode | Tools | What the agent can do | | ------------------ | ----- | ------------------------------------------- | | Spend (`spend`) | 23 | Everything, plus the two prompts | | Read only (`read`) | 17 | Browse, price and read. No jobs, no uploads | * New connections can spend. Change the mode on the [connections page](https://app.riffads.com/connections), then refresh the tool list in your client. * Anyone can set their own connection to read only. Only owners and admins can switch a connection to spend. * Spending is still capped: [Spend limits](/how-it-works#spend-limits). ## Check it [#check-it] Ask your agent: **Try asking:** > What are you connected to? It calls `riffads_ping`, which spends nothing. ```json title="riffads_ping result" { "user_id": "...", "organization_id": "...", "workspace": "Acme", "plan": "growth", "mode": "spend", "can_spend_credits": true, "server_time": "2026-09-28T10:28:41.002Z", "ok": true } ``` `workspace` is where credits come from. `can_spend_credits: false` means read only. ## First video [#first-video] **Try asking:** > Make a 5 second vertical video of a matte black water bottle on a gym bench, morning light, with sound. Use Kling 3 Pro. The agent prices it for free, asks for your yes, then submits, waits and hands you the link: [The flow](/how-it-works#the-flow). The calls, in order: `estimate_generation` on `kling_3_pro`, then `submit_generation` with the estimate's `max_credits_needed` as `max_credits`, then `wait_for_generation`. More ideas: [Prompting guide](/prompting). Every tool: [Tools](/mcp/tools). ## Custom clients [#custom-clients] Only for a client you build yourself. Other clients do this for you. 1. Call the server with no token. It answers `401` with a `WWW-Authenticate` header that names `resource_metadata`. 2. `GET` the protected resource document below. Use its `authorization_servers[0]` (today [https://app.riffads.com](https://app.riffads.com)), never a hardcoded host. 3. `GET` that server's `/.well-known/oauth-authorization-server` for the authorize, token and registration endpoints. 4. Register once (dynamic registration works), authorize in a browser, and exchange the code. Scopes: `openid profile email offline_access`. 5. Send `Authorization: Bearer ` on every call. An expired token answers `401`: refresh, or authorize again. ## Troubleshooting [#troubleshooting] | What you see | What to do | | -------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | No sign-in window opens | Check the server URL: no path, no trailing slash. The client must speak streamable HTTP | | The agent says it does not know which workspace to spend from (`connection_not_configured`) | You have several workspaces and none is picked. [Pick a workspace](#pick-a-workspace), then ask again. Asking before you pick changes nothing | | The agent can browse and price but not make anything, or sees only 17 tools (`read_only_connection`) | The connection is read only. An owner or admin switches it to spend on the [connections page](https://app.riffads.com/connections). Then refresh the tool list | | A job is refused over a spending limit (`spend_limit_exceeded`) | A workspace limit stopped it, and the refusal names which one: [Spend limits](/how-it-works#spend-limits) | | Not enough credits (`insufficient_credits`) | Top up on the [billing page](https://app.riffads.com/settings/billing) | | The agent says it is not signed in, or the workspace is gone (`not_authorized`, `workspace_unavailable`) | Reconnect, sign in and pick a workspace again | | Your plan does not include agents (`required_plan`) | The message names a plan that does | | Tools are missing, or "too many requests" (`429`) during setup | Wait a moment, refresh the tool list, or add the server again | Disconnecting deletes the tokens, but running work still finishes. Every refusal code: [Errors](/reference/errors).