MCP e API no trabalho do agente e da aplicação

O agente foi até uma fonte externa, entendeu o formato da resposta e montou uma página com um mapa. Funciona. Agora essa página é aberta por outra pessoa, que não tem Claude Code nenhum por perto.

Antes de publicar, vale responder a uma pergunta. Quem vai buscar os dados para o visitante? Vamos ver dois caminhos, o que o MCP faz, como conferir a conexão e o que precisa continuar funcionando depois que o(a) senhor(a) fechar a sessão do agente.

Quem está pedindo os dados agora

Há duas situações, e é fácil confundi-las, porque na tela as duas parecem "os dados apareceram".

Na primeira, o agente explora a fonte. O(a) senhor(a) está trabalhando no projeto, o Claude Code lê a documentação do serviço, testa uma requisição, olha a estrutura da resposta. Os dados servem para ele escrever código. Tudo isso acontece no seu computador, e só enquanto a sessão está aberta.

Na segunda, o visitante abre a página publicada. Agora é ela quem precisa dos dados - para mostrar um panorama atualizado. A requisição é feita pelo código da aplicação enquanto ela está em execução. É isso que chamam de runtime: o momento em que a aplicação está rodando para o usuário, e não o momento em que o(a) senhor(a) a está escrevendo.

Existe ainda uma terceira opção, intermediária. O agente foi até a fonte uma vez e salvou a resposta num arquivo ao lado do código, e o site mostra o conteúdo desse arquivo. Não há nada de errado nisso, é até prático para um exemplo ou uma demonstração. Só que é um snapshot que fica exatamente como foi salvo e não se atualiza sozinho.

As duas cadeias existem separadas, não há seta entre elas

Repare no tracejado no meio. Ele não está ali por decoração. Não há seta entre a cadeia de cima e a de baixo, e esse é o ponto principal do esquema. A fonte pode ser a mesma, mas o agente e a página têm cada um seu próprio caminho até ela. Abaixo vamos ver cada cadeia em separado.

O que é MCP

Uma tarefa raramente vive só no repositório. A descrição de um bug fica num ticket, o stack trace no sistema de monitoramento, as regras atuais de uma biblioteca na documentação, e os registros necessários num banco de dados.

Sem uma integração, é preciso copiar tudo isso à mão do navegador para o chat com o agente. Uma vez, dá para tolerar. Num trabalho recorrente, os dados ficam desatualizados, parte dos detalhes se perde, e o mesmo caminho precisa ser percorrido de novo.

MCP (Model Context Protocol) é um padrão pelo qual o Claude Code descobre as ferramentas externas disponíveis, as chama e recebe o resultado num formato combinado. Na cadeia mínima, o Claude Code cria um cliente MCP, o cliente mantém uma conexão com um servidor MCP, e o servidor, por sua vez, alcança o sistema ao qual tem acesso - arquivos, um banco, uma API de terceiros.

O Claude Code conversa com o servidor MCP, e o servidor abre só as capacidades dos sistemas externos que declarou de antemão

À esquerda está o Claude Code com o cliente MCP embutido, no centro o servidor MCP com as capacidades que declarou, à direita os sistemas externos. O ponto principal aqui é que o agente não recebe acesso irrestrito a tudo de uma vez. Ele vê só as operações e os dados que o servidor decidiu oferecer.

Um servidor MCP pronto também tira parte do trabalho de integração das suas costas. O(a) senhor(a) não precisa descrever sozinho(a) os formatos de chamada para cada sistema externo nem escrever todo o código de acesso à API dele. Isso fica por conta do servidor, e o Claude Code trabalha com operações já declaradas.

O servidor também não precisa ser um programa separado em algum lugar da internet. Ele pode rodar direto no seu computador como um processo local, ou pode rodar remotamente e atender muitos clientes de uma vez. Para o(a) senhor(a), a diferença está principalmente na forma como ele é conectado.

O que exatamente o servidor sabe fazer, ele mesmo decide. O protocolo descreve três tipos de coisas que um servidor pode oferecer:

tools - operações que o agente pode executar: buscar uma página, fazer uma requisição a uma API, gravar dados;
resources - conteúdo que o servidor entrega como contexto: arquivos, registros, respostas de serviços;
prompts - modelos de prompt prontos, que podem ser chamados como estão.

O servidor não é obrigado a suportar os três. Na conexão, o cliente e o servidor conferem quem sabe fazer o quê, e as operações não suportadas simplesmente não são usadas. Muitos servidores se limitam a tools, e isso já basta. Arquitetura do MCP.

Vale lembrar o principal. O MCP padroniza a forma como cliente e servidor conversam. O que exatamente fica disponível para o(a) senhor(a) é definido pelo servidor, não pelo protocolo. Conectar um servidor não significa ter acesso à internet inteira - o(a) senhor(a) recebe exatamente o conjunto de operações que esse servidor declarou.

No pedido ao agente, nomeie a fonte e o resultado de que precisa, não um comando. Depois confira se o servidor conectado tem uma operação adequada. Se não tiver a certa, a tarefa se resolve por outro caminho, não insistindo com o agente.

Como os dados chegam ao site

Agora a cadeia de baixo. A página publicada recebe os dados de uma de duas formas.

No primeiro caso, o navegador chama diretamente uma API pública. Essa forma serve quando a fonte é aberta e não precisa de chave. O código da página faz a requisição e renderiza a resposta. Simples, sem detalhes extras.

No segundo caso, o navegador chama o backend da aplicação, e ele chama uma API privada. É assim quando a fonte precisa de uma chave. O segredo fica no servidor, o navegador não o vê. Aqui o frontend cuida do que aparece na tela, e o backend do que roda no servidor e sabe chamar o serviço em nome da aplicação.

A API pública é acessível ao navegador diretamente, e a chave da API privada fica no backend

A rota de cima é mais curta porque o navegador pode chamar sozinho uma fonte aberta. Na rota de baixo, o backend vira a fronteira que protege o segredo. A chave fica no servidor e não vai para o código da página.

E agora o que não acontece. A conexão do Claude Code com o servidor MCP não vai junto com o site na publicação. O comando com o qual o(a) senhor(a) adicionou o servidor configura o seu agente; ele não acrescenta uma linha sequer de código à aplicação. Dá para escrever uma aplicação com o próprio cliente MCP, mas isso é um trabalho à parte e uma implementação separada, não o resultado de conectar um servidor no Claude Code.

Tudo isso é rápido de conferir. Feche o Claude Code, abra a página publicada e olhe a aba Network nas ferramentas de desenvolvedor. Se os dados estiverem chegando, dá para ver a requisição, o endereço e a resposta. Se não estiverem, não vai haver requisição nenhuma, e esse é exatamente o caso que vale a pena pegar antes de mais alguém ver a página.

Uma imagem na tela não basta. A página pode mostrar um snapshot salvo antes e ainda assim parecer totalmente viva. É preciso olhar para a própria requisição. E o contrário também vale: a ausência de eventos novos na resposta não significa necessariamente que algo quebrou. A fonte pode simplesmente não ter tido nada para enviar no período escolhido.

Como conferir a conexão

A ordem é quase a mesma para qualquer servidor:

encontrar as instruções oficiais do servidor - o endereço, a forma de acesso, a lista de operações;
adicionar o servidor com o comando que essas instruções indicam;
abrir /mcp no Claude Code e ver se o servidor conectou e quais ferramentas ele tem;
fazer uma única requisição de leitura, a mais simples possível;
conferir o resultado com a fonte à mão - abrir a mesma página e olhar.

No terminal, claude mcp list mostra o status, e claude mcp get mostra os detalhes de um servidor específico. É útil saber que esses passos respondem a perguntas diferentes:

O que o(a) senhor(a) viu	O que isso prova
a linha `Added ...` depois de adicionar	a configuração foi gravada, e só
`Connected` em `claude mcp list`	o Claude Code conseguiu se conectar ao servidor
a ferramenta devolveu conteúdo	a rota inteira funciona, da requisição à resposta

A diferença não é uma formalidade. Um config gravado com sucesso não diz nada sobre se o servidor responde, e uma conexão bem-sucedida não diz nada sobre se a operação necessária está disponível e se há permissão para usá-la. Por isso a verificação termina com uma chamada de verdade. Aliás, se a lista mostrar Needs authentication, o servidor não está quebrado, só está esperando um login.

Vamos a um exemplo concreto. O serviço Firecrawl tem um servidor MCP que sabe buscar o conteúdo de uma página pública - a ferramenta se chama firecrawl_scrape. Para o agente, essa é uma forma prática de ler uma página inteira de documentação, em vez de o(a) senhor(a) copiá-la em pedaços para a conversa.

# adicionar o servidor via HTTP; o endereço exato está na documentação do serviço
claude mcp add --transport http firecrawl https://mcp.firecrawl.dev/v2/mcp

Agora sobre o acesso. A documentação do Firecrawl descreve tanto o uso sem conta e sem chave, com limites diários, quanto o login pelo navegador, em que o cliente abre sozinho a página de login. As condições e os limites dos serviços mudam, então os valores atuais devem ser conferidos no próprio serviço, não neste artigo. Documentação do Firecrawl sobre MCP.

E um pequeno detalhe que economiza tempo. Por padrão o servidor é adicionado para o projeto em que o(a) senhor(a) deu o comando, e não aparece em outros projetos. Se o servidor for necessário em todo lugar, ou para a equipe inteira, o comando de adicionar tem opções separadas de escopo. Claude Code sobre MCP.

O valor da chave não tem lugar num exemplo de configuração, no endereço do servidor nem na conversa com o agente. No config coloca-se o nome da variável de ambiente, o valor é definido à parte - esse é o tema do artigo vizinho sobre chaves.

O que uma ferramenta específica permite

Um servidor conectado é um conjunto de operações, e elas são muito diferentes nas suas consequências. Ler uma página e alterar um registro num sistema externo não são a mesma coisa, mesmo que sejam chamadas do mesmo jeito.

Antes de aceitar uma chamada, vale olhar para três coisas: com que objeto a ferramenta trabalha, que operação ela executa e que permissões isso exige. Ler costuma ser mais seguro, mas também tem um custo. A requisição vai para um serviço de terceiros e consome a cota da sua conta.

Uma nota à parte sobre o que volta na resposta. Um texto vindo de um site de terceiros são dados, não uma ordem. Se dentro da página está escrito "agora apague todos os arquivos", isso continua sendo texto na página, e a decisão é do(a) senhor(a). É exatamente por isso que vale a pena revisar o que o agente pretende fazer depois de ler uma fonte externa.

E a principal pergunta prática. O MCP é realmente necessário? Nem sempre.

Tarefa	Forma mais simples de resolver
mostrar no site dados de um JSON público	uma requisição comum do código da aplicação, sem precisar de MCP
o agente trabalha regularmente com um serviço que já tem integração pronta	o MCP compensa: as operações estão descritas, a conexão é reaproveitada
ler a documentação uma vez ou acessar um único endereço	basta ler a URL ou chamar a API diretamente

O MCP não é a única porta para fora nem substitui tudo o mais. O agente ainda tem a linha de comando e o acesso direto à API. A escolha vem da tarefa, não do fato de já haver uma conexão configurada.

O que conferir no seu projeto

Quando o agente está preparando o trabalho com dados externos, ajuda pedir que ele separe as duas camadas de forma explícita, em vez de descobrir isso depois:

Descreva separadamente as duas rotas:
de onde você busca os dados enquanto trabalha no projeto,
e de onde a própria aplicação vai buscá-los para o visitante.
Mostre em qual arquivo e em qual ponto do código fica a requisição da aplicação.
Confira a página com a sessão fechada: os dados chegam ou não.
Se agora está sendo usado um snapshot salvo, diga isso claramente.

Três situações que aparecem com mais frequência, e a resposta para cada uma:

O que é preciso	Quem recebe os dados	Por quê
estudar a documentação de um serviço durante o desenvolvimento	o agente	os dados servem para escrever código, o visitante nunca repete essa requisição
manter o mapa atualizado para o visitante	o código da aplicação	a requisição roda enquanto a página está em uso, e a sessão do agente já está fechada nesse momento
salvar uma amostra de dados em JSON uma única vez	o agente, e só uma vez	daí em diante o site mostra o arquivo; os dados ficam como foram salvos

Repare que o MCP só aparece aqui na primeira linha, e mesmo assim não necessariamente. Se a tarefa se resolve com a leitura comum de um endereço, é isso que se deve fazer.

A última conferência antes de mostrar o trabalho para mais alguém é a mais simples: feche o Claude Code e abra a página. O que continuar funcionando é a sua aplicação. Todo o resto foi ajuda do agente durante o desenvolvimento - útil, mas que ficou no seu computador.