Metabase

Servidor MCP do Metabase

O Metabase inclui um servidor Model Context Protocol (MCP) integrado que permite que clientes de IA se conectem diretamente a uma instância do Metabase. Ele usa o https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http e se baseia na API de Agente do Metabase para expor ferramentas de busca, navegação, consulta, visualização e criação/atualização de conteúdo — tudo limitado às permissões do usuário conectado.

Endpoint

O servidor MCP está disponível em:

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

O caminho legado /api/mcp ainda funciona como um alias para clientes existentes, mas /api/metabase-mcp é a URL canônica a ser divulgada.

Conectando um cliente

Aponte qualquer cliente compatível com MCP para o endpoint /api/metabase-mcp. Por exemplo, com o Claude Code:

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

Para o Claude Desktop, crie um conector personalizado usando a mesma URL.

Para o Cursor, abra Configurações > MCP e adicione um novo servidor com o tipo definido como streamable-http e a URL:

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

Autenticação

Clientes MCP se autenticam via OAuth 2.0. O Metabase executa seu próprio servidor OAuth embutido — nenhum provedor externo é necessário.

O fluxo para uma primeira conexão:

1. O cliente descobre os endpoints OAuth do Metabase.
2. O cliente se registra no Metabase.
3. O usuário é redirecionado para o Metabase para fazer login e aprovar a conexão.
4. O cliente recebe um token de acesso limitado às permissões do usuário no Metabase.

Sessões baseadas em navegador (autenticação por cookie) também são suportadas e recebem escopos irrestritos.

Escopos

Os tokens de acesso são limitados para restringir quais ferramentas um cliente pode usar:

Escopo	Concede acesso a
agent:search	search
agent:resource:read	read_resource (sempre concedido a qualquer chamador autenticado; verificações de permissão por URI ocorrem dentro do despachante)
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 (também cobre "mover cartão para coleção" e arquivamento)
agent:question:execute	execute_question
agent:metric:create	create_metric
agent:metric:update	update_metric (também cobre "mover métrica para coleção" e arquivamento)
agent:dashboard:create	create_dashboard
agent:dashboard:update	update_dashboard (também cobre arquivamento)
agent:collection:create	create_collection

Padrões curinga (ex.: agent:*) correspondem a qualquer escopo com esse prefixo.

Os metadados do recurso protegido OAuth estão disponíveis em:

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

Por padrão, nossa tela de consentimento concede acesso a todos os escopos sem a oportunidade de personalizar.

Ferramentas disponíveis

O servidor MCP expõe estas ferramentas, geradas dinamicamente a partir dos metadados do endpoint da API de Agente:

Descoberta + leitura

Ferramenta	Descrição
search	Pesquisa tabelas, métricas, cartões, dashboards e coleções usando palavras-chave ou consultas em linguagem natural.
read_resource	Lê uma ou mais entidades do Metabase por URI metabase://. Cobre navegação em banco de dados/esquema/tabela/coleção/pergunta/dashboard/métrica/transformação. Até 5 URIs por chamada.

Construção e execução de consultas

Ferramenta	Descrição
construct_query	Constrói uma consulta em uma tabela ou métrica. Aceita a prompt original do usuário quando disponível. Retorna um query_handle opaco para uso com execute_query ou visualize_query.
construct_native_query	Constrói uma consulta nativa (SQL bruto) para um banco de dados. Retorna um query_handle opaco para alimentar create_question e salvá-lo. Não executa o SQL; manipuladores nativos são rejeitados por execute_query/query (use execute_sql para executar SQL bruto).
query	Consulta uma tabela ou métrica diretamente. Suporta paginação via tokens de continuação.
execute_query	Executa uma consulta previamente construída e retorna resultados com metadados de coluna.
execute_sql	Executa uma consulta SQL bruta em um banco de dados. Requer que o usuário tenha permissão de consulta nativa no banco de dados alvo. Pode ser desabilitado em toda a instância via configuração mcp-execute-sql-enabled.
execute_question	Executa uma pergunta salva por id e retorna suas linhas + metadados de coluna. Executa sob as permissões do chamador. Perguntas parametrizadas não são suportadas (retorna um erro).

Escrita

Ferramenta	Descrição
create_metric	Salva uma consulta como uma métrica reutilizável. Aceita um query_handle de construct_query. A consulta precisa de uma agregação e no máximo um agrupamento por data.
update_metric	Atualiza uma métrica salva. Semântica de patch. Definir collection_id a move; definir archived: true a arquiva — uma exclusão suave reversível, usada quando solicitado a excluir uma métrica. Um query substituto ainda deve ser uma métrica válida.
create_question	Salva uma consulta como uma pergunta nomeada (cartão). Aceita um query_handle de construct_query (MBQL) ou construct_native_query (SQL nativo). Salvar nativo requer permissão de consulta nativa no BD.
update_question	Atualiza uma pergunta salva. Semântica de patch. Definir collection_id move o cartão. Definir archived: true o arquiva — uma exclusão suave reversível, usada quando solicitado a excluir uma pergunta. Substituir a consulta aceita um manipulador construct_query ou construct_native_query.
create_dashboard	Cria um novo dashboard, opcionalmente preenchido com perguntas salvas (posicionadas automaticamente na grade).
update_dashboard	Atualiza os metadados de um dashboard (nome, descrição, coleção, arquivado — uma exclusão suave reversível, usada quando solicitado a excluir um dashboard).
create_collection	Cria uma nova coleção. Opcionalmente aninhada sob um parent_collection_id.

Os resultados da consulta são limitados a 200 linhas por solicitação. Quando mais linhas estão disponíveis, a resposta inclui um continuation_token que pode ser passado de volta para buscar a próxima página.

As respostas de lista read_resource são limitadas a 25 itens com sinais truncated / total; aprofunde-se em URIs específicas para ver mais ou refine via search.

Recursos

O servidor expõe recursos MCP para que os clientes possam buscar conteúdo suplementar por URI sem inflar as descrições das ferramentas.

URI do recurso	Descrição
metabase://docs/construct-query.md	Sintaxe do programa para construct_query e query: fontes, operações, formas de operador, exemplos práticos, armadilhas.

A ferramenta read_resource (acima) usa um esquema de URI separado para navegar pelas entidades do Metabase (metabase://question/{id}, metabase://database/{id}/tables, etc.). Os dois namespaces de URI são independentes: metabase://docs/... é para conteúdo de referência estático obtido via resources/read MCP, enquanto metabase://table/... e similares são URIs de entidade passadas para a ferramenta read_resource.

Métodos JSON-RPC suportados

Método	Descrição
initialize	Inicializa a conexão MCP. Retorna as capacidades do servidor e um ID de sessão.
notifications/initialized	Notificação do cliente de que a inicialização está completa.
tools/list	Lista as ferramentas disponíveis (filtradas pelos escopos do token).
tools/call	Chama uma ferramenta com argumentos.
resources/list	Lista os recursos disponíveis (filtrados pelos escopos do token).
resources/read	Lê um recurso por URI. Requer uma sessão inicializada.
ping	Ping de keepalive.

As solicitações podem ser enviadas individualmente ou como um lote JSON-RPC. O servidor responde com JSON ou SSE dependendo do cabeçalho Accept.

Arquitetura

A implementação reside nestes arquivos:

• api.clj - O manipulador HTTP. Analisa solicitações JSON-RPC, valida cabeçalhos de autenticação e sessão, impõe verificações de origem (proteção contra rebinding de DNS) e despacha para o método apropriado. Suporta formatos de resposta JSON e SSE.

• tools.clj - Despacho de ferramentas e geração de manifesto. Constrói a lista de ferramentas a partir dos metadados do endpoint da API de Agente, verifica escopos e roteia chamadas de ferramentas através de solicitações sintéticas da API de Agente.

• resources.clj - Registro e manipuladores de recursos MCP. Mantém recursos de documentação (como a referência construct_query) indexados por URI, com controle de acesso baseado em escopo em resources/list e resources/read.

• scope.clj - Lógica de correspondência de escopo. Suporta correspondências exatas, padrões curinga e o sentinela ::unrestricted para autenticação baseada em sessão.

Fluxo da requisição

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

Leitura adicional

• Documentação do usuário do MCP
• Código-fonte da API do Agent
• Especificação do Model Context Protocol