Agent setup: connect roasOS MCP

This page is for an AI agent. Do the steps in order. Do not skip a check. Refer to Connect an AI agent for the full reference.

1. Find the client

Identify the client that runs you.

2. Claude Code

Ask the person for an API key only if they have one. Do not ask them to paste a key into the chat. Tell them to set ROASOS_API_KEY in their shell.

Run this command when the variable is set:

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

When there is no key, run this command, and tell the person to approve the browser sign-in:

claude mcp add --transport http roasos https://mcp.roasos.com/mcp

Go to step 5.

3. A JSON configuration file

Add this entry to mcpServers in the file of the client. Keep the other entries.

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

Tell the person to restart the client. Go to step 5.

4. A web client

Tell the person to connect ROASOS from the Claude connector directory, or to add a custom connector with the URL https://mcp.roasos.com/mcp, then sign in and pick a workspace. You cannot do this step for them. Go to step 5 after they say that it is done.

5. Check the connection

Call roasos_get_account. It is free.

6. Learn the rules before you spend

1. Call roasos_list_skills with kind: guide. Read the guide for the job with roasos_get_skill.
2. Call roasos_get_catalog. Pick a model by its job. Use expected_generation_ms to decide if you wait.
3. Every paid tool quotes first. Send quote_only: true, then show the person the credits.
4. Send the quote_id only after the person agrees. You cannot approve spend for the person.