RawTree MCP Server
OfficialThe RawTree MCP Server connects MCP clients (like Claude Code, Cursor, and Claude Desktop) to RawTree, an analytics database for unstructured data, enabling SQL querying, JSON ingestion, table management, log inspection, and API key administration.
Querying
Run read-only SQL queries against a RawTree project and receive JSON rows, column metadata, statistics, and hints.
Data Ingestion
Insert single JSON objects or arrays of JSON objects into tables (auto-creates table on first insert).
Ingest JSON/JSONL data directly from a public URL.
Supports built-in transforms for OTLP traces/logs/metrics, CloudWatch Logs, CloudTrail, and Firehose.
Table Management
List all tables with row and byte counts.
Describe a table's columns, row count, size, project, and organization.
Permanently delete a table and its data (requires explicit user confirmation).
Log Inspection
Browse query and insert history with filters for type, status, origin, table name, hints, time window, and pagination.
API Key Management
List, create (with one-time token display), and revoke API keys for the configured project.
Project Identity
Retrieve the current project name and organization associated with the active API key.
Health Check
Verify that the configured RawTree API endpoint is reachable.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@RawTree MCP Servershow me the tables in my project"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
RawTree MCP Server
An MCP server for RawTree, an analytics database for unstructured data. Query data with SQL, insert JSON, inspect table schemas, review RawTree logs, and manage database credentials from MCP clients like Claude Code, Cursor, and Claude Desktop.
Features
Queries — Run read-only SQL against a RawTree database and receive JSON rows, metadata, statistics, and hints.
Ingest — Insert a single JSON object, arrays of JSON objects, or public URL data.
Tables — List tables, describe table columns and sizes, and delete tables after explicit confirmation.
Logs — Inspect RawTree query and insert history with structured filters for type, status, origin, table, hints, time window, and pagination.
API Keys — List, create, and revoke RawTree API keys for a database. Creation responses include the one-time API key value.
Organizations — List organizations and manage their members and roles with an OAuth-authenticated user.
Databases — List databases in a cluster and delete a named database.
Clusters — List, inspect, pause, resume, discover current creation options, verify optional customer-owned S3 access, and provision vertically autoscaling dedicated clusters after explicit confirmation where required. RawTree enforces user and organization-admin authorization.
Apps — List the app catalog for a cluster, inspect installation state, and install or uninstall apps after explicit confirmation.
Transports — Supports stdio for local MCP clients and dual-era Streamable HTTP for remote or multi-client deployments, including stateless MCP 2026-07-28 requests and legacy initialize-handshake clients.
Related MCP server: Azure SQL MCP Server
Setup
Create a RawTree API key from the RawTree CLI, dashboard, or API. A database API key starts with rt_ and is enough for data tools such as run-query, insert-json, list-tables, and list-logs.
Usage
The server supports two transport modes: stdio (default) and HTTP.
Stdio Transport
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/mcpCursor
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
Run the server over HTTP for remote or web-based integrations. In HTTP mode, each MCP client authenticates by passing its RawTree API key in the Authorization header.
Start the server:
npx -y @rawtree/mcp --http --port 3000The 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 port via the MCP_PORT environment variable:
MCP_PORT=3000 npx -y @rawtree/mcp --httpOptions
--api-key: RawTree database API key for stdio mode--api-url: RawTree API base URL, defaulthttps://api.rawtree.com--database: Database name for scoped routes--org: Organization name for scoped routes--http: Use HTTP transport instead of stdio--port: HTTP port when using--http, default3000orMCP_PORT
Environment variables:
RAWTREE_API_KEY: RawTree database API keyRAWTREE_API_URL: RawTree API base URL, defaulthttps://api.rawtree.comRAWTREE_DATABASE: Database name for scoped routesRAWTREE_ORG: Organization name for scoped routesMCP_PORT: HTTP port when using--http
Tools
Data
run-query— Run read-only SQL and return RawTree's JSON query response. Accepts organization, cluster, and database overrides.insert-json— Insert JSON object(s) 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 database.create-table— Create an empty table with cluster-default storage or an optional per-table customer-owned S3 bucket.describe-table— Inspect columns, row count, byte count, database, and organization.delete-table— Delete a table after explicit confirmation. Requires admin permission.
create-table.storage is optional. Omit it to use the cluster's default storage. For a cluster whose get-cluster response includes table_bucket_prefix, use { "type": "s3", "bucketSuffix": "events" } to create a table in the existing bucket formed by that server-owned prefix plus events. path is optional and defaults to rawtree/{database}/{table}. The AWS region, IAM role ARN, external ID, and bucket prefix come from the cluster configuration and are not create-table inputs.
Logs
list-logs— Read RawTree query and insert logs. Defaults to the last hour when no time window is provided.
Structured log filters include:
{
"statuses": ["error"],
"types": ["insert"],
"tables": ["events"],
"origins": ["api"],
"hints": "any",
"limit": 50
}API Keys
list-api-keys— List API keys for the configured database.create-api-key— Create a key withadmin,read_write,write_only, orread_onlypermission.delete-api-key— Revoke a key after explicit confirmation.
Databases
list-databases— List databases in an organization and cluster.delete-database— Delete a database and all its data after explicit confirmation.
Organizations
list-organizations— List organizations available to the authenticated user. Requires a user credential such as OAuth.list-organization-members— List accepted members of an organization with their user IDs and roles.add-organization-member— Send an organization member invitation after confirming the organization and email address. Membership starts after acceptance.update-organization-member— Change an accepted member's role toadminormemberafter explicit confirmation.remove-organization-member— Remove an accepted member and revoke organization access after explicit confirmation.
Clusters
list-clusters— List dedicated clusters accessible in an organization.list-cluster-sizes— List current replica limits, supported per-replica sizes, and default vertical autoscaling bounds.verify-cluster-s3-access— Verify an optional customer-owned S3 configuration before cluster creation. The check temporarily writes, reads, and removes a probe object in both configured destinations.create-cluster— Provision a dedicated cluster after confirming its organization, replica count, minimum size, maximum size, autoscaling behavior, optional idle timeout, and optional customer-owned S3 configuration.get-cluster— Get one dedicated cluster and its current lifecycle status by ID.update-cluster— Change a dedicated cluster's idle timeout after confirming the organization, cluster ID, and new value. Use0to disable idling.pause-cluster— Pause a dedicated cluster after explicit confirmation. Its databases become unavailable until the cluster is resumed.resume-cluster— Resume a paused dedicated cluster after explicit confirmation.
Cluster tools are advertised to every MCP client. Call list-cluster-sizes before create-cluster; creation starts at the selected minimum per-replica size and can vertically autoscale to the selected maximum. idleTimeoutMinutes accepts 0 to disable idling or a value from 15 through 43200; omit it during creation to use the server default.
create-cluster.byoS3 is optional. Omit it to use RawTree-managed storage. When provided, data and backups each require a bucket and accept an optional object-key path; roleArn identifies the customer IAM role RawTree may assume, and externalId must exactly match the role trust policy. tableBucketPrefix is optional and enables customer-owned buckets for individual tables; the same IAM role must allow buckets matching that prefix. Call verify-cluster-s3-access with the identical configuration before creation. Verification checks only the configured data and backup destinations, not future per-table buckets, and should be repeated after changing any byoS3 field.
The RawTree API remains the authorization boundary: cluster access requires a user access token, and cluster creation, S3 verification, updates, pausing, and resuming additionally require organization-admin access.
Apps
list-apps— List the available apps and installation state for one cluster.install-app— Install an app on a cluster after confirming the organization, cluster name, and app ID.uninstall-app— Uninstall an app and disable its native endpoints after confirming the organization, cluster name, and app ID. Existing cluster data is not deleted.
App tools require a user credential. Organization members can list apps; installing and uninstalling require organization-admin access. Use the app IDs returned by list-apps.
Connectors
list-connectors— List the managed connectors and destinations in a cluster.get-connector— Get one connector's status and sanitized configuration.create-connector— Create an active Kafka connector with one or more destinations.get-connector-metrics— Read connector and per-destination health, lag, buffers, delivery counters, errors, source lag, and HTTP latency counters.add-connector-destination— Preserve the existing routes and add another topic-to-table destination.set-connector-status— Pause or resume all destinations in a connector.
Connector tools use the same nested field names as the RawTree API. A minimal Kafka connector request looks like:
{
"organization": "acme",
"cluster": "production",
"name": "orders",
"type": "kafka",
"destinations": [
{
"topics": ["orders"],
"database": "default",
"table": "orders"
}
],
"settings": {
"bootstrap_servers": "kafka.example.com:9092",
"auto_offset_reset": "largest",
"tls": { "enabled": true },
"sasl": {
"enabled": true,
"mechanism": "PLAIN",
"username": "connector-user",
"password": "secret"
},
"batch": { "max_events": 1000, "timeout_secs": 1 }
}
}Creating connectors, adding destinations, and changing status require
organization-admin access. Credentials are encrypted by RawTree and omitted
from connector responses. get-connector-metrics returns cumulative counters;
take two samples and divide counter differences by elapsed time to calculate
event rates.
Programmatic hosted deployments can require explicit resource selection on
every applicable tool. Organization and cluster identify the resource boundary;
database remains an optional override and defaults to default when omitted.
This lets one OAuth-backed MCP connection switch between organizations,
clusters, and databases without encoding context in the MCP URL:
const server = createMcpServer(client, { requireExplicitScope: true });Examples
Query
{
"organization": "acme",
"cluster": "production",
"database": "analytics",
"sql": "SELECT count() AS rows FROM events"
}Insert JSON
{
"table": "events",
"data": [
{
"event": "signup",
"user_id": "user_123",
"source": "mcp"
}
]
}Debug Failed Inserts
{
"statuses": ["error"],
"types": ["insert"],
"startTime": "2026-05-28T09:00:00.000Z",
"endTime": "2026-05-28T10:00:00.000Z",
"limit": 25
}Local Development
Install and build:
pnpm install
pnpm buildUse 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.jsLive Testing with an MCP Client
Run TypeScript in watch mode, then point a separate MCP client at the built server:
pnpm tsc --watch{
"mcpServers": {
"rawtree-dev": {
"command": "node",
"args": ["/absolute/path/to/rawtree-mcp/dist/index.js"],
"env": {
"RAWTREE_API_KEY": "rt_xxxxxxxxx"
}
}
}
}Restart the MCP client session after each rebuild.
Programmatic usage
The package root exposes the reusable MCP server layer. The Node HTTP transport
is available separately from @rawtree/mcp/http, so hosted adapters can use
the server factory without importing the local process entrypoint.
import { createMcpServer, RawTreeClient } from '@rawtree/mcp';
const client = new RawTreeClient({ apiKey: process.env.RAWTREE_API_KEY! });
const server = createMcpServer(client);Publishing
Publishing is handled by the GitHub Actions Publish workflow.
Required repository secret:
NPM_TOKEN: npm automation token with permission to publish@rawtree/mcp.
Release flow:
Update
package.jsonto the new version.Push the change to
main.Create and publish a GitHub release with a tag that matches the package version, such as
v0.2.0.
The workflow verifies that the release tag matches package.json, runs lint, tests, and build, then publishes with npm provenance:
npm publish --provenance --access publicTesting with MCP Inspector
Build first:
pnpm buildStart the inspector:
RAWTREE_API_KEY=rt_xxxxxxxxx pnpm inspectorIn the Inspector UI, choose stdio:
Command:
nodeArgs:
dist/index.jsEnvironment:
RAWTREE_API_KEY=rt_xxxxxxxxx
RawTree References
Available Tools
12 toolscheck-healthCheck RawTree HealthA
Purpose: Check that the RawTree API endpoint is reachable.
NOT for: Validating project permissions or checking whether a specific table exists. Use list-tables or run-query for authenticated checks.
Returns: The RawTree health response.
When to use:
User asks whether RawTree is up
You are debugging MCP configuration before using authenticated tools
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but description states the tool returns the RawTree health response and that it is for reachability checks, not authenticated operations. Lacks detail on response format, but sufficient for a simple health check.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise, front-loaded with purpose, uses bullet points for clarity, no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and no output schema, the description fully covers purpose, usage, and exclusions. Complete for this simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters in schema; rule gives baseline 4. Description need not add parameter detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the verb and resource ('Check that the RawTree API endpoint is reachable'). It distinguishes from siblings by explicitly excluding validation of permissions or table existence, and recommends list-tables or run-query instead.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Includes explicit 'NOT for' section and 'When to use' scenarios, providing clear guidance on appropriate use cases and alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
create-api-keyCreate API KeyA
Purpose: Create a new RawTree API key for the configured project.
NOT for: User login or creating projects. Use RawTree auth/CLI or the dashboard for those workflows.
Returns: The new API key value. The API key is only shown once, so you MUST display it to the user.
Auth: Uses POST /v1/keys and requires admin permission for project API key auth.
When to use:
User needs a key for CI, an agent, a connector, or a script
User wants a read-only, write-only, read-write, or admin credential
User asks to rotate credentials by creating a replacement before revoking the old key
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Human-readable API key name. | |
| permission | No | Permission level. Prefer read_only for query-only agents and write_only for ingest-only connectors. | read_write |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries the full burden. It discloses that the returned key is only shown once (must display to user), requires admin permission, and uses POST /v1/keys. This is strong coverage, though could mention whether the key is immediately active or any side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with markdown headings and bullet points, front-loading the purpose and exclusions. Every sentence serves a distinct purpose, with no unnecessary words, making it efficient and clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has only 2 parameters, no output schema, and no annotations, the description covers all essential aspects: purpose, when to use/not use, return value behavior, authentication requirements, and parameter guidance. It is complete for an agent to correctly invoke this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by explaining how to choose permission levels (prefer read_only for query-only, write_only for ingest-only) and that name is human-readable, going beyond the schema's minimal descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the tool creates a RawTree API key for the configured project, distinguishing it from sibling tools like delete-api-key and list-api-keys. The verb 'create' and resource 'API key' are precise and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states what the tool is NOT for (user login, creating projects) and provides alternative workflows. Lists concrete use cases (CI, agents, connectors, scripts, credential rotation) and gives permission-level recommendations, making it clear when to choose this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
delete-api-keyDelete API KeyA
Purpose: Permanently revoke and delete a RawTree API key by UUID or full API key value.
NOT for: Deleting a table, project, or user session.
Returns: Deletion confirmation.
Safety: You MUST list or identify the key first, ask the user to confirm the exact key name or ID, and warn that services using it will lose access. This action cannot be undone.
| Name | Required | Description | Default |
|---|---|---|---|
| idOrApiKey | Yes | API key UUID or full rt_ API key value to delete. | |
| confirm | Yes | Set to true only after the user explicitly confirms revocation of this exact API key. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses irreversibility ('This action cannot be undone'), return type ('Deletion confirmation'), and impact ('services using it will lose access'). No annotations provided, so description fully handles transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-organized with bold section headers. Each sentence serves a clear purpose: purpose, exclusion, return, safety. No redundant or vague language.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive action with 2 required params and no output schema, the description covers purpose, usage, safety, and return value completely. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema already documents both parameters (idOrApiKey and confirm) with 100% coverage. Description adds value by explaining confirm as a safety mechanism requiring explicit user confirmation after identification.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Explicitly states 'permanently revoke and delete a RawTree API key by UUID or full API key value'. Distinguishes from sibling tools like list-api-keys and create-api-key by clarifying it is for deletion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit 'NOT for' list (delete table, project, user session) and detailed safety steps: list/identify key first, get user confirmation, warn about service disruption.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
delete-tableDelete TableA
Purpose: Permanently delete a RawTree table and its data.
NOT for: Clearing a query result or undoing a single insert. This deletes the whole table.
Returns: Deletion confirmation.
Safety: You MUST ask the user to confirm the exact table name before calling this tool. This action requires an admin key and cannot be undone.
| Name | Required | Description | Default |
|---|---|---|---|
| table | Yes | Table name to delete. | |
| confirm | Yes | Set to true only after the user explicitly confirms deletion of this exact table. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses permanent deletion, irreversibility, admin key requirement, and confirmation necessity. However, it could mention potential side effects or dependencies, but it covers the key destructive behavior well.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with bold section headers, front-loaded purpose, and no unnecessary words. Every sentence adds value, making it easy to scan quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of output schema, the description adequately explains return type ('Deletion confirmation') and covers all essential aspects: purpose, usage boundaries, safety, and prerequisites. It is complete for a destructive single-purpose tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. Description adds context by reinforcing the safety requirement for the 'confirm' parameter and clarifying the purpose of 'table'. It does not contradict schema and provides helpful real-world usage context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Permanently delete a RawTree table and its data', providing a specific verb and resource. It also distinguishes itself from siblings like 'describe-table' and 'list-tables' by clarifying it's not for clearing query results or undoing single inserts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when not to use ('NOT for: Clearing a query result or undoing a single insert'), and provides required safety steps (ask user to confirm exact table name) and prerequisites (admin key).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
describe-tableDescribe TableA
Purpose: Inspect a RawTree table's columns, row count, byte count, project, and organization.
NOT for: Sampling actual row values. Use run-query for SELECT queries.
Returns: Table metadata and columns.
When to use:
You need to know available fields before writing SQL
A query fails because a column may not exist
You just inserted data and want to inspect the dynamic schema
| Name | Required | Description | Default |
|---|---|---|---|
| table | Yes | Table name to describe. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. It states the tool returns metadata and columns, implying a read-only operation with no side effects. While safe, it could more explicitly confirm non-destructive behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise with clear structure: bold headings, bullet points for when-to-use, and direct language. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no output schema), the description fully covers purpose, usage, and return value. No gaps for an agent to interpret.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single parameter 'table'. The description adds context (e.g., 'table name to describe') but does not significantly extend beyond the schema's own description. Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: inspect a RawTree table's columns, row count, byte count, project, and organization. It distinguishes itself from the sibling tool 'run-query' by explicitly stating it is NOT for sampling row values.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use scenarios (know fields before SQL, debug failing queries, inspect dynamic schema) and when-not-to-use (not for sampling actual row values, use run-query for SELECT). This directly aids in tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_projectGet ProjectA
Purpose: Return the configured RawTree project identity using the current API key.
NOT for: Listing tables inside a project. Use list-tables for project data.
Returns: A compact project shape: { "name": "...", "organization": { "name": "..." } }.
Auth: Uses GET /v1/keys and parses the project and organization from that response. If the current project API key cannot list keys, it falls back to GET /v1/tables, which exposes the same project identity for read-capable keys.
When to use:
You need to know which RawTree project the current API key belongs to
You are setting up an MCP client and want to confirm the active project
You want the organization name without requiring a separate project endpoint
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full behavioral burden. It discloses the HTTP endpoints used (GET /v1/keys, fallback to GET /v1/tables), return shape, and implicit auth dependency. Missing edge cases like error handling, but otherwise thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with headers and bullet points. Front-loaded with purpose and use cases. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters, no output schema, and no annotations, the description is remarkably complete. It covers the API calls, return shape, use cases, and explicit sibling differentiation. Only minor gaps like error codes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist in the input schema (0 params), so baseline is 4. The description adds no parameter info because none needed, but it implicitly explains the auth context ('using the current API key').
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns the RawTree project identity using the current API key, with a specific verb and resource. It explicitly distinguishes itself from list-tables by stating 'NOT for: Listing tables inside a project. Use list-tables for project data.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit 'When to use' bullet points and a clear 'NOT for' section with a named alternative (list-tables). This gives strong guidance on appropriate usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
insert-from-urlInsert From URLA
Purpose: Ask RawTree to ingest JSON/JSONL data from a public URL into a table. RawTree streams progress as NDJSON.
NOT for: Private files on your machine, authenticated URLs, or built-in transforms. Host transformed data first or use insert-json with transform.
Returns: The RawTree NDJSON progress stream as text.
When to use:
User has a public JSON or JSONL file URL
You need RawTree to fetch and ingest the file directly
The data is too large or inconvenient to paste into the MCP call
Workflow: Confirm the URL is public → call insert-from-url → use list-logs and run-query to verify.
Key trigger phrases: "ingest this URL", "load JSONL from", "import from public file"
| Name | Required | Description | Default |
|---|---|---|---|
| table | Yes | Target table name. | |
| url | Yes | Public URL containing data RawTree can fetch. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes streaming NDJSON return, workflow steps, and limitations, but lacks details on error handling or network failure modes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with headings and bullet points, though slightly verbose; each section adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, workflow, return type, and verification steps; missing edge cases like URL format errors or size limits, but adequate for the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers both parameters with descriptions; description adds no extra semantic meaning beyond repeating the schema fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'ingest JSON/JSONL data from a public URL into a table' and distinguishes from siblings like insert-json and transforms.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly notes when to use (public URL, large data) and when not (private files, authenticated URLs), offering alternative insert-json with transform.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
insert-jsonInsert JSONA
Purpose: Insert one JSON object or an array of JSON objects into a RawTree table. RawTree auto-creates the table on first insert.
NOT for: Loading data from a public URL (use insert-from-url). Not for transformed URL ingest; transforms only apply to JSON request bodies.
Returns: Insert confirmation, usually { "inserted": }. Firehose transform returns request metadata.
When to use:
User wants to send events, logs, traces, metrics, or arbitrary records to RawTree
You need to create a table by inserting the first row
You need to validate that RawTree accepts a payload shape
You have OTLP, CloudWatch Logs, CloudTrail, or Firehose JSON that should be flattened by RawTree
Workflow: Choose a table name → send a small representative payload → run describe-table or run-query to verify.
Key trigger phrases: "insert this", "send event", "write to RawTree", "create table with data", "ingest JSON"
| Name | Required | Description | Default |
|---|---|---|---|
| table | Yes | Target table name. RawTree accepts identifiers like events, traces, api_logs. | |
| data | Yes | A JSON object or a non-empty array of JSON objects to insert. | |
| transform | No | Optional RawTree built-in transform for JSON body inserts: otlp-traces, otlp-logs, otlp-metrics, cloudwatch-logs, cloudtrail, or firehose. | |
| columns | No | For transform=firehose only: TSV column names matching each Firehose record line. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations, so description carries full burden. Discloses auto-creation, return format (insert confirmation with row count), and firehose transform metadata. Missing error conditions and idempotency details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Structured with headings, bullet points, and clear sections. Front-loaded purpose and conditions. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers return values, workflow, and trigger phrases given no output schema. Could include more on error states but overall comprehensive for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema already provides full parameter descriptions (100% coverage), so description adds limited semantic value beyond contextual workflow guidance like 'send a small representative payload'. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it inserts JSON objects into RawTree, auto-creates tables, and distinguishes from insert-from-url. Specific verb and resource with clear scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use scenarios (events, logs, traces) and when-not-to-use (public URL). Lists workflow steps and trigger phrases. Lacks exclusion of other sibling tools like run-query.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list-api-keysList API KeysA
Purpose: List API keys for the configured RawTree project.
NOT for: Creating or revoking credentials. Use create-api-key or delete-api-key for those workflows.
Returns: API key names, IDs, API key hints, permissions, project, organization, and creation dates.
Auth: Uses GET /v1/keys and requires an admin project API key.
When to use:
User asks what API keys exist
You need the key ID before revoking a key
You need to audit permissions for a project
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Mentions auth requirement (admin project API key), HTTP method, and return fields. Lacks potential details like rate limits or pagination but sufficient for a simple list tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections (Purpose, NOT for, Returns, Auth, When to use). Every sentence earns its place; front-loaded and concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters and no output schema, the description provides return fields, auth requirements, and usage context. Complete enough for a simple list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters (0 params), baseline 4. Description adds value by listing return fields, which helps the agent understand the output.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'List API keys for the configured RawTree project' using specific verb+resource, and distinguishes from siblings like create-api-key and delete-api-key.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'NOT for: Creating or revoking credentials. Use create-api-key or delete-api-key for those workflows.' Also provides concrete when-to-use scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list-logsList LogsA
Purpose: List recent RawTree insert/query/describe/explain activity for the configured project.
NOT for: Reading application log files from disk or infrastructure logs. This tool reads RawTree's product query and insert logs.
Returns: Log entries with time, type, status, origin, query, exception, rows, duration, bytes, tables, projections, hints, and pagination.
When to use:
An insert or query failed and you need the RawTree exception or hints
You need to verify whether an agent, CLI, API, or UI call reached RawTree
You need recent activity for a table
You want the exact SQL RawTree saw
Workflow: Start with status=error for the last hour. Narrow by table or type if needed. Use next_offset for pagination.
Key trigger phrases: "check RawTree logs", "why did the insert fail", "show query history", "recent errors"
| Name | Required | Description | Default |
|---|---|---|---|
| startTime | No | Inclusive lower bound as an ISO datetime. Defaults to one hour before endTime. | |
| endTime | No | Inclusive upper bound as an ISO datetime. Defaults to now. | |
| limit | No | Number of logs to return. Default: 50. Max: 200. | |
| offset | No | Number of logs to skip for pagination. | |
| search | No | Optional raw RawTree search string, for example "type:insert status:error table:events". Structured filters are appended to it. | |
| types | No | Filter by log type. | |
| statuses | No | Filter by status. | |
| origins | No | Filter by origin. | |
| tables | No | Filter by one or more table names. | |
| hints | No | Filter to logs with any hints or no hints. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries full burden. It describes the data returned, pagination behavior, and scope, but could explicitly declare as read-only. Still, it is highly transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-organized with headers and bullet points, front-loads purpose, and every section adds value; slightly verbose but good structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 10 parameters, no output schema, and no annotations, the description covers return fields, usage patterns, and a workflow. Could mention rate limits, but overall complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear descriptions; the description adds minimal extra meaning beyond the schema, meeting the baseline expectation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists RawTree activity, distinguishes itself from reading other log types, and enumerates specific use cases.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states what the tool is NOT for, provides structured 'When to use' scenarios, a workflow, and key trigger phrases, guiding appropriate selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list-tablesList TablesA
Purpose: List all tables in the configured RawTree project with row and byte counts.
NOT for: Reading table rows. Use run-query for data and describe-table for columns.
Returns: Tables plus project and organization context.
When to use:
User asks what data exists
You need a table name before querying
You want to verify that an insert auto-created a table
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It describes the return content (tables, project, organization context) and implicitly indicates a read operation. However, it does not explicitly state it is non-destructive or safe, but the read-only nature is clear from the purpose.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with headings and bullet points, making it easy to scan. It is concise (approximately 6 sentences) and front-loads the purpose, with every sentence adding value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no parameters, no output schema), the description covers all necessary aspects: purpose, usage guidelines, return content, and exclusions. It is complete and well-suited for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters, and schema description coverage is 100%. The description adds no parameter information because none are needed. With zero parameters, a baseline score of 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists all tables with row and byte counts. It explicitly distinguishes from siblings like 'run-query' and 'describe-table', making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit 'When to use' scenarios (e.g., user asks what data exists, need table name before querying) and a 'NOT for' section with alternatives. This guides the agent on when to select this tool over siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
run-queryRun QueryA
Purpose: Execute a read-only SQL query against the configured RawTree project and return JSON rows, column metadata, statistics, and hints.
NOT for: Inserting, updating, deleting, or mutating data. RawTree validates queries as read-only and rejects unsafe statements.
Returns: RawTree's query response: meta, data, rows, statistics, and optional hints.
When to use:
User asks questions about data already in RawTree
You need to verify an insert
You need a quick aggregate, sample, or schema-oriented SELECT
You need RawTree query hints after an error
Workflow: Start with a bounded SELECT. For exploratory queries, include LIMIT and order by a time column when available.
Key trigger phrases: "query RawTree", "run SQL", "count rows", "show sample rows", "check the data"
| Name | Required | Description | Default |
|---|---|---|---|
| sql | Yes | Read-only SQL to execute. Prefer bounded SELECT queries with LIMIT for exploration. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully discloses behavior: read-only execution, return structure (meta, data, rows, statistics, hints), and validation rejecting unsafe statements. It accurately portrays the tool's side-effect-free nature.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized with clear headings and bullet-like lists. Every sentence adds value—purpose, exclusions, return info, usage scenarios, workflow tips. No wasted text despite moderate length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool with no output schema, the description fully covers purpose, return format, and usage boundaries. It also provides workflow guidance and key trigger phrases, making it self-contained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds guidance on preferred SQL practices (bounded SELECT with LIMIT for exploration), which provides extra semantic value beyond the schema's description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool executes a read-only SQL query against RawTree and explicitly excludes mutation operations like INSERT, UPDATE, DELETE. It differentiates from sibling tools (insert-from-url, delete-table, etc.) and provides verb+resource specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use scenarios (user questions about data, verifying inserts, quick aggregates) and trigger phrases. It also states when not to use (mutation operations) and recommends starting with bounded SELECT queries with LIMIT.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
1 tool update
v0.2.0- Changed
delete-api-key3 fields changed- added
Input schema / properties / idOrApiKeyAdded value: +{ + "description": "API key UUID or full rt_ API key value to delete.", + "minLength": 1, + "type": "string" +} - removed
Input schema / properties / idOrTokenRemoved value: -{ - "description": "API key UUID or full rt_ token to delete.", - "minLength": 1, - "type": "string" -} - changed
Input schema / requiredPrevious value: -[ - "idOrToken", - "confirm" -]New value: +[ + "idOrApiKey", + "confirm" +]
12 tool updates
v0.1.0- First observed
check-health - First observed
create-api-key - First observed
delete-api-key - First observed
delete-table - First observed
describe-table - First observed
get_project - First observed
insert-from-url - First observed
insert-json - First observed
list-api-keys - First observed
list-logs - First observed
list-tables - First observed
run-query
TDQS
Each tool has a clearly distinct purpose. Insert-from-url and insert-json are differentiated by source, and API key management tools are separate. No overlapping functionality that would confuse an agent.
Most tools follow a consistent verb_noun pattern with hyphens (e.g., create-api-key, list-tables), but get_project uses an underscore instead of a hyphen, introducing a minor inconsistency.
With 12 tools, the set is well-scoped for a data server. It covers health check, API key CRUD, table operations, data insertion, querying, and logs without unnecessary bloat or missing essentials.
The tool surface covers core workflows: project info, table schema, data insertion, querying, and log inspection. Missing explicit update/delete data operations may be intentional given RawTree's design, but could be a gap for some use cases.
Maintenance
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Related MCP Connectors
Query your warehouse or a CSV with Claude/ChatGPT over MCP, governed by table-level ACL + audit.
Query your org's data in natural language — read-only MCP access to SQL, NoSQL, files & warehouses.
Analytical memory for AI agents: a real Postgres queried in plain English over MCP. One command.
Hosted MCP server for AI-driven data ops. Create apps, manage schemas, and CRUD structured data.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables natural language queries and management of databases and subscribed data shares through Anthropic's Model Context Protocol.1MIT
- FlicenseAqualityDmaintenanceEnables querying, exploring, and interacting with Azure SQL databases through MCP-compatible clients like Claude Desktop.5-
- FlicenseAqualityBmaintenanceEnables querying JSON/JSONL social datasets in Claude Desktop via MCP tools, using DuckDB as the backend database.8-
- AlicenseBqualityAmaintenanceEnables AI assistants to connect to 17+ databases and query/analyze data using natural language via MCP and HTTP APIs, supporting platforms like Claude Desktop, Cursor, and VS Code.42107MIT
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/rawtreedb/rawtree-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server