Como Conectar um Servidor MCP a um Aplicativo de IA

Como Conectar um Servidor MCP a um Aplicativo de IA

Um servidor MCP é como uma oficina bem organizada: oferece ferramentas, materiais de consulta e prompts reutilizáveis. Mas a oficina não aparece sozinha no seu aplicativo de IA. O host, ou aplicativo principal, precisa de um cliente MCP para se conectar, descobrir o que está disponível e encaminhar cada solicitação ao servidor certo.

Vamos conectar tudo. Criaremos um pequeno cliente TypeScript que inicia um servidor local, descobre as ferramentas disponíveis e mostra onde o modelo entra. Depois, veremos como a mesma ideia funciona com um servidor remoto e um produto de IA real.

Quem participa da conversa?

O host é o aplicativo que a pessoa usa. Ele controla o chat, consulta um modelo de linguagem, gerencia conexões e decide o que a pessoa pode aprovar. Um cliente MCP fica dentro desse host e se comunica com um servidor específico. O servidor anuncia capacidades: ferramentas que o modelo pode pedir para executar, recursos que o host pode ler e prompts que podem iniciar um fluxo de trabalho.

A ideia principal é: MCP conecta seu aplicativo a capacidades; ele não chama o modelo de IA por você. O host apresenta ferramentas selecionadas ao modelo, recebe uma solicitação de ferramenta, pede ao cliente MCP para executá-la e devolve o resultado ao modelo.

Conecte-se a um servidor local com TypeScript

O SDK oficial de TypeScript v2 separa o pacote cliente do pacote servidor. Este exemplo inicia o processo do servidor como um processo filho via stdio, pergunta quais ferramentas ele oferece e executa uma delas. Instale o SDK cliente e um executor de TypeScript:

npm install @modelcontextprotocol/client
npm install -D typescript tsx @types/node

Salve o código como src/connect.ts, ajustando o caminho do servidor e os argumentos da ferramenta para o seu projeto:

1import { Client } from "@modelcontextprotocol/client";
2import { StdioClientTransport } from "@modelcontextprotocol/client/stdio";
3
4const client = new Client(
5  { name: "meu-host-de-ia", version: "1.0.0" },
6  { versionNegotiation: { mode: "auto" } },
7);
8
9const transport = new StdioClientTransport({
10  command: "npx",
11  args: ["tsx", "./server/index.ts"],
12});
13
14try {
15  await client.connect(transport);
16
17  const { tools } = await client.listTools();
18  console.log("Ferramentas disponíveis:", tools.map(({ name }) => name));
19
20  // Use um nome e argumentos que o servidor conectado realmente anunciar.
21  const result = await client.callTool({
22    name: "get-weather",
23    arguments: { city: "Boston" },
24  });
25
26  if (result.isError) {
27    throw new Error("A ferramenta MCP retornou um erro");
28  }
29
30  for (const block of result.content) {
31    if (block.type === "text") console.log(block.text);
32  }
33} finally {
34  await client.close();
35}

versionNegotiation: { mode: "auto" } pede ao SDK que use o ciclo de protocolo stateless atual 2026-07-28 quando disponível, com compatibilidade com servidores antigos. Isso importa porque instalar um SDK recente não significa necessariamente que todo cliente criado manualmente adote o novo protocolo. Em stdio local, o SDK inicia e controla o processo: não inicie uma segunda cópia em outro terminal. As mensagens do protocolo devem ficar em stdout; diagnósticos do servidor vão para stderr.

Conecte-se a um servidor remoto

Para um servidor implantado na rede, use o transporte Streamable HTTP do SDK e um endpoint completo https://. O cliente e o servidor podem estar em aplicativos diferentes e ser implantados de forma independente. Uma integração remota de produção também precisa de autorização: use o fluxo OAuth MCP aceito pelo cliente e pelo provedor, armazene as credenciais com segurança e nunca coloque um token bearer duradouro no código-fonte ou em um prompt do modelo.

A configuração exata depende do host. Em um produto como um ambiente de desenvolvimento integrado (IDE), você pode adicionar o servidor nas configurações MCP do produto e deixar que o host gerencie o cliente. Em um aplicativo próprio, o SDK MCP cuida da comunicação do protocolo e a camada de identidade do app fornece o provedor de autorização aceito. Não invente um esquema próprio de cabeçalho quando o servidor exigir a autorização MCP.

O transporte muda, mas o fluxo do cliente continua familiar:

1import { Client, StreamableHTTPClientTransport } from "@modelcontextprotocol/client";
2
3const client = new Client(
4  { name: "meu-host-de-ia", version: "1.0.0" },
5  { versionNegotiation: { mode: "auto" } },
6);
7
8await client.connect(
9  new StreamableHTTPClientTransport(new URL("https://mcp.example.com/mcp")),
10);

Para um endpoint protegido, configure o provedor cliente OAuth aceito pelo SDK para o seu aplicativo; este exemplo com apenas uma URL serve somente para um servidor sem exigência de autorização. Use https:// nas conexões de rede.

O ciclo entre modelo e servidor

Depois de chamar listTools(), os nomes, as descrições e os esquemas JSON de entrada do servidor podem ser convertidos em definições de ferramenta da API do modelo. Quando o modelo retornar uma chamada, encaminhe nome e argumentos para client.callTool(). Depois, envie o conteúdo retornado ao modelo como resultado daquela chamada.

1Host → cliente MCP: listTools()
2Cliente MCP → servidor: tools/list
3Servidor → cliente MCP → host: nomes + esquemas das ferramentas
4Host → modelo: conversa + ferramentas selecionadas
5Modelo → host: solicitação de ferramenta(nome, argumentos)
6Host → cliente MCP: callTool(nome, argumentos)
7Cliente MCP → servidor → host: resultado da ferramenta
8Host → modelo: resultado da ferramenta
9Modelo → pessoa: resposta

callTool() não decide se o modelo deve executar uma ferramenta. O host faz esse encaminhamento e é o lugar certo para filtrar ferramentas conforme a tarefa, validar nome e argumentos, aplicar permissões e pedir aprovação antes de ações sensíveis. Um esquema anunciado pelo servidor ajuda na documentação e validação; não prova que aquela pessoa tem permissão para executar a operação.

Ofereça uma caixa de ferramentas pequena e pertinente

Pode ser tentador encaminhar todas as ferramentas de todos os servidores em cada solicitação ao modelo. Isso cria um menu confuso e pode expor capacidades desnecessárias. Em vez disso, escolha poucas ferramentas conforme a tarefa atual e as permissões da conta. Escreva descrições claras, mantenha esquemas de argumentos específicos e diferencie ações somente de leitura daquelas que alteram dados.

A operação tools/list pode usar paginação, e respostas MCP atuais podem incluir indicações de cache. Use a paginação do SDK e respeite o escopo e o prazo de cache; listas que variam por pessoa ou organização não devem vazar entre contas. Atualize a descoberta quando um servidor mudar e informe claramente se uma ferramenta desaparecer entre a descoberta e uma chamada posterior.

Recursos, prompts e capacidades

Ferramentas são ações. Recursos expõem dados que o host pode ler por URI; prompts oferecem modelos reutilizáveis para iniciar tarefas. Você pode descobri-los pelos métodos de listagem correspondentes e depois ler um recurso ou obter um prompt quando necessário. Não busque todos os recursos por padrão: selecione apenas o material necessário e pense em como dados privados podem entrar no contexto do modelo.

Um servidor MCP também pode anunciar extensões opcionais do protocolo. Só use capacidades que host e servidor realmente negociaram; não presuma que o nome ou a versão informados pelo servidor são uma identidade confiável. Metadados ajudam na compatibilidade e apresentação, não controlam o acesso.

Problemas comuns de conexão

Para um servidor antigo, o SDK pode negociar o ciclo anterior de inicialização em vez do ciclo stateless mais recente. Confira a compatibilidade real do servidor antes de investigar essa diferença como um erro do aplicativo.

Uma primeira integração segura

Comece com um servidor confiável e uma ferramenta somente de leitura. Confirme o resultado e então conecte o ciclo da ferramenta ao provedor do modelo. Só adicione ações de escrita quando tiver autorização por pessoa, validação de argumentos, confirmação visível para operações importantes, timeouts e logs úteis sem segredos. Encerre os transportes ao desligar o aplicativo e mantenha processos e dependências atualizados.

Para saber mais

• SDK MCP TypeScript: crie seu primeiro cliente
• SDK MCP TypeScript: conectar a um servidor
• SDK MCP TypeScript: chamar ferramentas e ler recursos
• Entenda os clientes MCP
• Especificação de autorização MCP (2026-07-28)