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.

Purpose: Execute a read-only SQL query against a RawTree database 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"

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": }.

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"

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, optionally using a customer-owned S3 bucket configured for the cluster.

Returns: The database and table names plus the resolved storage destination. S3 responses include the full bucket, object path, and endpoint.

Behavior: Omit s3Storage to inherit database-level storage when configured, then the cluster's default storage. To use an explicit per-table customer-owned S3 configuration, provide the complete s3Storage object with data and backup buckets, optional paths, roleArn, and externalId. Paths default to the bucket root when omitted.

Credentials: The API does not return S3 credentials in cluster metadata. Confirm the exact buckets, paths, role ARN, and External ID before using an explicit s3Storage override.

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, database, 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

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, database, organization, and creation dates.

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

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 externalId exactly.

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 tables inherit unless they specify their own storage. Destination paths are optional; the buckets, roleArn, and externalId are required inside s3Storage.

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.

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 optional database_s3_access metadata for independent per-database storage. s3_storage exposes bucket and path values; database_s3_access exposes its External ID and bucket tag. 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 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 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 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; the buckets, roleArn, and externalId are required inside s3Storage. databaseS3Access is also optional and independent from s3Storage: provide it when databases may later use dedicated customer-owned buckets, even if the cluster keeps RawTree-managed default storage. It contains the External ID and the immutable database bucket tag; each customer database bucket must carry rawtree.com/cluster=. When both settings are supplied, their External ID values must match. The role ARN and bucket destinations for an individual database are supplied later in create-database.s3Storage.

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

Safety: You MUST first call list-cluster-sizes, then confirm the exact organization, 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. Never reuse a successful verification after changing any s3Storage field. If databaseS3Access is provided, confirm that its External ID and immutable bucket tag are intentional and that customer database buckets will be tagged as required; this metadata does not verify or create future database buckets.

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 optional database_s3_access metadata for independent per-database storage. s3_storage exposes bucket and path values; database_s3_access exposes its External ID and bucket tag. 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.