Voltar para o blog
Engenharia

Converse com o seu PDF: um servidor MCP no Claude Code e no Claude Desktop

Ligamos o servidor MCP da série de RAG ao Claude Code e ao Claude Desktop. Funcionou nos três modos, e cada um chegou à resposta por um caminho diferente.

MCPClaudeRAGPython

Na parte 4 da série sobre RAG, o Relatório de Política Monetária do Banco Central virou um servidor MCP com duas ferramentas: search_report, que busca trechos, e view_page, que devolve a página como imagem. Lá, quem usava o servidor era um agente que nós mesmos escrevemos.

Aqui, o mesmo servidor vai para o Claude Code e para o Claude Desktop, sem escrever agente nenhum. Você pergunta numa conversa, o Claude busca no relatório, abre a página do gráfico e responde. O documento fica na sua máquina, e o servidor roda de graça.

Testamos os três jeitos: o Claude Code no terminal, a aba de código do Claude Desktop e a conversa normal do Desktop. Funcionou nos três, mas não do mesmo jeito. O servidor, que funcionava bem no nosso agente, quase não subiu a tempo. E, na conversa do Desktop, o Claude fez nove buscas antes de descobrir que podia abrir a página; depois de reescrever a descrição de uma ferramenta, fez uma.

O código é o mesmo da série, em salada-dados/blog, com uma mudança no mcp_server.py que explicamos abaixo.


O que você precisa

  • O Postgres com pgvector rodando no Docker e os trechos do relatório carregados pelo index_pg.py, como na parte 4.
  • O ambiente Python (venv) com as dependências do requirements.txt.
  • O Claude Code ou o Claude Desktop instalado e logado na sua conta.

Nenhuma chave de API. O uso entra no seu plano do Claude.

No Claude Code

Um comando registra o servidor:

claude mcp add --env DOC_LANG=pt --scope project --transport stdio relatorio-bc -- \
  "C:\Users\voce\.venvs\rag\Scripts\python.exe" "C:\caminho\para\rag-pdf-bcb\mcp_server.py"

Tudo depois do -- é o comando que inicia o servidor. Dois cuidados:

  • Caminhos absolutos, e o Python do venv. O Claude Code inicia o servidor como um processo separado, que não herda o venv ativo no seu terminal. Com python puro, ele pega o Python do sistema, sem as bibliotecas, e o servidor morre ao subir.
  • A ordem das opções importa. Na primeira tentativa, escrevemos --scope project --transport stdio --env DOC_LANG=pt relatorio-bc, e o comando respondeu: "Invalid environment variable format: relatorio-bc". Com --env logo antes do nome, ele lê o nome como mais uma variável. A documentação avisa; a gente só leu depois.

O --scope project grava a configuração num .mcp.json na pasta do projeto, que pode ir para o Git e servir para a equipe toda. Por isso mesmo, o Claude Code não confia nele de cara: o claude mcp list mostrou o servidor como "Pending approval", e é preciso aprová-lo uma vez numa sessão interativa. Um .mcp.json de um repositório alheio poderia rodar qualquer comando na sua máquina. Os outros escopos são local (só você, só este projeto, o padrão) e user (você, em todos os projetos).

Dentro de uma sessão, o comando /mcp mostra se o servidor conectou e quais ferramentas ele oferece.

Também dá para usar sem sessão interativa, liberando só as duas ferramentas do servidor:

claude -p "Entre EUA, China, Japão, área do euro e Reino Unido, qual economia teve o menor crescimento do PIB no segundo trimestre de 2026?" \
  --mcp-config .mcp.json \
  --allowedTools "mcp__relatorio-bc__search_report" "mcp__relatorio-bc__view_page"

O Claude fez quatro buscas, abriu a página 10, leu o Gráfico 1.1.4 e respondeu "Japão", com uma tabela de valores aproximados. Ainda distinguiu a página impressa do relatório (9) da página do PDF (10), e avisou que Japão e área do euro estavam perto demais para cravar a diferença só olhando as barras.

No Claude Desktop

O Desktop lê os servidores locais de um arquivo JSON. O caminho mais curto até ele é Configurações → Desenvolvedor → Editar configuração:

claude_desktop_config.json
{
  "mcpServers": {
    "relatorio-bc": {
      "command": "C:\\Users\\voce\\.venvs\\rag\\Scripts\\python.exe",
      "args": ["C:\\caminho\\para\\rag-pdf-bcb\\mcp_server.py"],
      "env": { "DOC_LANG": "pt" }
    }
  }
}

No Windows, cada barra do caminho vira barra dupla, porque é JSON. Depois de salvar, feche o Desktop por completo, inclusive pelo ícone perto do relógio, e abra de novo. Se der certo, o servidor aparece em execução na mesma tela:

Tela Desenvolvedor do Claude Desktop, com o servidor relatorio-bc marcado como Em execução e os caminhos do comando borrados

Se não aparecer, o botão "Ver registros" abre o log do servidor, com tudo o que ele escreveu no stderr.

O Desktop tem dois jeitos de conversar, e o servidor funciona nos dois, com comportamentos diferentes.

Na aba de código

A aba com o ícone </> é o Claude Code dentro do Desktop. O servidor configurado no JSON apareceu ali sem nenhum claude mcp add. Não houve pedido de aprovação: apareceu um aviso de que o modo automático é o padrão de permissão do Claude Code, em que o Claude avalia cada chamada e executa sozinho as de menor risco.

O Claude carregou as duas ferramentas, buscou e abriu a página. A imagem aparece no meio da conversa:

Chamada view_page na página 10 dentro da aba de código do Claude Desktop, com a miniatura da página e a resposta começando abaixo; o caminho do arquivo salvo está borrado

Na conversa normal

Na conversa normal, o servidor vira um conector, com chave de liga e desliga no menu da caixa de mensagem:

Menu de conectores do Claude Desktop com o relatorio-bc ligado; os outros conectores estão borrados

Aqui, cada ferramenta pede permissão antes do primeiro uso:

Pedido de aprovação: Claude quer usar Search report de relatorio-bc, com as opções Negar, Sempre permitir e Permitir uma vez

Marcamos as duas ferramentas como somente leitura no servidor (read_only_hint), e o pedido apareceu do mesmo jeito. No Claude Code, essa anotação só faz o Claude rodar chamadas de leitura em paralelo; ela não dispensa a sua aprovação. Faz sentido: quem garante que a ferramenta só lê é o servidor, e o servidor pode mentir.

A resposta veio certa, com o mesmo cuidado de separar os números que o texto do relatório cita em bases diferentes:

Resposta no Claude Desktop: Japão teve o menor crescimento, com uma tabela de valores aproximados lidos do Gráfico 1.1.4 e uma lista dos números do texto em bases diferentes

Mas o caminho até ela foi longo. Veja o que veio antes.

Nove buscas antes de abrir a página

Lista de chamadas no Claude Desktop: duas buscas de ferramentas e nove buscas no relatório antes de uma chamada view_page

Na conversa normal, o Claude fez 9 buscas no relatório antes de abrir a página do gráfico. Ele procurou o PIB de cada país no texto, um por um, e só depois procurou outra ferramenta e encontrou o view_page.

O motivo está numa linha da lista: "Searched available tools". O Claude não recebe todas as ferramentas de uma vez. Ele procura as que precisa, por palavras, e só então elas entram na conversa. A primeira procura foi por "Banco Central relatório política monetária". Pelo que veio depois, ela trouxe só o search_report, cuja descrição fala do Monetary Policy Report do Banco Central do Brasil. A descrição do view_page fala em devolver uma página "do relatório" como imagem, sem citar Banco Central nem política monetária. Ele ficou de fora até o Claude procurar de novo, já perto do fim.

Na aba de código, o Claude carregou as duas ferramentas de uma vez e abriu a página na segunda chamada. Mesma pergunta, mesmo servidor, caminhos bem diferentes.

Na parte 4, mostramos que a descrição da ferramenta muda o jeito como o modelo a usa. Aqui, ela também decide se o modelo encontra a ferramenta.

Então corrigimos as duas coisas que o Claude lê antes de usar o servidor. A descrição do view_page passou a citar o relatório pelo nome, em inglês e em português, e a dizer que a ferramenta anda junto com a busca. E o campo instructions do servidor, que antes dizia só "Read-only access to one PDF report", passou a explicar como as duas ferramentas se combinam:

mcp_server.py
"view_page": (
    f"Return one page (1 to {len(doc)}) of the Banco Central do Brasil's Monetary Policy Report "
    "(Relatório de Política Monetária, September 2026) as an image. Use it to read a chart "
    "(gráfico) or a table (tabela) on a page that search_report found: the values of charts "
    "are only in the image. Load it together with search_report."
),
 
INSTRUCTIONS = (
    "Read-only access to the Banco Central do Brasil's Monetary Policy Report (Relatório de Política "
    "Monetária, September 2026). Two tools work together: search_report finds the pages, and view_page "
    "shows a page as an image. Chart values exist only in the image, so after a search that points to "
    "a chart or a table, call view_page on that page."
)

Reiniciamos o Desktop e fizemos a mesma pergunta numa conversa nova:

Lista de chamadas depois da correção: uma busca de ferramentas que carrega as duas ferramentas do relatorio-bc, uma busca no relatório e a chamada view_page com a página 10

A procura por ferramentas trouxe as duas de uma vez ("Loaded 2 relatorio-bc tools"). O Claude fez uma busca, abriu a página 10 e respondeu com os mesmos valores de antes. De 9 buscas para 1.

É uma execução antes e uma depois, não uma medição: o modelo não responde sempre igual, e a própria procura por ferramentas usou outras palavras na segunda vez. Mas a causa é clara e a correção custou dois parágrafos de texto. Se o seu servidor tem mais de uma ferramenta, escreva cada descrição pensando também em quem vai procurá-la, e não só em quem vai usá-la.

O que a IA de coding não vai te avisar

O servidor demorava mais para subir do que o cliente esperava

Medimos o tempo entre iniciar o servidor e ele listar as ferramentas: 28 a 40 segundos. Quase tudo era a importação do PyTorch e o carregamento do modelo de embeddings, que o servidor fazia logo ao subir. O Claude Code espera um servidor por 30 segundos (dá para aumentar com a variável MCP_TIMEOUT). Nos nossos testes, a conexão coube, mas no limite: num computador mais lento, ou na primeira vez, com o modelo ainda sendo baixado, não caberia.

No nosso agente da parte 4, isso nunca apareceu, porque o código esperava o tempo que fosse. A correção foi carregar o modelo na primeira busca, e não na inicialização:

mcp_server.py
@cache
def embedder():
    """Loaded on the first search, not at startup: importing PyTorch and loading the model takes
    30 s or more, and MCP clients give a server about that long to start (30 s in Claude Code)."""
    from sentence_transformers import SentenceTransformer
    return SentenceTransformer("intfloat/multilingual-e5-small")

O servidor passou a subir em 2 a 3 segundos. O custo foi para a primeira busca, que agora leva de 18 a 33 segundos; as seguintes saem na hora.

A leitura do gráfico é aproximada, e varia

Fizemos a mesma pergunta três vezes. O Japão saiu como o menor em todas. Mas a área do euro foi lida como cerca de 0,7% no Claude Code do terminal e cerca de 1,2% nas duas conversas do Desktop. Só o número da China (4,3%) está escrito no texto; os outros vêm das barras.

O Claude avisou isso nas três respostas, o que é bom. Mas, se a decisão depende da segunda casa decimal, um gráfico não é fonte. Procure a tabela ou a série original.

Vale de novo, porque no Desktop é mais difícil de descobrir: no transporte stdio, a saída padrão é o canal do protocolo. Um print() de depuração no servidor vira lixo no meio da conversa. Log vai para o stderr, e o Desktop mostra esse log no botão "Ver registros".

Um assistente de código é um leitor de PDF caro

No modo -p, o Claude Code informa quanto a sessão custaria em preço de API. A pergunta do Japão, no modelo padrão, deu US$ 0,70. Com o Sonnet, uma pergunta de tabela deu US$ 0,45. O nosso agente enxuto da parte 4 gastava US$ 0,024.

A diferença não está no PDF. O Claude Code leva para cada chamada o prompt de sistema dele, dezenas de ferramentas de programação e o histórico inteiro, e isso somou mais de 250 mil tokens lidos do cache numa única pergunta. Numa assinatura, você não paga por chamada, mas isso consome o seu limite de uso. Para consultar um documento de vez em quando, tudo bem. Para centenas de perguntas por dia, um agente próprio sai muito mais barato.

Quando usar cada um

  • Claude Desktop, conversa normal: o mais simples para consultar o documento no dia a dia. Pede aprovação por ferramenta, e você vê cada busca.
  • Claude Code ou a aba de código: útil quando a consulta faz parte de um trabalho maior, como escrever um relatório a partir do documento. O .mcp.json no projeto deixa a configuração pronta para a equipe.
  • Um agente próprio, como o da parte 4: quando o volume é alto, o custo precisa ser previsível ou a resposta vai para outro sistema.

Nos três casos, o documento e o banco ficam na sua máquina. O que sai é o que o modelo lê: os trechos e as páginas que ele pediu.

Próximos passos

Este servidor só funciona onde o Claude roda na sua máquina. O Claude no navegador e no celular aceita servidores MCP como conectores, mas eles precisam estar na internet, com HTTPS e autenticação. Levar este servidor para lá, com o custo e os riscos medidos, é o próximo post.