Give an AI agent the fastest safe path to ingest, query, and debug RawTree data.

Quickstart for agents

Use this page when a coding agent, terminal agent, or CI worker needs to operate RawTree without extra context.

Fastest path: hosted MCP

For an interactive agent, connect RawTree's hosted MCP server and sign in with OAuth. No API key or local process is required.

codex mcp add rawtree --url https://mcp.rawtree.com/mcp

Use https://mcp.rawtree.com/mcp as a remote or Streamable HTTP server in other MCP clients. See the MCP server reference for Claude Code, Claude, Cursor, headless clients, and local-server setup.

CLI and unattended agents

Use the CLI path when OAuth browser login is unavailable or the agent needs to run without interaction.

1) Install the RawTree skill

Install the RawTree skill so your agent has the CLI, API, SQL, logs, and error-handling patterns available in its working context.

npx skills add rawtreedb/agent-skills

Use a cluster-wide API key when OAuth browser login is unavailable, such as in CI or another unattended environment. You can create one in the RawTree dashboard from cluster settings, or from the CLI:

rtree key create --name my-agent --permission read_write

See CLI reference / API keys for the full key commands.

Prefer the least permission that can complete the job.

export RAWTREE_API_KEY=rt_...
export RAWTREE_DATABASE=analytics
export RAWTREE_ORG=team_alpha

Recommended permissions:

Task	Permission
Insert and query data	`read_write`
Insert only	`write_only`
Query and inspect logs	`read_only`
Manage databases or API keys, or delete tables	`admin`

3) Verify context

rtree status --json

The response includes the resolved database, organization, authentication state, and dashboard URL.

4) Ingest data

rtree insert --table events \
  --data '[{"action":"click","user":"alice"},{"action":"view","user":"bob"}]' \
  --json

Tables are created automatically when data is inserted for the first time.

5) Query with SQL

rtree query --json \
  "SELECT action, count() AS total FROM events GROUP BY action ORDER BY total DESC LIMIT 10"

Only read-only SQL is accepted through the query API. Use LIMIT while iterating.

6) Check API request logs

Use GET /v1/logs or the platform Logs screen to inspect request paths, HTTP statuses, timing, client source, and structured errors. Use the Queries screen for SQL execution history.

Starter prompt

You are operating a RawTree database.

Use the configured RawTree MCP tools. If MCP is unavailable, use
RAWTREE_API_KEY, RAWTREE_DATABASE, and RAWTREE_ORG from the environment.

Goals:
1. Ingest the provided data into table "events".
2. Query the table with read-only SQL.
3. Use LIMIT while exploring data.
4. Check RawTree logs from the last hour if insert or query fails.
5. Return the commands you ran and the final result.

Agents