Agents
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 the RawTree Cloud 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/mcpUse https://mcp.rawtree.com/mcp as a remote or Streamable HTTP server in other MCP clients.
See the MCP server reference for setup instructions for Claude Code, Claude, Cursor, headless clients, and local servers.
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 to give your agent CLI, API, SQL, logs, and error-handling patterns.
npx skills add rawtreedb/agent-skills2) Provide credentials
Use a cluster-wide API key when OAuth browser login is unavailable, such as in CI or another unattended environment. Create the key in cluster settings in the RawTree Cloud dashboard or with the CLI:
rtree key create --name my-agent --permission read_writeSee 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_alphaRecommended 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 --jsonThe 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"}]' \
--jsonTables 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"Start with read queries and use LIMIT while iterating. The Query API also
accepts selected write and management statements with the required permissions.
See SQL statements.
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 service request logs from the last hour if insert or query fails.
5. Return the commands you ran and the final result.