Connect an AI agent (MCP)

Connect an agent to roasOS, and it gets the whole product as tools. The door changes, and the rules do not: a paid tool quotes first, and the server never approves spend.

The tools cover your brand, competitor research, every model, and the roasOS agent itself. This page connects a client, names every tool, and states what the server refuses to do.

MCP works on every plan. Each paid tool uses the credits on your account. API keys for the REST API need the Growth or Scale plan.

The server

roasOS runs one MCP server. One worker serves the REST API and the MCP server. A tool and its REST operation are therefore the same code.

The server binds one REST operation to each tool. It forwards the call to that operation, and the operation authorizes it again. Scopes, entitlement, rate limits, spend policy, quotes and idempotency therefore cannot drift between the two doors. The rate limit is the rate limit of your key. Refer to Authentication.

The transport carries four headers and no others: Authorization, Idempotency-Key, X-RoasOS-Project and X-RoasOS-Cost-Center. A cookie never travels.

There is no SSE transport and no stdio transport. The server keeps no session, so each request stands alone.

Use with Claude

Claude (claude.ai and the Claude apps) connects with OAuth. You do not need an API key.

1. In Claude, open Settings → Connectors.
2. Find ROASOS in the directory and select Connect. If you do not find it, select Add custom connector and type the URL https://mcp.roasos.com/mcp.
3. Sign in to ROASOS. The consent screen shows the host that the connection returns to (claude.ai), the name the app gives, and what the connection can do.
4. Select the workspaces, at most 25. The workspaces that you own are selected at the start. A workspace that you only administer uses the credits of its owner, so you select it yourself. Clear the ones that the connection must not use.
5. Select Connect. Claude returns and lists the ROASOS tools.

One connection can use all the workspaces that you selected. Credits come from the balance of each workspace owner, the same as in the app. If you own all the workspaces, they share your one balance.

• roasos_list_workspaces gives the id and the name of each connected workspace, and the default workspace. The default is the first one in the list: a workspace that you own, when you selected one.
• When the connection has more than one workspace, each tool takes workspace_id. A tool that reads uses the default workspace if you do not send workspace_id. A tool that writes or spends must have workspace_id, so that a model never spends in a workspace by default.

Each connection makes one API key in each selected workspace. Its name is MCP · and the app name, for example MCP · Claude. Each key counts toward the limit of 10 active keys in its workspace.

To disconnect fully, revoke the MCP · keys in workspace settings. When you remove the connector in Claude, Claude stops calling, but the keys stay active until you revoke them, or until your next connection replaces them. After a revoke, that workspace leaves the connection. When no workspace is left, the next call answers 401 invalid_token and Claude asks you to sign in again.

Every paid tool and every tool that changes existing data is marked destructive (destructiveHint: true), so a client such as Claude can ask you before it runs one. A paid tool also needs a quote and then a confirm. Refer to Money.

Connect a client

Three recipes follow for clients that send a header. Each one uses the same key as the REST API. Make the key in your workspace settings.

Claude Code

claude mcp add --transport http roasos https://mcp.roasos.com/mcp \
  --header "Authorization: Bearer $ROASOS_API_KEY"

The command writes a local entry. Add --scope project to write .mcp.json beside your code. Add --scope user to reach every project.

Then type /mcp in Claude Code. The client lists the roasOS server and its tools.

The short forms are -t for --transport and -H for --header. Command form from the Claude Code MCP reference, read on 2026-08-22.

A configuration file

Claude Desktop and most file-configured clients read an mcpServers block.

{
  "mcpServers": {
    "roasos": {
      "type": "http",
      "url": "https://mcp.roasos.com/mcp",
      "headers": {
        "Authorization": "Bearer roasos_sk_..."
      }
    }
  }
}

Set type to http. An entry with a url and no type is a configuration error. The value streamable-http is an accepted alias for http.

The file then holds your key. Keep it out of version control.

claude.ai

claude.ai signs in with OAuth and sends no header. Refer to Use with Claude. Leave the OAuth client id and client secret fields empty: the connector registers itself.

Your own client

Send JSON-RPC over HTTP POST.

curl -X POST https://mcp.roasos.com/mcp \
  -H "Authorization: Bearer roasos_sk_..." \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

The Accept header must name both types. A request that names one answers 406, with the message Client must accept both application/json and text/event-stream.

The answer is JSON. An initialize call reports the protocol version and the server name. It also carries the server instruction: paid actions are quote-first, and the server never approves spend.

A browser client must send an allowed Origin. The three allowed values are https://mcp.roasos.com, https://api.roasos.com and the roasOS app. Another origin answers 403. A request with no Origin header passes.

OAuth and the hostname

OAuth 2.1 is live on https://mcp.roasos.com. A client that supports OAuth (for example a claude.ai custom connector) signs in with your roasOS account; it needs no API key. Discovery is at https://mcp.roasos.com/.well-known/oauth-authorization-server, and the scopes are api:read and api:write.

An API key also works, for a client that can carry a bearer header.

• A request with no Authorization header answers 401. Its WWW-Authenticate header is a Bearer challenge. The challenge names resource_metadata and the scopes api:read api:write, so an OAuth client can start sign-in.
• An unknown key or a bad token answers 401. Its WWW-Authenticate header carries error="invalid_token".
• A connection whose keys were all revoked or have expired answers 401 invalid_token on every POST, and its refresh token answers invalid_grant. The client signs in again.
• Plain http:// on mcp.roasos.com answers 400. The server does not redirect. Use https://.

The tools

Each tool carries its own marks. Read them before you call one.

The lists below use three words. Read is a tool that changes nothing. Paid is a tool that can spend credits. Free write is a tool that writes and charges nothing.

Account and platform (6).

Catalog (3).

Jobs (9).

roasos_get_job gives the exact request of the job under inputs, with the endpoint. roasos_rerun_job sends that request again through the same endpoint, with an optional new prompt. It quotes first. A job with no recorded request answers 409 rerun_inputs_unavailable. A job that carries a statement of media rights answers 409 rerun_requires_new_rights_statement, because a person must make that statement again.

roasos_show_media_job opens an inline viewer on a host that supports MCP Apps. The viewer is the resource ui://roasos/media-viewer.html. It loads media only from cdn.roasos.com. Another host gets the same JSON as roasos_get_job.

roasos_cancel_job cancels only a job that the same connection started. The same connection is the same API key, or the same OAuth grant. Each OAuth grant has its own key, so a reconnect starts a new connection. A job that a person started in the roasOS app, or that a different key or grant started, answers 403 job_not_cancelable_by_caller. The person can cancel that job in the roasOS app. When the job is not yet at the model provider, it stops and all its credits come back (cancel_honoured: true). When the provider already has the job, it runs to the end and roasOS bills it (cancel_honoured: false). A job that already finished answers 409 job_not_cancelable. These are the REST cancel rules, and the refunds are the same.

Generations (8).

A batch is two calls. roasos_quote_generation_batch quotes up to eight generations and returns a batch_quote_id. roasos_create_generation_batch takes that batch_quote_id and admits all the jobs at once. The server remembers the key of the quote for one hour, so create the batch inside that hour. After one hour, or when the quote is unknown, the create answers batch_quote_unknown: quote the batch again. When the quote answers approval_required, a person approves it at its authorize_url before the create. Then wait for the jobs with roasos_wait_for_jobs.

Scenes (2).

Avatars (2).

Products (4).

roasos_list_products takes query for text in the name, brand or description, and url for one product page. The scheme, www., the query string and a trailing slash do not count.

roasos_build_product_kit is quote-first, as every paid tool is. Send full: true for eight angles, or an angles list. With neither, the tool builds the four core angles. First call it with quote_only: true. The quote charges nothing. Then send the same input with the quote_id. The confirm charges exactly the quoted credits and starts the kit job. When a kit job already runs for the product, the confirm answers 409 kit_job_running and charges nothing. Wait for the job with roasos_wait_for_jobs, then read the kit with roasos_get_product. Refer to Product kits.

Uploads (3).

roasos_import_social_post copies the media of one public TikTok, Instagram, X or Meta post into your workspace. The request must carry media_rights. Send it only after the person states that they may use this post. roasOS records the statement before it copies a file. A file over 16 MiB is refused.

Projects (2).

One chat is one project. Pass the conversation_id of a project to roasos_agent_ask to work inside it.

Measured reading (5).

A frame is a workspace image that you can use again. roasos_view_filmstrip measures cuts by the difference between sampled frames, and the answer states the sample interval. roasos_analyze_ad gives the same measurement under measured_cuts in its result. A read that roasOS already stored costs nothing and needs no confirm.

Discover (2).

Research (4).

Research reads the Facebook Ad Library. roasos_run_research takes one of two capabilities.

A keyword search also takes filters.media_type (ALL, IMAGE or VIDEO) and filters.sort_by (total_impressions or relevancy_monthly_grouped). A live fetch costs 1 credit. A fresh cache hit costs nothing, and cache_disposition reports which one happened.

Workflows (11).

An analysis costs 1 credit for a still and 3 credits for a video. A brand extraction costs 2 credits. Refer to Workflows.

Agent runs (6).

Skills (3).

roasos_list_skills also lists the roasOS production guides. A guide has an id that starts with guide:. Its requires states the MCP tools and host features that it needs. Read a guide with roasos_get_skill. You read a guide. You cannot run it. Send kind: guide or kind: saved to narrow the list.

Voices (4).

roasos_search_voices finds voices by purpose, in the voice library and in your workspace. roasos_design_voice makes one speech sample from a written brief. To keep the voice, send the URL of the sample to roasos_create_voice. noise_reduction: true cleans the sample for a MiniMax clone. roasOS has no tool that removes noise from a speech file. Deleting a voice stays a REST operation.

Saved edits (5).

A saved edit is a stored cut with versions. A batch of commands applies whole or not at all. Rendering the same version returns the same job. Refer to Saved edits.

The brain (10).

These ten are the brain families: the brand kit, the memory and the intelligence. The two update tools merge. A field that you omit keeps its value. jtbd_forces, colors and fonts merge for each role, so send only the role that you change. roasos_extract_brand fills the brand kit and belongs to Workflows, because it spends. Refer to Brand.

Model endpoints (77).

Each model endpoint carries one tool. Every one of them carries the paid mark. The name is roasos_, then the family, then the model id. Each - and each . becomes _.

• roasos_image_nano_banana_pro calls POST /v1/image/nano-banana-pro.
• roasos_video_kling_4 calls POST /v1/video/kling-4.
• roasos_assembly_compose calls POST /v1/assembly/compose.

Call roasos_get_catalog for the model ids, the units and the credit examples. Its roles list gives the default model for each job, such as identity-locked people, static ads or a music bed. Models change, so choose by job from roles and not by a model name you remember. You can always name another catalog model. Each model also has its own page, such as Kling 4.0.

The tools that roasOS does not bind

Three actions have no tool. Each one is absent by decision.

Refer to Memory for the pin that only your own software can delete.

The manifest declares seven more tool names. The server binds none of them.

Every delete in the two tables follows one rule: a connected model may write, and it must never erase. A delete stays a REST operation, under your key and your own software.

Money

One value, on every paid call

Send either quote_only: true for a price, or a quote_id to confirm a price.

A paid call with neither quote_only nor a quote_id answers quote_required. That message states that the tool never auto-approves spend. The refusal happens before the action starts, so it does not charge.

The server picks the Idempotency-Key of each paid call for you. You do not send one.

• Each quote_only: true call gets a new key. The server keeps that key with the quote_id while the quote is valid.
• A confirm with that quote_id uses the same key. A retry of the confirm therefore never charges twice.
• To run the same input again, quote it again. The new quote gets a new key.

A confirm must carry the input of its quote. Only webhook_url and wait_timeout_seconds can change. A confirm that changes another field answers quote_input_changed. Quote the new input with quote_only: true.

A tool error carries isError: true and the REST error body. Every error carries a request_id. Give it to support when you report a problem.

{ "error": { "code": "quote_required", "message": "...", "retryable": false, "request_id": "..." } }

An error that the server can repair with a new quote also carries next_step. It tells the model which call to make next.

A grant with api:read only lists the read tools. A write tool or a paid tool is not in tools/list for that connection.

A read tool and a free write tool need neither value. The server checks the paid mark first, and a free tool never asks for a quote.

What a paid tool gives back

Three shapes, and three read paths. Do not merge them.

To wait for jobs, call roasos_wait_for_jobs after you start the generations. Give it up to 12 job ids in ids. It returns when all the jobs are finished, or after timeout_seconds (default 50, maximum 55). When all_terminal is false, call it again with the ids that are not finished. Then read each result with roasos_get_job_result. Do not poll roasos_get_job_status for each job.

Each family has its own status words. Refer to Jobs for the job words, and to Runs for the run words.

The approval card

An agent run proposes each paid generation before it starts one. The proposal opens an approval on the run, and the work waits there.

The run approves the generation itself when both of these hold:

1. The price is inside the credits that remain in generation_spend_cap_credits.
2. The price is inside auto_approve_up_to_credits on your key.

The run then writes a gate_auto_approved event and continues. In every other condition the approval waits in pending_approvals, and roasOS charges nothing for it.

One approval card carries at most eight quotes. A storyboard that compiles to more than eight requests waits for a person.

Approving spend is never a tool

A connected model can decline an open approval with roasos_agent_decline_approval. It cannot approve one.

• A roasos_agent_ask run has a thread in roasOS. A person approves its paid action in the roasOS app, on the card in that thread. The approve_url of the approval names the thread.
• A skill run or a workflow run (roasos_run_skill, roasos_remix_ad, roasos_statics) has no thread, so it has no card. Its approve_url is the REST approve path.
• Your own software approves any run over REST, with POST /v1/agent-runs/{id}/gates/{gate_id}/approve. That call carries your key and obeys the spend policy of your key.

The approve operation stays out of the tool list on purpose. A connected model therefore cannot turn a review step into a rubber stamp. Refer to Spend caps and approvals.

The caps and the policy

An agent run carries two caps, and neither one replaces the other. max_credits bounds the tokens that the run's own thinking uses. generation_spend_cap_credits bounds the paid work that the run starts without a person, and its default is 0. A quote returns the sum of the two as a ceiling. roasOS reserves that ceiling, meters the true cost, and refunds the difference.

Your key holds the policy above both caps, and the policy always wins. roasos_get_limits reads it: max_credits_per_request, auto_approve_up_to_credits, daily_credit_budget, monthly_credit_budget, allowed_models, the credits used, and the two reset stamps. Both stamps are UTC midnight. auto_approve_up_to_credits is the value that unlocks an unattended run. A key at 0 starts no run at all: the run tools answer 402 approval_required, and nothing charges. Refer to Quotes and credits.

The twelve pack skills

The fastest work an agent can start is a pack skill. roasos_run_skill takes an id, or one of these roasos: slugs.

Every skill run is one agent run, so the caps, the approvals and the read paths above hold. Two of the twelve also have a typed door. roasos_remix_ad and roasos_statics start the same work from a typed body. Refer to Skills.

Limitations

• The server keeps no session. There is no SSE stream and no stdio transport. A GET or DELETE on /mcp answers 405.
• No tool deletes a record. Refer to The tools that roasOS does not bind. One tool removes data as a side effect: roasos_create_memory_pin drops the oldest pin in a category when the category has more than fifty pins.
• One connection covers at most 25 workspaces. A workspace that you make after you connect is not in the connection. Connect again to add it.
• A connected model cannot approve spend. A paid tool needs a quote and then a confirm with its quote_id.
• A tool answer is JSON text. The tools do not declare an outputSchema. Only roasos_show_media_job also sends structuredContent, for its media viewer.
• A connection has the rate limit, the spend policy and the credits of its workspace key. Refer to Authentication.
• A workspace holds at most 10 active API keys. Each MCP connection uses one in each of its workspaces. When a new connection finds the workspace full, it revokes the least recently used MCP key of yours in that workspace, and the connection that held it.
• Long jobs do not finish inside one call. Wait with roasos_wait_for_jobs, then read the result.
• roasos_import_social_post refuses files over 16 MiB.
• The four roasos_generate_* tools are deprecated. Their REST operation has a Sunset of 30 November 2026. Use a model-endpoint tool.

Troubleshooting

Each error carries a request_id. Send it to support when you report a problem.

Data handling

• What a tool reads and writes. A tool reads and writes only the workspaces that you connected. It uses the same REST operation and the same records as the ROASOS app.
• What the server logs. Each MCP request writes one api_requests row: the method, the tool name, the status, the duration, the IP address and the user agent. A tool call also writes the row of the REST operation that it runs. That row has the REST path, which can contain the id of a record, for example /v1/jobs/<id>. No row contains the tool arguments or the results.
• Your conversation. The server receives only the tool calls that the client sends. It does not receive or store the rest of your conversation. A prompt that you send to roasos_agent_ask is stored as a message in a ROASOS project, as it is in the app.
• Credentials. The OAuth provider keeps no token in plain text. For the API key that a grant makes, ROASOS stores a SHA-256 hash and a short display prefix (the first 8 and the last 4 characters), never the key. No tool returns a key or a secret.
• Quotes. The server keeps the link between a quote and its confirm for the life of the quote, at most 24 hours.
• Media. Media that you generate or import is stored in your workspace, the same as media from the app.
• Third parties. A paid tool sends its input to the model provider that runs it. Three free tools also reach outside ROASOS: roasos_import_social_post (the social platform), roasos_create_upload (a public URL that you give) and roasos_create_product (an App Store listing). These tools have openWorldHint: true.

Refer to the Privacy Policy and the Terms.

Your first five minutes

1. Connect. Run the claude mcp add command above, or paste the mcpServers block into your client.
2. List the tools. Type /mcp in Claude Code, or call tools/list. Every tool name starts with roasos_.
3. Read the brand. Ask for roasos_get_brand_kit and roasos_get_intelligence_context. Both are free, and both tell your agent who the workspace sells to.
4. Analyze an ad. Ask your agent to quote roasos_analyze_ad on one ad URL. Confirm the quote with its quote_id, poll roasos_get_ad_analysis_status, then read roasos_get_ad_analysis_result. The price is 1 credit for a still and 3 credits for a video.
5. Quote a generation. Read roles in roasos_get_catalog, pick the model for your job, and ask for its tool with quote_only set to true. Read the credits field. Stop there. Nothing spends until you send the quote_id back.

Then hand the whole job to the agent. roasos_agent_ask plans the work, chooses the models, and calls these same tools under your caps. Refer to Agent.