Purpose: List RawTree organizations available to the authenticated user.

Returns: Organization names, roles, plans, and avatar URLs.

Auth: Requires a user credential such as OAuth. Database API keys are not user credentials and cannot list organizations.

When to use:

• You need an organization name before listing clusters

• The user wants to work across multiple organizations through one MCP connection

Purpose: List accepted members of a RawTree organization.

Returns: Member user IDs, email addresses, roles, and creation times. Pending invitations are not included.

Auth: Requires a user credential and membership in the organization. Authorization is enforced by the RawTree API.

When to use:

• You need the member user ID before changing a role or removing access

• The user wants to inspect who belongs to an organization

Purpose: Start adding a member to a RawTree organization by sending an invitation to their email address.

Returns: Whether the invitation was created, its invite link, and its expiration time.

Behavior: This creates a pending invitation. The person becomes a member only after accepting it and will not appear in list-organization-members before acceptance. New members join with the member role; use update-organization-member after acceptance to promote them.

Auth: Requires a user credential with organization admin access. Authorization is enforced by the RawTree API.

Safety: This sends an external email and creates a pending access invitation. You MUST confirm the exact organization and email address with the user before calling this tool.

Purpose: Change an accepted organization member's role to admin or member.

Returns: The member's updated role.

NOT for: Pending invitations. Use list-organization-members to identify an accepted member and obtain their user ID.

Auth: Requires a user credential with organization admin access. Authorization is enforced by the RawTree API. RawTree prevents demoting the last organization admin.

Safety: Changing a role can grant administrative privileges or revoke them. You MUST confirm the exact organization, member, and new role with the user before calling this tool.

Purpose: Remove an accepted member from a RawTree organization and revoke their organization access.

Returns: Whether the member was removed.

NOT for: Revoking a pending invitation. Use list-organization-members to identify an accepted member and obtain their user ID.

Auth: Requires a user credential with organization admin access. Authorization is enforced by the RawTree API. RawTree prevents removing the last organization admin.

Safety: This revokes the member's access to the organization. You MUST confirm the exact organization and member with the user before calling this tool.

List service accounts in an organization, including their IDs, names, descriptions, and stored organization roles. Requires an organization admin using a user session or OAuth; API keys cannot manage service accounts.

Create an organization service account with an immutable, unique name. Returns its ID, organization ID, name, description, and stored role. Requires an organization admin using a user session or OAuth; API keys cannot manage service accounts. This creates an identity without credentials. API key permissions are configured separately. An organization can have up to 100 service accounts.

List all federation issuers. Returns an array of complete objects with configuration, IDs and timestamps. Requires an organization admin using a user session or OAuth with full_access. API keys and workload tokens cannot manage federation configuration.

Read the saved configuration. Returns an issuer object with its full configuration, id, organization_id, created_at and updated_at. Requires an organization admin using a user session or OAuth with full_access. API keys and workload tokens cannot manage federation configuration.

Create an organization issuer with discovery or an explicit JWKS URL. Saving does not fetch keys. Returns an issuer object with its full configuration, id, organization_id, created_at and updated_at. Requires an organization admin using a user session or OAuth with full_access. API keys and workload tokens cannot manage federation configuration.

Replace the complete configuration (PUT), not a partial update. Omitted optional fields are cleared. Changes invalidate existing workload access tokens. Returns an issuer object with its full configuration, id, organization_id, created_at and updated_at. Requires an organization admin using a user session or OAuth with full_access. API keys and workload tokens cannot manage federation configuration.

Delete the issuer. Referencing rules must be deleted first; otherwise the API returns 409. Returns null on success. Requires an organization admin using a user session or OAuth with full_access. API keys and workload tokens cannot manage federation configuration.

List all federation rules. Returns an array of complete objects with configuration, IDs and timestamps. Requires an organization admin using a user session or OAuth with full_access. API keys and workload tokens cannot manage federation configuration.

Read the saved configuration. Returns a rule object with its full configuration, id, organization_id, cluster_id, created_at and updated_at. Requires an organization admin using a user session or OAuth with full_access. API keys and workload tokens cannot manage federation configuration.

Create a cluster rule mapping an external identity to your user or a service account. An enabled rule permits authentication and grants the configured access. Returns a rule object with its full configuration, id, organization_id, cluster_id, created_at and updated_at. Requires an organization admin using a user session or OAuth with full_access. API keys and workload tokens cannot manage federation configuration.

Replace the complete configuration (PUT), not a partial update. Omitted optional fields are cleared. Changes invalidate existing workload access tokens. Returns a rule object with its full configuration, id, organization_id, cluster_id, created_at and updated_at. Requires an organization admin using a user session or OAuth with full_access. API keys and workload tokens cannot manage federation configuration.

Delete the rule and revoke workload access through it. Returns null on success. Requires an organization admin using a user session or OAuth with full_access. API keys and workload tokens cannot manage federation configuration.

Purpose: List the integrations connected to a RawTree organization, such as Slack workspaces.

Returns: { integrations, slack_available, settings_url }. Each integration has id, organization_id, type ("slack"), settings (team_id, team_name, bot_user_id, scopes), and created_at. slack_available is false when Slack is not configured for this RawTree deployment. settings_url links to the organization's integrations settings page in the RawTree app.

Behavior: Connecting or disconnecting Slack is not available through MCP: an organization admin must do it on the integrations settings page in the RawTree app. Share settings_url with the user when no Slack workspace is connected.

Auth: Requires a user credential such as OAuth and membership in the organization. API keys are not supported. Authorization is enforced by the RawTree API.

When to use:

• You need a Slack integration ID for a workflow Slack sink

• The user wants to know which Slack workspaces the organization has connected

Purpose: List or search the channels of a Slack workspace connected to a RawTree organization.

Returns: { channels, next_cursor }. Each channel has id, name, and is_private. next_cursor is null when there are no more results.

Behavior: Results are paginated. Pass next_cursor as cursor, with the same name when searching, to continue. With name, returns channels whose name contains it, ignoring a leading #, surrounding spaces, and case. Each search request scans a bounded part of the workspace, so a page can have no channels while next_cursor is set: the search has not finished, so call again with that cursor and the same name. Workflow Slack sinks accept a channel_name directly; use this tool to find a channel or confirm its exact name. The RawTree app must be a member of a private channel before it can post there.

Auth: Requires a user credential such as OAuth and membership in the organization. API keys are not supported. Authorization is enforced by the RawTree API.

When to use:

• You need to find a Slack channel for a workflow Slack sink

• The user describes a channel only partially and you need its exact name or ID

Format complete SQL with the native RawTree formatter without executing statements or writing database query logs. Supports multiple statements and preserves literals. Inline INSERT VALUES data is copied verbatim without completeness or schema validation.

Returns JSON { "formatted": "..." } containing the entire formatted SQL. The API allows a 50 MiB JSON request, 100 MiB formatted output, and 30 seconds of formatting. Requires a backend with POST /v1/query-format.

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.

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).

Returns: Insert confirmation, usually { "inserted": <row_count> }.

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

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"

Purpose: Ask RawTree to ingest JSON/JSONL data from a public URL into a table. Waits for the import to complete.

NOT for: Private files on your machine or authenticated URLs. Normalize or transform data before making it available at the public URL.

Returns: The completed import result as JSON: inserted is the row count, or null when unavailable.

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"

List all saved SQL queries visible to you in a cluster, across databases. Returns { queries: [...] } with each query's id, organization_id, cluster_id, user_id, name, sql, database, visibility, created_at, and updated_at. There is no pagination.

User sessions and OAuth can see their own private queries and cluster-shared queries. Standard API keys with read permission can see only cluster-shared queries; write-only and database-role keys are not supported.

To execute a saved query, pass its sql and database to run-query with the same organization and cluster. Listing does not execute SQL or grant access to the underlying data.

Save SQL for reuse without executing it. Omit id to create a query; name, sql, and database are required. Visibility defaults to private. Supply id to update an existing query, with at least one of name, sql, database, or visibility. Omitted fields remain unchanged; null is invalid. Use the id returned by list-saved-queries or a previous save-query call.

Requires a user session or OAuth; API keys are not supported. The authenticated user owns new queries and can update only their own queries. Set visibility to cluster to share the definition with cluster members. Returns the saved query: id, organization_id, cluster_id, user_id, name, sql, database, visibility, created_at, and updated_at.

Delete a saved query you own by its id. Requires a user session or OAuth; API keys are not supported. Deletes only the saved definition and does not execute SQL or delete underlying data. Returns { id, deleted: true } after successful deletion.

Purpose: List all tables in a RawTree database with row and byte counts.

NOT for: Reading table rows. Use run-query for data and describe-table for columns.

Returns: Tables plus database 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

Purpose: Create an empty RawTree table in a database.

Returns: The database and table names, the resolved storage destination, and the table's sorting key.

Behavior: The table uses the database's storage when the database configures one, and the cluster's default storage otherwise. Storage is configured on the cluster or the database, never per table.

Sorting key: sortingKey is an optional string of comma-separated SQL expressions. Omit it and the table picks a sorting key per part from the ingested data, which suits exploratory tables. Set it when the query pattern is known, listing expressions in key order, lowest cardinality first. Use update-table to change it later.

Auth: Requires organization admin access. Authorization is enforced by the RawTree API.

Reliability: If the response is ambiguous, call list-tables to reconcile by database and table name before retrying.

Purpose: Inspect a RawTree table's columns, row count, byte count, sorting key, database, and organization.

NOT for: Sampling actual row values. Use run-query for SELECT queries.

Returns: Table metadata and columns. sorting_key is a comma-separated SQL expression string, empty when the table picks a key per part from the ingested data.

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

• You want the current sorting key before changing it with update-table

Purpose: Change the sorting key of an existing RawTree table.

NOT for: Renaming a table, adding columns, or changing storage. Only the sorting key can be updated.

Returns: The database and table names plus the new sorting key.

Behavior: Provide a comma-separated SQL expression string in key order, lowest cardinality first. A bare name such as user.id is read as a path into the ingested JSON. The new key applies to newly inserted parts and wins later merges, so existing parts are re-sorted in the background instead of being rewritten by this call. Call describe-table first to see the current key.

Limits: The key must contain at least one expression; a table's sorting key cannot be removed once set. RawTree validates the SQL expressions and the engine may reject an unusable key.

Auth: Requires organization admin access. Authorization is enforced by the RawTree API.

Safety: You MUST confirm the exact table name and sorting expression order with the user before calling this tool.

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.

Purpose: List recent RawTree insert/query/describe/explain activity for a database.

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"

Purpose: List API keys for a RawTree cluster.

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 or database roles, default database, creation dates, and expires_at (UTC timestamp or null for never).

Auth: Uses GET /v1/keys and requires an admin database 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 database

Purpose: Create a new RawTree API key for a cluster.

NOT for: User login. Use RawTree auth/CLI or the dashboard for that workflow.

Returns: The new API key value and expires_at (UTC timestamp or null for never). 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 database 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

Purpose: Permanently revoke and delete a RawTree API key by UUID or full API key value.

NOT for: Deleting a table, database, 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.

Purpose: List databases in a RawTree organization and cluster.

Returns: Database names and their organization context. Databases with explicit customer-owned storage include s3_storage metadata; null means the database inherits the cluster's default storage. This metadata contains bucket and path values only; credentials are never returned.

When to use:

• You need a database name before using query, table, ingest, or log tools

• The user wants to switch databases without configuring another MCP server

Purpose: Verify that RawTree can use a customer IAM role to access customer-owned S3 storage before creating a database.

Returns: Whether access was verified and a human-readable result message.

Behavior: RawTree assumes roleArn using the cluster's saved external_id, checks the data and backup bucket locations, lists each configured path, and writes, reads, then removes a temporary probe object under each path. Paths are optional and default to the bucket root. Both configured buckets must be in the cluster environment's AWS region.

Safety: This check temporarily writes to and deletes from both configured destinations. Confirm the exact organization, cluster, database name, buckets, paths, role ARN, and External ID before running it. The IAM trust policy's External ID must match the cluster's saved external_id exactly; this tool does not accept an identity override.

Auth: Organization-admin access is required. Authorization is enforced by the RawTree API.

Reliability: The check is safe to retry. Newly changed IAM policies may require a short propagation delay before verification succeeds.

Purpose: Create a database in a RawTree organization and cluster.

Returns: The created database and organization context.

Behavior: s3Storage is optional. Omit it to use the cluster's default storage. When provided, it configures customer-owned database storage that all tables in the database inherit. Destination paths are optional; data and backups (each with a bucket), plus roleArn are required inside s3Storage. The API reuses the cluster's saved External ID; do not supply an identity override.

Safety: You MUST first call list-databases and confirm the exact organization, cluster, database name, and optional S3 configuration with the user. If s3Storage is provided, first call verify-database-s3-access with the identical configuration. Never reuse a successful verification after changing any s3Storage field.

Auth: Organization-admin access is required. Authorization is enforced by the RawTree API.

Reliability: This operation is not idempotent. If the response is ambiguous, call list-databases to reconcile by organization, cluster, and database name before retrying.

Purpose: Permanently delete a RawTree database and all data it contains.

Returns: RawTree's deletion result, usually { "deleted": true }.

Safety: You MUST list databases first and ask the user to confirm the exact organization, cluster, and database name before calling this tool. This action cannot be undone.

Auth: Authorization is enforced by the RawTree API.

List the public and BYOC regions accessible to an organization. Use an enabled region ID for cluster creation and its prerequisite size and S3 checks. Regions need a ready deployment, except the legacy public default.

Purpose: List RawTree dedicated clusters accessible in an organization.

Returns: Cluster IDs, names, creation times, lifecycle status, resources, whether each cluster can be paused or resumed, optional s3_storage metadata for customer-owned default storage, and s3_storage_access containing external_id and resource_tag (null for older clusters without saved identity). s3_storage exposes data and backups, each with bucket and path. An empty path means the bucket root. Role ARNs and secret credentials are never returned.

With user authentication, discovery spans enabled regions. If a region is unavailable, healthy clusters are returned with unavailable_regions (region IDs and names). This is a partial list: do not infer that missing clusters do not exist; retry discovery. Each regional lookup is limited to five seconds. Authentication failures and total regional outages remain errors.

Auth: The RawTree API requires a user access token and organization membership. Authorization is enforced by the API.

When to use:

• User asks which dedicated clusters exist

• You need a cluster ID or current lifecycle status

• You need to inspect provisioned resources before creating another cluster

Purpose: List the current RawTree cluster creation options.

Returns: Supported per-replica sizes, minimum and maximum replica counts, and the default minimum and maximum vertical autoscaling sizes.

Auth: Requires a user credential such as OAuth. Authorization is enforced by the RawTree API.

When to use: You MUST call this tool before create-cluster so replicas and both sizes come from the current backend-controlled catalog.

Purpose: Verify that RawTree can use a customer IAM role to access customer-owned S3 storage before cluster creation.

Returns: Whether access was verified and a human-readable result message.

Behavior: RawTree assumes roleArn using s3StorageAccess.externalId, checks the data and backup bucket locations, lists each configured path, and writes, reads, then removes a temporary probe object under each path. Paths are optional and default to the bucket root. Both configured buckets must be in the cluster environment's AWS region.

Auth: The RawTree API requires a user access token with organization admin access. Authorization is enforced by the API.

When to use: Use this tool after the IAM trust and permissions policies are configured and immediately before create-cluster whenever its optional s3Storage field will be provided. It is unnecessary when RawTree-managed storage will be used.

Safety: This check temporarily writes to and deletes from both configured destinations. Confirm the exact organization, buckets, paths, role ARN, and External ID before running it. The IAM trust policy's External ID must match s3StorageAccess.externalId exactly.

Reliability: The check is safe to retry. Newly changed IAM policies may require a short propagation delay before verification succeeds.

Purpose: Provision a new RawTree dedicated cluster in an organization.

Returns: The newly created cluster, including its ID, lifecycle status, and initial resources. Provisioning continues asynchronously after the request is accepted; use get-cluster to check progress.

Behavior: The cluster starts at minimumSize and can vertically autoscale per replica up to maximumSize. The replica count remains fixed. s3Storage is optional: omit it to use RawTree-managed storage. When provided, it configures customer-owned data and backup destinations through a customer IAM role. Destination paths are optional; data and backups (each with a bucket), plus roleArn are required inside s3Storage. s3StorageAccess contains the immutable externalId and resourceTag for this cluster's S3 storage access. The API generates omitted values independently using secure UUIDs, but requires an explicit s3StorageAccess.externalId for custom S3 matching the customer IAM trust policy. The MCP client forwards optional identity values without generating them. Tag eligible customer buckets and IAM roles with rawtree.com/cluster=. Database operations reuse this saved identity automatically.

Auth: The RawTree API requires a user access token with organization admin access. Authorization is enforced by the API.

Safety: When selecting a region, first call list-regions and use the same regionId for list-cluster-sizes, verify-cluster-s3-access and create-cluster. You MUST first call list-cluster-sizes, then confirm the exact organization, region, name, replica count, minimum per-replica size, maximum per-replica size, vertical autoscaling behavior, and idle timeout with the user. If idleTimeoutMinutes is omitted, explain that the server default will apply. For one replica, warn that the cluster has no redundancy. If s3Storage is provided, first call verify-cluster-s3-access with the identical configuration and confirm the data and backup buckets, optional paths, role ARN, and External ID. Pass the same s3StorageAccess.externalId to verification and creation. Never reuse a successful verification after changing s3StorageAccess.externalId or any s3Storage field. Confirm any explicitly supplied identity values with the user; generated values are returned with the cluster.

Reliability: This operation is not idempotent. If the response is ambiguous, call list-clusters to reconcile by organization and name before retrying.

Purpose: Get one RawTree dedicated cluster and its current lifecycle status.

Returns: The cluster ID, name, creation time, lifecycle status, resources, whether it can be paused or resumed, optional s3_storage metadata for customer-owned default storage, and s3_storage_access containing external_id and resource_tag (null for older clusters without saved identity). s3_storage exposes data and backups, each with bucket and path. An empty path means the bucket root. Role ARNs and secret credentials are never returned.

Auth: The RawTree API requires a user access token and organization membership. Authorization is enforced by the API.

When to use:

• User asks for the current status of one cluster

• You need to check progress after pausing or resuming a cluster

• You already have a cluster ID and do not need the full organization cluster list

Purpose: Update the idle timeout for a RawTree dedicated cluster.

Returns: The updated cluster, including its effective idle timeout and current lifecycle status.

Behavior: idleTimeoutMinutes controls how many minutes of inactivity pass before the cluster automatically pauses. Use 0 to disable idling. Values from 15 through 43200 minutes are supported.

Auth: The RawTree API requires a user access token with organization admin access. Authorization is enforced by the API.

Safety: You MUST confirm the exact organization, cluster ID, and new idle timeout with the user before calling this tool.

Purpose: Request that a RawTree dedicated cluster pause.

Returns: The updated cluster, including its lifecycle status. Pausing continues asynchronously after the request is accepted. Use get-cluster to check one cluster's progress.

Auth: The RawTree API requires a user access token with organization admin access. Authorization is enforced by the API.

Safety: Pausing makes the cluster's databases unavailable until it is resumed. You MUST confirm the exact organization and cluster ID before calling this tool.

Purpose: Request that a paused RawTree dedicated cluster resume.

Returns: The updated cluster, including its lifecycle status. Resuming continues asynchronously after the request is accepted. Use get-cluster to check one cluster's progress.

Auth: The RawTree API requires a user access token with organization admin access. Authorization is enforced by the API.

Safety: You MUST confirm the exact organization and cluster ID before calling this tool.

Purpose: List managed connectors for one RawTree cluster.

Returns: Connector IDs, names, types, statuses, destinations, sanitized settings, revisions, and timestamps. Stored credentials are never returned.

Auth: Requires a user credential and organization membership. Connector management may be unavailable in some environments.

Purpose: Get one managed connector and its complete public configuration.

Returns: The connector status, sanitized connection settings, destinations with topics and consumer groups, revision, and timestamps. Stored credentials are never returned.

When to use: Inspect the latest connector before adding a destination or changing its status.

Purpose: Create an active Kafka connector with one or more independent topic-to-table destinations.

Behavior: Consumption starts after the runtime applies the connector. Each destination uses its own consumer group; omit group_id to let RawTree generate one. Destination tables can be created automatically when their first events arrive.

Auth: Requires organization-admin access.

Safety: Confirm the exact organization, cluster, connector name, bootstrap servers, offset policy, topics, consumer groups, and destination tables before calling. Treat SASL values as secrets and never repeat them in confirmation text or logs.

Reliability: Creation is not idempotent. If the response is ambiguous, call list-connectors and reconcile by name before retrying.

Purpose: Read current health and runtime counters for one connector and each destination.

Returns: Runtime status, observation time, Kafka consumer lag, buffered events, consumed and delivered event totals, errors, discarded events, source lag, and HTTP latency counters.

Interpretation: Event values are cumulative counters. Take two samples and divide their difference by elapsed time to calculate rates. A status of applying or unavailable includes an explanatory message.

Purpose: Add one Kafka topic-to-table destination to an existing connector without changing its current destinations.

Behavior: The tool reads the latest connector, preserves every existing destination, and appends the new destination. Omit group_id to let RawTree generate an independent consumer group. An exact existing database/table destination is treated as an idempotent success; conflicting settings are rejected.

Auth: Requires organization-admin access.

Safety: Confirm the exact organization, cluster, connector ID, topics, optional consumer group, database, and table before calling.

Purpose: Pause or resume every destination in one connector.

Behavior: paused removes the connector from the active runtime. active restores it with the same destination consumer groups, so Kafka resumes from their committed offsets subject to Kafka retention and at-least-once delivery.

Auth: Requires organization-admin access.

Safety: Confirm the exact organization, cluster, connector ID, and requested status. Pausing interrupts ingestion for all destinations until resumed.

Purpose: List the RawTree app catalog and installation state for one cluster.

Returns: The cluster ID and name, plus every available app with its ID, display name, and installed state.

Auth: Requires a user credential and organization membership. Authorization is enforced by the RawTree API.

When to use:

• You need a valid app ID before installing or uninstalling an app

• You want to check which apps are installed on a cluster

• You want to verify installation state after a change

Purpose: Install a RawTree app on one cluster and enable its native endpoints.

Returns: The app ID, display name, and installed state set to true.

Auth: Requires a user credential with organization admin access. Authorization is enforced by the RawTree API.

Safety: This changes the app functionality enabled for the cluster. You MUST confirm the exact organization, cluster name, and app ID with the user before calling this tool.

Purpose: Uninstall a RawTree app from one cluster and disable its native endpoints.

Returns: The app ID, display name, and installed state set to false.

Behavior: Uninstalling removes the app installation state. It does not delete existing data stored in the cluster.

Auth: Requires a user credential with organization admin access. Authorization is enforced by the RawTree API.

Safety: This makes the app's native endpoints unavailable for the cluster. You MUST confirm the exact organization, cluster name, and app ID with the user before calling this tool.

List all workflows in one cluster across databases. Returns { workflows: [...] } with complete workflow objects; no pagination. Returns the workflow object: id, name, description, query, schedule, revision, created_at, updated_at, and sinks. The query object contains database and sql. schedule is null for manual-only workflows; otherwise it contains cron, enabled, and next_run_at (null while paused). Each sink has id, type, and settings. HTTP settings contain url (null when unreadable), url_configured, and header_names; header values are never returned. Table settings contain database and table. Slack settings contain integration_id, channel_id, and channel_name, resolved from Slack when the sink was saved. Requires an admin API key bound to the selected organization and cluster, or OAuth. Organization members may read; organization admins may create, update, or delete. Workflows execute with organization credentials and continue after the creating key is revoked or expires.

Read a workflow and its current schedule configuration. Returns the workflow object: id, name, description, query, schedule, revision, created_at, updated_at, and sinks. The query object contains database and sql. schedule is null for manual-only workflows; otherwise it contains cron, enabled, and next_run_at (null while paused). Each sink has id, type, and settings. HTTP settings contain url (null when unreadable), url_configured, and header_names; header values are never returned. Table settings contain database and table. Slack settings contain integration_id, channel_id, and channel_name, resolved from Slack when the sink was saved. Requires an admin API key bound to the selected organization and cluster, or OAuth. Organization members may read; organization admins may create, update, or delete. Workflows execute with organization credentials and continue after the creating key is revoked or expires.

Create a scheduled SQL workflow. Requires name and query (database and sql). Defaults: schedule={ cron: "* * * * * *", enabled: true }, sinks=[]. An enabled schedule starts recurring SQL execution and sink delivery; use schedule.enabled=false to create it paused, or schedule=null for manual-only. SQL may write rows through INSERT SELECT. Creation is not idempotent: reconcile an uncertain result with list-workflows before retrying. Returns the workflow object: id, name, description, query, schedule, revision, created_at, updated_at, and sinks. The query object contains database and sql. schedule is null for manual-only workflows; otherwise it contains cron, enabled, and next_run_at (null while paused). Each sink has id, type, and settings. HTTP settings contain url (null when unreadable), url_configured, and header_names; header values are never returned. Table settings contain database and table. Slack settings contain integration_id, channel_id, and channel_name, resolved from Slack when the sink was saved. Requires an admin API key bound to the selected organization and cluster, or OAuth. Organization members may read; organization admins may create, update, or delete. Workflows execute with organization credentials and continue after the creating key is revoked or expires.

Update only supplied fields of an existing workflow; at least one changed field is required. Omitted fields remain unchanged. Set schedule.enabled=false to pause or schedule.enabled=true to resume; set schedule.cron to change the cadence. Supplying sinks replaces the whole list and may remove delivery targets. Read get-workflow before editing sinks so you can preserve their IDs. Already buffered deliveries can continue after pausing. Returns the workflow object: id, name, description, query, schedule, revision, created_at, updated_at, and sinks. The query object contains database and sql. schedule is null for manual-only workflows; otherwise it contains cron, enabled, and next_run_at (null while paused). Each sink has id, type, and settings. HTTP settings contain url (null when unreadable), url_configured, and header_names; header values are never returned. Table settings contain database and table. Slack settings contain integration_id, channel_id, and channel_name, resolved from Slack when the sink was saved. Requires an admin API key bound to the selected organization and cluster, or OAuth. Organization members may read; organization admins may create, update, or delete. Workflows execute with organization credentials and continue after the creating key is revoked or expires.

Delete a workflow definition and its schedule, stopping future evaluations. Does not undo previous SQL writes or completed deliveries. Returns { id, deleted: true } only after the API confirms deletion. Requires an admin API key bound to the selected organization and cluster, or OAuth. Organization members may read; organization admins may create, update, or delete. Workflows execute with organization credentials and continue after the creating key is revoked or expires.