> ## Documentation Index
> Fetch the complete documentation index at: https://docs.roe-ai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Roe MCP Basics

> Teach your assistant the Roe MCP fundamentals — run-mode selection, job polling, table queries, auth and error handling — with one installable skill

The Roe MCP tools are self-describing, but the judgment calls between them —
sync vs async runs, when to batch, how to poll jobs and table queries, what a
`503` means versus a `401` — live across many tool descriptions. This skill
puts all of it in your assistant's context up front, so it picks the right
tool the first time.

Install it alongside the [Workflow Builder skill](/mcp/skills/workflow-builder),
which covers authoring multi-step workflows; this one covers everything else.

## Install the skill

<Tabs>
  <Tab title="Claude Code">
    Save the block to `~/.claude/skills/roe-mcp-basics/SKILL.md` (or
    `.claude/skills/roe-mcp-basics/SKILL.md` inside a project) and restart Claude
    Code.
  </Tab>

  <Tab title="Cursor">
    Save the block to `.cursor/rules/roe-mcp-basics.mdc`, replacing the
    `name:`/`description:` frontmatter with Cursor's
    [rule frontmatter](https://docs.cursor.com/context/rules):

    ```markdown theme={null}
    ---
    description: Call Roe agents, tables, jobs, policies, and connections via the Roe MCP server — run-mode selection, job polling, table queries, auth and error handling.
    alwaysApply: false
    ---
    ```
  </Tab>

  <Tab title="Codex">
    Append the block's body (everything from `# Roe MCP basics` down) to your
    project's `AGENTS.md`, or to `~/.codex/AGENTS.md` to apply it globally.
  </Tab>

  <Tab title="Any other client">
    This page is served as plain Markdown at
    [docs.roe-ai.com/mcp/skills/roe-mcp-basics.md](https://docs.roe-ai.com/mcp/skills/roe-mcp-basics.md)
    (and listed in [docs.roe-ai.com/llms.txt](https://docs.roe-ai.com/llms.txt)).
    Paste it into a system prompt or project instructions.
  </Tab>
</Tabs>

## The skill

```markdown theme={null}
---
name: roe-mcp-basics
description: Call Roe agents, tables, jobs, policies, and connections via the hosted Roe MCP server. TRIGGER when the user wants to run/list/manage Roe agents, query or upload Roe tables, check Roe jobs, or work with Roe policies/connections. SKIP for authoring multi-step Roe workflows (use the roe-workflow-authoring skill) and for non-Roe MCP servers.
---

# Roe MCP basics

Start with `whoami` to confirm the connection — it returns
`{user_id, org_id, email, source}` (`source` is `mcp-oauth` for OAuth,
`mcp-bearer` for API-key auth). Every call is scoped to that org; you cannot
act outside it. Never invent ids or names — discover them with the `list_*`
tools first. List tools paginate: stop when `len(results) < page_size`.

## Running agents — decision tree

1. One run, expected under ~25 seconds → `run_agent` (synchronous, returns
   the result directly).
2. One run, longer than ~25 seconds or you want a job id → `trigger_agent_run`
   → poll `get_agent_job_status` until terminal → `get_agent_job_result`.
3. Three or more input sets for the SAME agent → `run_agents_batch` → poll
   `get_agent_jobs_status_batch` → `get_agent_jobs_result_batch`. Batch runs
   the agent's CURRENT version only (no `version_id`), and `metadata` is
   batch-level, not per input.

Inputs must match the keys in `get_current_agent_version.input_definitions`
(or `get_agent_version.input_definitions` when passing `version_id`).
Reserved input keys: `metadata` on `run_agent`; `idempotency_key`,
`metadata`, `timeout_seconds` on `trigger_agent_run`.

## Job status codes

`get_agent_job_status` returns an integer: 0 PENDING, 1 STARTED, 2 RETRY,
3 SUCCESS, 4 FAILURE, 5 CANCELLED, 6 CACHED. Terminal set is {3, 4, 5, 6} —
stop polling there; anything else means keep polling.
`list_agent_jobs` filters an agent's job history by status, metadata, search,
and date range.

## Tables

Flow: `list_tables` → `describe_table` → usually `preview_table` →
`query_tables` → poll `get_table_query_result`.

- `query_tables` accepts exactly ONE read-only ClickHouse statement
  (`SELECT` or `WITH ... SELECT`). Mutating SQL, multiple statements,
  database-qualified names, system tables, and Roe SQL functions like
  `run_agent` are rejected. `limit` defaults to and maxes at 1000.
- It returns `{table_query_id, status, created_at}` — the rows come from
  `get_table_query_result`, polled until terminal. Completed results carry
  `{columns, rows, row_count, truncated, execution_time_ms}`; `truncated:
  true` means a row cap, byte cap, or a shortened oversized cell.
- `upload_table` creates a table from an inline CSV body (small payloads
  only). The `upload_chatgpt_*` tools exist for ChatGPT-host file references.

## Auth & errors

- OAuth or API key. API-key mode requires BOTH headers:
  `Authorization: Bearer <key>` and `X-Roe-Organization-Id: <org-uuid>` — a
  `401` reading "X-Roe-Organization-Id header required" means the client
  config is missing the second header; fix the config, not the prompt.
- `401` with `resource_metadata` in `WWW-Authenticate` → OAuth token invalid
  or expired; reconnect through the client's connector/auth UI.
- `503` with `Retry-After` → upstream Roe backpressure (its 429 surfaces as
  MCP 503). Back off for the advertised duration and retry — this is NOT an
  auth failure.
- Rate limits are token buckets per tool: keyed by user+org for OAuth, by
  bearer key for API-key mode. One drained bucket doesn't block other tools.
- Tool errors arrive as a JSON envelope `{code, message, hint, details}` —
  parse it; `details` carries the backend's response body.

## Destructive tools — confirm with the user first

`delete_agent`, `delete_agent_version`, `delete_table`, `delete_policy`,
`delete_connection`, `cancel_agent_job`, `cancel_all_agent_jobs`, and
`agents_jobs_delete_data_create` (irreversibly purges job data). Never call
these without explicit confirmation.

## Don'ts

- Don't paste API keys or OAuth tokens into the chat; use placeholders in
  config snippets.
- Don't add an `X-Roe-API-Base-URL` header — the MCP host already selects
  the right backend (`mcp.roe-ai.com` or `mcp.<tenant>.roe-ai.com`).
- Don't author WorkflowOrchestrator configs from this skill — call
  `get_help` with topic `workflows` (older servers fall back to the general
  guide) or use the roe-workflow-authoring skill.

When unsure which tool fits, call `get_help(topic=...)`: topics include
overview, getting-started, auth, tools, and troubleshooting.
```