Ligar o Lexbase a um CLI (Claude Code e Gemini CLI)

O que é a ligação MCP

O MCP (Model Context Protocol) é a norma que permite a um assistente de IA chamar ferramentas externas durante a conversa. O Lexbase expõe um servidor MCP em https://api.lexbase.pt/mcp: ligado, o seu assistente passa a pesquisar legislação portuguesa consolidada e a citar o artigo — a resposta continua a ser do assistente; a lei passa a vir de nós.

Antes de começar: conta e chave

Precisa de duas coisas:

• 1.Uma conta Lexbase. É gratuita, sem cartão, e inclui 200 pesquisas por mês — pesquisas no navegador e pedidos MCP contam do mesmo saldo.
• 2.Uma chave de API, criada em lexbase.pt/mcp. As chaves são nomeadas, revogáveis e com o consumo à vista, por chave.

A chave segue em todos os pedidos no cabeçalho Authorization: Bearer <a-sua-chave>. Trate-a como trata uma palavra-passe: não a coloque em repositórios nem em ficheiros partilhados.

Claude Code

Um comando:

claude mcp add --transport http lexbase https://api.lexbase.pt/mcp \
  --header "Authorization: Bearer <a-sua-chave>"

Substitua <a-sua-chave> pela chave que criou. A partir daqui o servidor fica registado com o nome lexbase e o assistente chama as ferramentas quando a conversa precisa de legislação. Como o servidor declara todas as ferramentas como apenas de leitura, o Claude não lhe pede confirmação a cada chamada.

Gemini CLI

O mesmo servidor, o mesmo endpoint:

gemini mcp add --transport http \
  --header "Authorization: Bearer <a-sua-chave>" \
  lexbase https://api.lexbase.pt/mcp

Nota técnica. O servidor está montado em dois caminhos: /mcp (aceita chaves estáticas e OAuth) e /mcp-key (apenas chaves estáticas, para clientes que abandonam a autenticação por chave quando vêem um desafio OAuth). Os comandos deste guia usam /mcp, que funciona com a sua chave. Para confirmar que o serviço está de pé, GET https://api.lexbase.pt/health responde sem autenticação.

O que o assistente passa a conseguir

Ligado, o assistente ganha oito ferramentas — todas apenas de leitura — sobre um corpus de 70 491 diplomas consolidados (638 364 blocos de texto). Cada retorno com conteúdo traz a citação (diploma + artigo) e a informação de vigência: o assistente não tem maneira de citar sem a âncora verificável.

As duas que fazem o trabalho principal:

• §`search_legislation(query, k, tipo, tema_tag_id, in_force_only)` — pesquisa semântica e lexical na legislação consolidada. Devolve os artigos mais relevantes; cada resultado traz a citação verificável, o texto do artigo e o trecho que justificou a correspondência. Por omissão devolve 8 resultados e considera apenas redacções em vigor (in_force_only=true). Quando não há correspondência, devolve total=0 com um campo note a explicar porquê — um resultado vazio é uma resposta honesta, não um convite a inventar.
• §`get_article(diploma_id, article, with_amendments)` — resolve um artigo pelo número dentro de um diploma. Aceita «1425», «1425.º» ou «Artigo 1425.º».

As restantes:

• §`get_diploma(diploma_id, include)` — metadados (meta), índice de artigos (tree) ou texto integral (full).
• §`get_fragment(fragment_id, with_amendments, with_context)` — lê um artigo pelo seu id, com citação, texto e datas de vigência; opcionalmente com o histórico de alterações e os artigos vizinhos.
• §`get_amendments(diploma_id | fragment_id)` — histórico de alterações de um diploma ou de um artigo específico; cada entrada identifica o diploma alterador e a data de entrada em vigor.
• §`list_themes()` — os temas jurídicos disponíveis, com contagem de diplomas, utilizáveis no filtro tema_tag_id da pesquisa.
• §`search(query)` e `fetch(id)` — versões simplificadas, com nomes e esquemas fixados pela OpenAI, para clientes que só chamam estes dois nomes (é o caso do ChatGPT). O search devolve id, citação, excerto e ligação permanente; o fetch devolve o texto integral com metadados de vigência. As ligações abrem o diploma em lexbase.pt com o artigo destacado.

Na prática: pergunte «O meu cliente quer instalar um elevador no prédio. Que maioria precisa?» e o assistente pesquisa e responde com o artigo 1425.º do Código Civil — a redacção em vigor, a data, o histórico de alterações e a ligação ao Diário da República. A cota que ele cita é, carácter por carácter, a que copiaria do navegador.

Clientes ainda em testes

Este guia cobre o que funciona hoje. Mistral Le Chat, Claude (claude.ai e aplicação Desktop) e ChatGPT (Connectors) estão em testes finais — a ligação existe, mas ainda não dizemos que funciona. O Gemini (aplicação) está em construção.

Além dos dois CLIs deste guia, funcionam hoje o Google Antigravity e agentes próprios via API (OpenAI Responses, Vertex/ADK, Gemini API).

A regra é simples: não anunciamos integrações que ainda não funcionam. A tabela de estado em lexbase.pt é actualizada quando o estado muda, não quando o plano muda.

Revogar a chave

A chave é sua, pessoal e revogável a qualquer momento na sua conta. Como as chaves são nomeadas e o consumo é visível por chave, uma chave com consumo que não reconhece é fácil de identificar — revogue-a.

Uma chave revogada deixa de ser aceite. Para continuar a usar o Lexbase no CLI, crie uma chave nova em lexbase.pt/mcp e repita o comando de configuração com a chave nova. Se alguma vez expuser uma chave — num repositório, num registo, numa captura de ecrã — revogue primeiro, substitua depois.