Skip to main content
Glama
Sign In
RawTree MCP Server

RawTree MCP Server

Official
by rawtreedb
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

Run Query

run-query
Destructive

Execute SQL queries to read, insert, and modify data within RawTree. Manage database schema, roles, and configuration using precise SQL commands.

Instructions

Execute one SQL statement through RawTree's Query API. Supports reads and the writes below; this tool can change data, table configuration, and access controls. Use the existing connection with sufficient permission; supported writes do not require a browser login or a different execution surface.

Supported statements and permissions:

  • SELECT, WITH, EXPLAIN, DESCRIBE: read_only, read_write, or admin API key, or a signed-in session. Database-role keys support reads subject to their database grants; they cannot execute the write families below. write_only keys cannot use this endpoint.

  • INSERT INTO [(columns)] SELECT ... (including a WITH source): read_write/admin or a signed-in session. The target must already exist in the selected user database. VALUES, FORMAT, and url()/urlCluster() sources are unsupported; use insert-json or insert-from-url for ingestion.

  • CREATE TABLE [IF NOT EXISTS] ENGINE = ReplicatedRawMergeTree [ORDER BY ]: admin API key or a signed-in session. No column definitions, engine arguments, other engines, AS SELECT, or other table clauses except optional ON CLUSTER 'default'.

  • ALTER TABLE MODIFY ORDER BY ; ADD/MATERIALIZE/CLEAR/DROP PROJECTION; ADD/MATERIALIZE/CLEAR/DROP INDEX (including text indexes): admin API key or a signed-in session. One operation per statement, on a table in the selected user database; no ON CLUSTER or IN PARTITION. ADD accepts IF NOT EXISTS; MATERIALIZE/CLEAR/DROP accept IF EXISTS. ADD INDEX requires an expression and TYPE, optionally positive integer GRANULARITY; AFTER is unsupported. Use storage paths such as __raw_data.field in index/projection definitions, with casts as needed.

  • KILL MUTATION WHERE table = '' [AND mutation_id = '']: admin API key or a signed-in session. The backend applies the selected user database automatically. Only these equality filters are supported; use doubled quotes, not backslash escapes, in string values.

  • CREATE ROLE , DROP ROLE [IF EXISTS] , GRANT SELECT/INSERT [(columns)] ON . TO : admin API key or organization administrator session. Grants can combine SELECT and INSERT and use database.* or .; the target must be an existing role, not a user. No role inheritance, delegation options, or REVOKE.

  • CREATE [OR REPLACE] WORKLOAD/RESOURCE, CREATE WORKLOAD/RESOURCE IF NOT EXISTS, DROP WORKLOAD/RESOURCE [IF EXISTS]: admin API key or organization administrator session. Workloads support IN and literal SETTINGS; resources support MASTER/WORKER THREAD and READ/WRITE DISK or ANY DISK operations.

  • CREATE SETTINGS PROFILE [OR REPLACE | IF NOT EXISTS], DROP SETTINGS PROFILE [IF EXISTS]: admin API key or organization administrator session. Only workload = '' and use_concurrency_control = 0/1, optionally READONLY/CONST, assigned TO 1–32 distinct existing roles.

  • CREATE ROW POLICY [OR REPLACE | IF NOT EXISTS], DROP ROW POLICY [IF EXISTS]: admin API key or organization administrator session. One table in the selected user database; SELECT USING a scalar filter, optional AS PERMISSIVE/RESTRICTIVE, TO 1–32 distinct existing roles. No subqueries, user targets, or wildcard targets.

  • CREATE NAMED COLLECTION [IF NOT EXISTS] AS key = literal, ...: admin API key or organization administrator session. Unique keys with string/numeric/boolean values and optional OVERRIDABLE/NOT OVERRIDABLE; no ALTER or DROP.

Role, workload/resource, profile, policy, and named-collection management accept optional ON CLUSTER 'default' and preserve the engine's replication semantics; row policies with ON CLUSTER require an explicit matching database.table. These management operations can affect the cluster beyond the selected database. All write families are unavailable in RawTree's internal organization. Other SQL mutations, including UPDATE, DELETE, DROP TABLE, and arbitrary ALTER, are unsupported; use delete-table for table deletion.

Returns JSON meta, data, rows, statistics, and optional hints. DDL normally returns an empty result; INSERT SELECT reports statistics.written_rows; KILL MUTATION returns matched mutations. MATERIALIZE/CLEAR run in the background: inspect system.mutations for progress and system.projections or system.data_skipping_indices for definitions. Repeating writes may duplicate data or change state; inspect results before retrying. For exploratory reads, use LIMIT and deterministic ORDER BY.

Detailed syntax and replication limits: https://rawtree.com/docs/reference/api and https://rawtree.com/docs/reference/authentication#existing-database-roles.

Input Schema

NameRequiredDescriptionDefault
sqlYesOne supported SQL statement to execute: a read query or an authorized INSERT SELECT, CREATE TABLE, ALTER TABLE, KILL MUTATION, or management statement listed in the tool description. Writes can change persistent state. Use LIMIT for exploratory reads.
clusterNoRawTree cluster to use for this operation.
databaseNoOptional RawTree database override. RawTree uses the default database when omitted.
organizationNoRawTree organization containing the target cluster.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.4.3
    • changedInput schema / properties / sql / description
      Previous value: -"Read-only SQL to execute. Prefer bounded SELECT queries with LIMIT for exploration."New value: +"One supported SQL statement to execute: a read query or an authorized INSERT SELECT, CREATE TABLE, ALTER TABLE, KILL MUTATION, or management statement listed in the tool description. Writes can change persistent state. Use LIMIT for exploratory reads."
  2. Changed4 schema fields changedv0.3.2
    • changedInput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • addedInput schema / properties / cluster
      Added value: +{
+  "description": "RawTree cluster to use for this operation.",
+  "minLength": 1,
+  "type": "string"
+}
    • addedInput schema / properties / database
      Added value: +{
+  "description": "Optional RawTree database override. RawTree uses the default database when omitted.",
+  "minLength": 1,
+  "type": "string"
+}
    • addedInput schema / properties / organization
      Added value: +{
+  "description": "RawTree organization containing the target cluster.",
+  "minLength": 1,
+  "type": "string"
+}
  3. First observedv0.1.0

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The annotations already mark this tool as non-read-only, non-idempotent, and destructive; the description adds substantial context beyond that, including permission requirements, data/state mutation risks, duplicate-write warnings, background operation behavior, and restrictions in internal organizations. It also explains what DDL and KILL MUTATION return, which is meaningful behavioral detail absent from annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Although long, the length is justified by the number of supported SQL families and permission combinations. The description is front-loaded with purpose and risk, then organized into readable bullet categories, with no obvious filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, and the description compensates well by explaining the JSON result shape, DDL empty results, INSERT SELECT written_rows, KILL MUTATION matched mutations, and background MATERIALIZE/CLEAR behavior. It is nearly complete, though some advanced SQL limitations are deferred to external documentation links.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds significant meaning for the sql parameter by enumerating the statement forms and constraints that are valid. It also clarifies database and organization targeting behavior, though cluster and organization semantics are largely already covered by schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: "Execute one SQL statement through RawTree's Query API." It then enumerates supported read and write statement families, which clearly distinguishes this general SQL execution tool from siblings like insert-json, insert-from-url, and delete-table.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is unusually explicit: it lists which statements are supported, which permissions each family requires, and which statements are unsupported. It also names alternatives for excluded operations, such as insert-json and insert-from-url for ingestion and delete-table for table deletion.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools