Metabase

Servidor MCP de Metabase

Metabase incluye un servidor Model Context Protocol (MCP) integrado que permite a los clientes de IA conectarse directamente a una instancia de Metabase. Utiliza el https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http y se basa en la API de Agente de Metabase para exponer herramientas de búsqueda, navegación, consulta, visualización y creación/actualización de contenido, todo limitado a los permisos del usuario que se conecta.

Endpoint

El servidor MCP está disponible en:

https://{your-metabase.example.com}/api/metabase-mcp

La ruta heredada /api/mcp sigue funcionando como alias para clientes existentes, pero /api/metabase-mcp es la URL canónica que se debe publicitar.

Conexión de un cliente

Dirige cualquier cliente compatible con MCP al endpoint /api/metabase-mcp. Por ejemplo, con Claude Code:

claude mcp add metabase https://{your-metabase.example.com}/api/metabase-mcp --transport streamable-http

Para Claude Desktop, crea un conector personalizado usando la misma URL.

Para Cursor, abre Configuración > MCP y añade un nuevo servidor con el tipo establecido en streamable-http y la URL:

https://{your-metabase.example.com}/api/metabase-mcp

Autenticación

Los clientes MCP se autentican mediante OAuth 2.0. Metabase ejecuta su propio servidor OAuth integrado, sin necesidad de un proveedor externo.

El flujo para una primera conexión:

1. El cliente descubre los endpoints OAuth de Metabase.
2. El cliente se registra en Metabase.
3. Se redirige al usuario a Metabase para que inicie sesión y apruebe la conexión.
4. El cliente recibe un token de acceso limitado a los permisos del usuario en Metabase.

Las sesiones basadas en navegador (autenticación por cookie) también son compatibles y reciben ámbitos sin restricciones.

Ámbitos

Los tokens de acceso están limitados para restringir qué herramientas puede usar un cliente:

Ámbito	Concede acceso a
agent:search	search
agent:resource:read	read_resource (siempre concedido a cualquier llamante autenticado; las comprobaciones de permisos por URI ocurren dentro del despachador)
agent:query:construct	construct_query
agent:query	query
agent:query:execute	execute_query
agent:sql:construct	construct_native_query
agent:sql:execute	execute_sql
agent:question:create	create_question
agent:question:update	update_question (también cubre "mover tarjeta a colección" y archivado)
agent:question:execute	execute_question
agent:metric:create	create_metric
agent:metric:update	update_metric (también cubre "mover métrica a colección" y archivado)
agent:dashboard:create	create_dashboard
agent:dashboard:update	update_dashboard (también cubre archivado)
agent:collection:create	create_collection

Los patrones comodín (p. ej., agent:*) coinciden con cualquier ámbito que tenga ese prefijo.

Los metadatos del recurso protegido OAuth están disponibles en:

/.well-known/oauth-protected-resource/api/metabase-mcp

Por defecto, nuestra pantalla de consentimiento concede acceso a todos los ámbitos sin posibilidad de personalización.

Herramientas disponibles

El servidor MCP expone estas herramientas, generadas dinámicamente a partir de los metadatos del endpoint de la API de Agente:

Descubrimiento + lectura

Herramienta	Descripción
search	Busca tablas, métricas, tarjetas, paneles y colecciones usando palabras clave o consultas en lenguaje natural.
read_resource	Lee una o más entidades de Metabase por URI metabase://. Cubre la navegación por base de datos/esquema/tabla/colección/pregunta/panel/métrica/transformación. Hasta 5 URIs por llamada.

Construcción y ejecución de consultas

Herramienta	Descripción
construct_query	Construye una consulta sobre una tabla o métrica. Acepta la prompt original del usuario cuando está disponible. Devuelve un query_handle opaco para usar con execute_query o visualize_query.
construct_native_query	Construye una consulta nativa (SQL en bruto) para una base de datos. Devuelve un query_handle opaco para alimentar create_question y guardarlo. No ejecuta el SQL; los manejadores nativos son rechazados por execute_query/query (usa execute_sql para ejecutar SQL en bruto).
query	Consulta una tabla o métrica directamente. Soporta paginación mediante tokens de continuación.
execute_query	Ejecuta una consulta previamente construida y devuelve resultados con metadatos de columna.
execute_sql	Ejecuta una consulta SQL en bruto contra una base de datos. Requiere que el usuario tenga permiso de consulta nativa en la base de datos objetivo. Se puede deshabilitar para toda la instancia mediante la configuración mcp-execute-sql-enabled.
execute_question	Ejecuta una pregunta guardada por id y devuelve sus filas + metadatos de columna. Se ejecuta bajo los permisos del llamante. Las preguntas parametrizadas no son compatibles (devuelve un error).

Escritura

Herramienta	Descripción
create_metric	Guarda una consulta como una métrica reutilizable. Acepta un query_handle de construct_query. La consulta necesita una agregación y como máximo una agrupación por fecha.
update_metric	Actualiza una métrica guardada. Semántica de parcheo. Establecer collection_id la mueve; establecer archived: true la archiva — un borrado suave reversible, usado cuando se pide eliminar una métrica. Un query de reemplazo debe seguir siendo una métrica válida.
create_question	Guarda una consulta como una pregunta con nombre (tarjeta). Acepta un query_handle de construct_query (MBQL) o construct_native_query (SQL nativo). Guardar nativo requiere permiso de consulta nativa en la BD.
update_question	Actualiza una pregunta guardada. Semántica de parcheo. Establecer collection_id mueve la tarjeta. Establecer archived: true la archiva — un borrado suave reversible, usado cuando se pide eliminar una pregunta. Reemplazar la consulta acepta un manejador construct_query o construct_native_query.
create_dashboard	Crea un nuevo panel, opcionalmente poblado con preguntas guardadas (posicionadas automáticamente en la cuadrícula).
update_dashboard	Actualiza los metadatos de un panel (nombre, descripción, colección, archivado — un borrado suave reversible, usado cuando se pide eliminar un panel).
create_collection	Crea una nueva colección. Opcionalmente anidada bajo un parent_collection_id.

Los resultados de las consultas están limitados a 200 filas por solicitud. Cuando hay más filas disponibles, la respuesta incluye un continuation_token que se puede pasar de vuelta para obtener la página siguiente.

Las respuestas de lista de read_resource tienen un límite de 25 elementos con señales truncated / total; profundiza en URIs específicas para ver más, o refina mediante search.

Recursos

El servidor expone recursos MCP para que los clientes puedan obtener contenido complementario por URI sin inflar las descripciones de las herramientas.

URI de recurso	Descripción
metabase://docs/construct-query.md	Sintaxis de programa para construct_query y query: fuentes, operaciones, formas de operador, ejemplos prácticos, trampas.

La herramienta read_resource (arriba) usa un esquema de URI separado para navegar por las entidades de Metabase (metabase://question/{id}, metabase://database/{id}/tables, etc.). Los dos espacios de nombres de URI son independientes: metabase://docs/... es para contenido de referencia estático obtenido a través de resources/read de MCP, mientras que metabase://table/... y similares son URIs de entidad pasadas a la herramienta read_resource.

Métodos JSON-RPC soportados

Método	Descripción
initialize	Inicializa la conexión MCP. Devuelve las capacidades del servidor y un ID de sesión.
notifications/initialized	Notificación del cliente de que la inicialización está completa.
tools/list	Lista las herramientas disponibles (filtradas por los ámbitos del token).
tools/call	Llama a una herramienta con argumentos.
resources/list	Lista los recursos disponibles (filtrados por los ámbitos del token).
resources/read	Lee un recurso por URI. Requiere una sesión inicializada.
ping	Ping de mantenimiento de conexión.

Las solicitudes se pueden enviar individualmente o como un lote JSON-RPC. El servidor responde con JSON o SSE dependiendo de la cabecera Accept.

Arquitectura

La implementación reside en estos archivos:

• api.clj - El manejador HTTP. Analiza las solicitudes JSON-RPC, valida la autenticación y las cabeceras de sesión, aplica comprobaciones de origen (protección contra reenlace DNS) y despacha al método apropiado. Soporta formatos de respuesta JSON y SSE.

• tools.clj - Despacho de herramientas y generación de manifiesto. Construye la lista de herramientas a partir de los metadatos del endpoint de la API de Agente, comprueba los ámbitos y enruta las llamadas a herramientas a través de solicitudes sintéticas a la API de Agente.

• resources.clj - Registro de recursos MCP y manejadores. Contiene recursos de documentación (como la referencia construct_query) indexados por URI, con control de acceso basado en ámbitos en resources/list y resources/read.

• scope.clj - Lógica de coincidencia de alcances. Admite coincidencias exactas, patrones comodín y el centinela ::unrestricted para autenticación basada en sesión.

Flujo de solicitud

MCP client
  -> POST /api/metabase-mcp (JSON-RPC)
  -> Origin + session validation
  -> Auth: OAuth bearer token or browser session
  -> Scope check against requested tool
  -> Synthetic request to Agent API endpoint
  -> Response materialized as MCP content
  -> JSON or SSE back to client

Lectura adicional

• Documentación de usuario de MCP
• Código fuente de la API del Agente
• Especificación del Protocolo de Contexto de Modelo