Servidor MCP de RawTree

Un servidor MCP para RawTree, una base de datos analítica para datos no estructurados. Consulta datos con SQL, inserta JSON, inspecciona esquemas de tablas, revisa registros de RawTree y gestiona credenciales de base de datos desde clientes MCP como Claude Code, Cursor y Claude Desktop.

Características

• Consultas — Ejecuta SQL de solo lectura contra una base de datos de RawTree y recibe filas JSON, metadatos, estadísticas y sugerencias.

• Ingesta — Inserta un único objeto JSON, arrays de objetos JSON o datos desde una URL pública. Soporta transformaciones integradas de RawTree para trazas/logs/métricas OTLP, CloudWatch Logs, CloudTrail y Firehose.

• Tablas — Lista tablas, describe columnas y tamaños de tablas, y elimina tablas tras confirmación explícita.

• Registros — Inspecciona el historial de consultas e inserciones de RawTree con filtros estructurados por tipo, estado, origen, tabla, sugerencias, ventana de tiempo y paginación.

• Claves API — Lista, crea y revoca claves API de RawTree para una base de datos. Las respuestas de creación incluyen el valor de la clave API de un solo uso.

• Organizaciones — Lista las organizaciones disponibles para un usuario autenticado mediante OAuth.

• Bases de datos — Lista bases de datos en un clúster y verifica el acceso a una base de datos seleccionada.

• Clústeres — Lista clústeres dedicados y aprovisiona un clúster tras confirmación explícita. RawTree aplica autorización de usuario y administrador de organización.

• Transportes — Soporta stdio para clientes MCP locales y Streamable HTTP de doble era para implementaciones remotas o con múltiples clientes, incluyendo solicitudes stateless MCP 2026-07-28 y clientes heredados de handshake de inicialización.

Related MCP server: Chakra MCP Server

Configuración

Crea una clave API de RawTree desde la CLI, el panel de control o la API de RawTree. Una clave API de base de datos comienza con rt_ y es suficiente para herramientas de datos como run-query, insert-json, list-tables y list-logs.

La herramienta get_database usa la clave API actual para leer la identidad de la base de datos desde el endpoint de claves de RawTree, con un respaldo del endpoint de tablas para claves API de base de datos no administradoras con capacidad de solo lectura.

Uso

El servidor soporta dos modos de transporte: stdio (por defecto) y HTTP.

Transporte Stdio

Configuración Rápida

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

Claude Code

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

Cursor

Abre la paleta de comandos y elige "Configuración de Cursor" > "MCP" > "Agregar nuevo servidor MCP global".

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

Claude Desktop

Abre la configuración de Claude Desktop > pestaña "Desarrollador" > "Editar Config".

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

Transporte HTTP

Ejecuta el servidor sobre HTTP para integraciones remotas o basadas en web. En modo HTTP, cada cliente MCP se autentica pasando su clave API de RawTree en el encabezado Authorization.

Inicia el servidor:

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

El servidor escucha en http://127.0.0.1:3000 y expone el endpoint MCP en /mcp usando 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"
      }
    }
  }
}

También puedes configurar el puerto mediante la variable de entorno MCP_PORT:

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

Opciones

• --api-key: Clave API de base de datos de RawTree para modo stdio

• --api-url: URL base de la API de RawTree, por defecto https://api.rawtree.com

• --database: Nombre de la base de datos para rutas con ámbito

• --org: Nombre de la organización para rutas con ámbito

• --http: Usa transporte HTTP en lugar de stdio

• --port: Puerto HTTP al usar --http, por defecto 3000 o MCP_PORT

Variables de entorno:

• RAWTREE_API_KEY: Clave API de base de datos de RawTree

• RAWTREE_API_URL: URL base de la API de RawTree, por defecto https://api.rawtree.com

• RAWTREE_DATABASE: Nombre de la base de datos para rutas con ámbito

• RAWTREE_ORG: Nombre de la organización para rutas con ámbito

• MCP_PORT: Puerto HTTP al usar --http

Herramientas

Datos

• check-health — Verifica que el endpoint de la API de RawTree sea accesible.

• run-query — Ejecuta SQL de solo lectura y devuelve la respuesta JSON de consulta de RawTree. Acepta anulaciones de organización, clúster y base de datos.

• insert-json — Inserta objeto(s) JSON en una tabla, opcionalmente con una transformación de RawTree.

• insert-from-url — Ingresa datos desde una URL pública y devuelve el flujo de progreso NDJSON de RawTree.

Tablas

• list-tables — Lista tablas en la base de datos configurada.

• describe-table — Inspecciona columnas, cantidad de filas, cantidad de bytes, base de datos y organización.

• delete-table — Elimina una tabla tras confirmación explícita. Requiere permiso de administrador.

Registros

• list-logs — Lee registros de consultas e inserciones de RawTree. Por defecto, la última hora cuando no se proporciona ventana de tiempo.

Los filtros de registro estructurados incluyen:

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

Claves API

• list-api-keys — Lista claves API para la base de datos configurada.

• create-api-key — Crea una clave con permiso admin, read_write, write_only o read_only.

• delete-api-key — Revoca una clave tras confirmación explícita.

Bases de datos

• list-databases — Lista bases de datos en una organización y clúster.

• get_database — Verifica una base de datos seleccionada y devuelve { "name": "...", "organization": { "name": "..." } }.

Organizaciones

• list-organizations — Lista organizaciones disponibles para el usuario autenticado. Requiere una credencial de usuario como OAuth.

Clústeres

• list-clusters — Lista clústeres dedicados accesibles en una organización.

• create-cluster — Aprovisiona un clúster dedicado tras confirmación explícita de su organización y configuración de recursos facturables.

Las herramientas de clúster se anuncian a todos los clientes MCP. La API de RawTree sigue siendo el límite de autorización: el acceso al clúster requiere un token de acceso de usuario, y la creación de clústeres requiere además acceso de administrador de organización.

Las implementaciones programáticas alojadas pueden requerir la selección explícita de recursos en cada herramienta aplicable. La organización y el clúster identifican el límite de recursos; la base de datos sigue siendo una anulación opcional y por defecto es default cuando se omite. Esto permite que una única conexión MCP respaldada por OAuth cambie entre organizaciones, clústeres y bases de datos sin codificar el contexto en la URL MCP:

const server = createMcpServer(client, { requireExplicitScope: true });

Ejemplos

Consulta

{
  "organization": "acme",
  "cluster": "production",
  "database": "analytics",
  "sql": "SELECT count() AS rows FROM events"
}

Insertar JSON

{
  "table": "events",
  "data": [
    {
      "event": "signup",
      "user_id": "user_123",
      "source": "mcp"
    }
  ]
}

Insertar Trazas OTLP

{
  "table": "traces",
  "transform": "otlp-traces",
  "data": {
    "resource": {
      "attributes": [
        {
          "key": "service.name",
          "value": {
            "stringValue": "api"
          }
        }
      ]
    },
    "scopeSpans": [
      {
        "spans": [
          {
            "name": "GET /health",
            "spanId": "abc"
          }
        ]
      }
    ]
  }
}

Depurar Inserciones Fallidas

{
  "statuses": ["error"],
  "types": ["insert"],
  "startTime": "2026-05-28T09:00:00.000Z",
  "endTime": "2026-05-28T10:00:00.000Z",
  "limit": 25
}

Desarrollo Local

1. Instala y construye:

pnpm install
pnpm build

2. Usa la compilación local desde un cliente MCP:

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

Pruebas en Vivo con un Cliente MCP

Ejecuta TypeScript en modo watch, luego apunta un cliente MCP separado al servidor compilado:

pnpm tsc --watch

{
  "mcpServers": {
    "rawtree-dev": {
      "command": "node",
      "args": ["/absolute/path/to/rawtree-mcp/dist/index.js"],
      "env": {
        "RAWTREE_API_KEY": "rt_xxxxxxxxx"
      }
    }
  }
}

Reinicia la sesión del cliente MCP después de cada recompilación.

Uso Programático

La raíz del paquete expone la capa reutilizable del servidor MCP. El transporte HTTP de Node está disponible por separado desde @rawtree/mcp/http, para que los adaptadores alojados puedan usar la fábrica del servidor sin importar el punto de entrada del proceso local.

import { createMcpServer, RawTreeClient } from '@rawtree/mcp';

const client = new RawTreeClient({ apiKey: process.env.RAWTREE_API_KEY! });
const server = createMcpServer(client);

Publicación

La publicación es gestionada por el flujo de trabajo Publish de GitHub Actions.

Secreto requerido del repositorio:

• NPM_TOKEN: Token de automatización de npm con permiso para publicar @rawtree/mcp.

Flujo de lanzamiento:

1. Actualiza package.json a la nueva versión.

2. Sube el cambio a main.

3. Crea y publica un lanzamiento de GitHub con una etiqueta que coincida con la versión del paquete, por ejemplo v0.2.0.

El flujo de trabajo verifica que la etiqueta del lanzamiento coincida con package.json, ejecuta lint, pruebas y compilación, luego publica con procedencia npm:

npm publish --provenance --access public

Pruebas con MCP Inspector

Compila primero:

pnpm build

Inicia el inspector:

RAWTREE_API_KEY=rt_xxxxxxxxx pnpm inspector

En la interfaz del Inspector, elige stdio:

• Comando: node

• Argumentos: dist/index.js

• Entorno: RAWTREE_API_KEY=rt_xxxxxxxxx

Referencias de RawTree

• Documentación de RawTree

• llms.txt

• Especificación OpenAPI