---
title: "Agent setup: connect roasOS MCP"
description: "Steps that an AI agent can read and do to connect the roasOS MCP server."
url: https://docs.roasos.com/mcp-setup
---

# 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](/mcp) for the full reference.

## 1. Find the client

Identify the client that runs you.

| Client                                               | Go to  |
| ---------------------------------------------------- | ------ |
| Claude Code                                          | Step 2 |
| A client that reads a JSON file (for example Cursor) | Step 3 |
| claude.ai or another web client                      | Step 4 |

## 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:

```bash
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:

```bash
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.

```json
{
  "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.

| Result                 | Do this                                                          |
| ---------------------- | ---------------------------------------------------------------- |
| The account comes back | Go to step 6.                                                    |
| `401`                  | The key or the sign-in is not valid. Ask the person to check it. |
| The tool is not there  | The client did not load the server. Restart it.                  |

## 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.