MCP Server

curl https://mcp.roe-ai.com/.well-known/oauth-protected-resource
curl https://app.roe-ai.com/.well-known/oauth-authorization-server

KEY="your-org-api-key"
ORG_ID="your-org-uuid"
URL="https://mcp.roe-ai.com/mcp"
HDRS=(-H "Authorization: Bearer $KEY"
      -H "X-Roe-Organization-Id: $ORG_ID"
      -H 'Content-Type: application/json'
      -H 'Accept: application/json, text/event-stream')

# 1. Initialize and capture the session id from the response header.
SID=$(curl -sS -D - -o /dev/null "${HDRS[@]}" -X POST "$URL" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"smoke","version":"0"}}}' \
  | awk 'tolower($1)=="mcp-session-id:"{print $2}' | tr -d '\r')

# 2. Acknowledge initialization (no response body expected).
curl -sS "${HDRS[@]}" -H "Mcp-Session-Id: $SID" -X POST "$URL" \
  -d '{"jsonrpc":"2.0","method":"notifications/initialized"}'

# 3. List tools.
curl -sS "${HDRS[@]}" -H "Mcp-Session-Id: $SID" -X POST "$URL" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

Use Roe whoami to confirm the connection.
List my Roe agents and show the first 10 with their ids.
Run the merchant-risk agent asynchronously and poll until it finishes.
List my Roe policies and show the current version for each.
Upload this CSV to Roe tables, then create a run input that references it.

---
name: roe-mcp
description: Call Roe agents, policies, and jobs via the hosted Roe MCP server. TRIGGER when the user wants to "run a roe agent", "list my roe agents", interact with Roe policies, or any roe.ai task that maps to the Roe public API. SKIP for non-Roe MCP servers.
---

# Roe MCP skill

The Roe MCP server is registered as `roe` in Claude Code's MCP config.
Preferred auth is OAuth through `/mcp`; do not ask the user for a Roe API key
unless the deployment uses API-key mode.

Hosted Roe uses `https://mcp.roe-ai.com/mcp`. Single-tenant Roe uses
`https://mcp.<tenant>.roe-ai.com/mcp`; the matching API backend is selected by
the MCP deployment. Never invent an organization id or tenant slug — ask the
user if it isn't already in context.

## Tool surface

- **Identity:** `whoami` — connection check; returns `{user_id, org_id, email, source}`.
- **Agents (CRUD):** `list_agents`, `get_agent`, `create_agent`, `update_agent`, `delete_agent`, `duplicate_agent`.
- **Agent versions:** `list_agent_versions`, `get_agent_version`, `get_current_agent_version`, `create_agent_version`, `update_agent_version`, `delete_agent_version`.
- **Runs:** `run_agent` (synchronous, ≤25s wall clock) or `trigger_agent_run` (returns `job_id`) + `get_agent_job_status` + `get_agent_job_result`.
- **Jobs:** `get_agent_job_status`, `get_agent_job_result`, `cancel_agent_job`, `download_job_reference`.
- **Policies:** `list_policies`, `get_policy`, `create_policy`, `update_policy`, `delete_policy`, `list_policy_versions`, `get_policy_version`, `create_policy_version`.
- **Batch (use when N ≥ 3):** `run_agents_batch`, `get_agent_jobs_status_batch`, `get_agent_jobs_result_batch`, `cancel_all_agent_jobs`.

## Run-mode decision tree

1. One run, expected under 25s → `run_agent`.
2. One run, longer than 25s or you want a job id → `trigger_agent_run`, poll `get_agent_job_status` until terminal, then `get_agent_job_result`.
3. Three or more runs of the same agent → `run_agents_batch`, then batch status/result tools.

## Job status

`get_agent_job_status` returns a raw integer from `roe.models.job.JobStatus`:

| Code | Name | Terminal? |
| --- | --- | --- |
| 0 | PENDING | no |
| 1 | STARTED | no |
| 2 | RETRY | no |
| 3 | SUCCESS | yes |
| 4 | FAILURE | yes |
| 5 | CANCELLED | yes |
| 6 | CACHED | yes |

Stop polling on `{3, 4, 5, 6}`. Anything else means keep polling.

## Error semantics

- `401 X-Roe-Organization-Id header required.` → an API-key config is missing the org-id header; fix the MCP client config, not the prompt.
- `401` with `resource_metadata` in `WWW-Authenticate` → OAuth is required or the OAuth token is invalid; ask the user to reconnect the Roe MCP server through the client's auth UI.
- `401` with any other body in API-key mode → bearer is wrong or revoked. Ask the user to mint a fresh key in Roe settings.
- `503` with `Retry-After` → upstream Roe is throttling. Back off for the advertised duration, then retry; do not treat as auth failure.
- Token-bucket rate limits are per user/org/tool for OAuth and per bearer/tool for API-key mode. When one bucket drains, the same user can still call other tools.

## Don'ts

- Don't paste OAuth tokens or API keys into the chat transcript; reference them as placeholders in config snippets.
- Don't call `delete_agent`, `delete_agent_version`, `delete_policy`, or `cancel_all_agent_jobs` without explicit user confirmation — they're destructive.
- Don't add `X-Roe-API-Base-URL` for normal OAuth connections. Use the correct MCP host instead: `mcp.roe-ai.com` or `mcp.<tenant>.roe-ai.com`.