MCP server

Use the RawTree MCP server to give AI agents direct access to a RawTree project. Agents can query data, insert events, inspect tables, read RawTree logs, and manage project API keys through a standard MCP client.

What is an MCP server?

MCP is an open protocol for connecting AI applications to external tools and context. A RawTree MCP server exposes RawTree operations as tools that an agent can call from clients such as Claude Code, Codex, Cursor, Claude Desktop, or any MCP-compatible runtime.

What can RawTree's MCP server do?

The RawTree MCP server provides tools for common project workflows:

• Query — run read-only SQL and return rows, column metadata, query statistics, and hints.
• Ingest — insert JSON objects, arrays of JSON objects, or public URL data.
• Transforms — apply RawTree built-in transforms for OTLP traces, OTLP logs, OTLP metrics, CloudWatch Logs, CloudTrail, and Firehose JSON body inserts.
• Tables — list tables, describe columns and storage metadata, and delete tables when using an admin key.
• Logs — inspect RawTree query and insert logs with filters for time range, type, status, origin, table, and hints.
• API keys — list, create, and revoke project API keys when using an admin key.
• Project identity — return the current project and organization for the configured API key.

Prerequisites

Create a RawTree API key from the dashboard or CLI:

rtree key create --name mcp --permission read_write

Use the least permission that can complete the workflow:

How to use the MCP server

The server supports two transport modes: stdio for local MCP clients and HTTP for remote or web-based integrations.

Replace rt_xxxxxxxxx with your RawTree API key.

Stdio transport

Use stdio when your MCP client launches the server as a local process.

Quick setup

npx add-mcp @rawtree/mcp --name rawtree --env "RAWTREE_API_KEY=rt_xxxxxxxxx"

Claude Code

claude mcp add rawtree \
  -e RAWTREE_API_KEY=rt_xxxxxxxxx \
  -- npx -y @rawtree/mcp

Codex

codex mcp add rawtree \
  --env RAWTREE_API_KEY=rt_xxxxxxxxx \
  -- npx -y @rawtree/mcp

Cursor

Open the command palette and choose "Cursor Settings" > "MCP" > "Add new global MCP server".

{
  "mcpServers": {
    "rawtree": {
      "command": "npx",
      "args": ["-y", "@rawtree/mcp"],
      "env": {
        "RAWTREE_API_KEY": "rt_xxxxxxxxx"
      }
    }
  }
}

Claude Desktop

Open Claude Desktop settings > "Developer" tab > "Edit Config".

{
  "mcpServers": {
    "rawtree": {
      "command": "npx",
      "args": ["-y", "@rawtree/mcp"],
      "env": {
        "RAWTREE_API_KEY": "rt_xxxxxxxxx"
      }
    }
  }
}

HTTP transport

Use HTTP when you want a long-running MCP endpoint. Each client authenticates by sending its RawTree API key in the Authorization header.

Start the server:

npx -y @rawtree/mcp --http --port 3000

The server listens on http://127.0.0.1:3000 and exposes the MCP endpoint at /mcp using Streamable HTTP.

Claude Code

claude mcp add rawtree \
  --transport http http://127.0.0.1:3000/mcp \
  --header "Authorization: Bearer rt_xxxxxxxxx"

Cursor

{
  "mcpServers": {
    "rawtree": {
      "url": "http://127.0.0.1:3000/mcp",
      "headers": {
        "Authorization": "Bearer rt_xxxxxxxxx"
      }
    }
  }
}

You can also set the HTTP port with MCP_PORT:

MCP_PORT=3000 npx -y @rawtree/mcp --http

Options

Environment variables:

Public configuration is limited to RawTree API keys and the MCP HTTP port.

Tools

Data

• check-health — Check that the RawTree API endpoint is reachable.
• run-query — Run read-only SQL and return RawTree's JSON query response.
• insert-json — Insert one JSON object or an array of JSON objects into a table.
• insert-from-url — Ingest data from a public URL and return RawTree's NDJSON progress stream.

Tables

• list-tables — List tables in the configured project.
• describe-table — Inspect table columns, row count, byte count, project, and organization.
• delete-table — Delete a table after explicit confirmation. Requires admin permission.

Logs

• list-logs — Read RawTree insert and query logs. Defaults to the last hour when no time window is provided.

Example log filter:

{
  "statuses": ["error"],
  "types": ["insert"],
  "tables": ["events"],
  "origins": ["api"],
  "hints": "any",
  "limit": 50
}

API keys

• list-api-keys — List API keys for the configured project. Requires admin permission.
• create-api-key — Create a key with admin, read_write, write_only, or read_only permission.
• delete-api-key — Revoke a key after explicit confirmation.

Project

• get_project — Return the current project as { "name": "...", "organization": { "name": "..." } }.

Local development

Clone the server and build it:

git clone https://github.com/rawtreedb/rawtree-mcp.git
cd rawtree-mcp
pnpm install
pnpm build

Use the local build from an MCP client:

claude mcp add rawtree \
  -e RAWTREE_API_KEY=rt_xxxxxxxxx \
  -- node /absolute/path/to/rawtree-mcp/dist/index.js

For HTTP mode:

node /absolute/path/to/rawtree-mcp/dist/index.js --http --port 3000

Then configure your client with http://127.0.0.1:3000/mcp and an Authorization: Bearer rt_xxxxxxxxx header.

Testing with MCP Inspector

Build the project first:

pnpm build

Stdio

Set your API key:

export RAWTREE_API_KEY=rt_xxxxxxxxx

Start the inspector:

pnpm inspector

In the Inspector UI:

• Choose stdio.
• Command: node.
• Args: dist/index.js.
• Env: RAWTREE_API_KEY=rt_xxxxxxxxx.
• Connect, then use "List tools" to verify the server.

HTTP

Start the HTTP server:

node dist/index.js --http --port 3000

Start the inspector in another terminal:

pnpm inspector

In the Inspector UI:

• Choose Streamable HTTP.
• URL: http://127.0.0.1:3000/mcp.
• Add Authorization: Bearer rt_xxxxxxxxx as a custom header.
• Connect, then use "List tools" to verify the server.

Next steps

• Agents quickstart
• Ingest data
• Query data
• Debug with logs
• API reference