Como criar um servidor MCP: passo a passo

Criar um servidor MCP é a forma de dar às ferramentas de IA do seu time acesso, de maneira padronizada, aos dados e às ações da sua organização. Em vez de cada assistente ter a sua própria integração, você expõe tudo uma vez e qualquer cliente compatível passa a consumir.

Se você ainda não viu o conceito, vale ler antes o nosso guia sobre o que é o Model Context Protocol (MCP). Aqui o foco é prático: o passo a passo para colocar um servidor de pé e conectá-lo a um cliente.

O que um servidor MCP expõe

Um servidor MCP oferece três tipos de recurso para o cliente, e entender essa divisão é o que torna o resto simples:

• Tools são ações que o modelo pode executar, como consultar um sistema, criar um registro ou rodar uma busca. Cada tool tem nome, descrição e um schema de entrada.
• Resources são dados que o cliente pode ler, identificados por um endereço (URI), como um arquivo, uma página de documentação ou o resultado de uma consulta.
• Prompts são modelos de instrução reutilizáveis que o servidor disponibiliza prontos para o cliente usar.

Do outro lado está o cliente, que é a ferramenta de IA que se conecta ao servidor, como Claude, Cursor, Codex ou Copilot. A conversa entre os dois acontece sobre um transport, que pode ser local ou remoto.

O que você vai precisar

• Um SDK oficial do MCP, disponível em TypeScript e em Python. Ele cuida do protocolo para você, então o seu trabalho fica em definir o que expor.
• Um cliente para testar, como o Claude Desktop ou o Cursor, que leem uma configuração simples em JSON para se conectar ao seu servidor.
• Clareza sobre o que expor, ou seja, quais dados e quais ações fazem sentido entregar para os agentes antes de escrever qualquer linha.

Passo a passo para criar um servidor MCP

1. Decida o que o servidor vai expor

Antes do código, liste as tools e os resources que fazem sentido. Uma regra prática: tools para o que o agente precisa fazer, resources para o que ele precisa ler. Comece pequeno, com uma ou duas capacidades bem definidas, e cresça depois.

2. Inicie o projeto com o SDK

Crie um projeto novo e instale o SDK oficial, o pacote @modelcontextprotocol/sdk em Node, ou o pacote mcp em Python. Em seguida, crie uma instância de servidor com um nome e uma versão, que é o que o cliente vai enxergar ao se conectar.

3. Defina as tools

Para cada ação, registre uma tool com quatro coisas: um nome claro, uma descrição que diga ao modelo quando usá-la, um schema de entrada que valide os parâmetros e a função que executa de fato. A descrição é a parte mais subestimada: é por ela que o modelo decide chamar, ou não, a sua tool.

4. Exponha os resources

Resources são dados endereçáveis por URI. Você define quais estão disponíveis e entrega o conteúdo quando o cliente pede. Pense em documentos, trechos de uma base de conhecimento ou o retorno de uma consulta já formatado para leitura.

5. Escolha o transport

Para rodar na máquina do desenvolvedor, o transport por stdio é o mais simples e é o que a maioria dos clientes de desktop usa. Para expor o servidor pela rede, para vários usuários, use HTTP. O código das tools é o mesmo nos dois casos, muda apenas como o servidor é iniciado.

6. Conecte e teste em um cliente

Aponte o cliente para o seu servidor adicionando uma pequena configuração em JSON, por exemplo no arquivo do Cursor ou do Claude. Ao reiniciar o cliente, as tools aparecem disponíveis e você consegue pedir ao assistente que as use, confirmando que tudo responde como esperado.

7. Cuide de acesso e segurança

Assim que o servidor sai da sua máquina, o acesso precisa de controle. Use chaves para autenticar os clientes, limite o escopo do que cada chave enxerga e exponha apenas o necessário. Tratar isso desde o início evita retrabalho e vazamento de dados sensíveis.

Erros comuns ao criar um servidor MCP

• Descrições vagas nas tools, que fazem o modelo chamar a ferramenta errada ou não chamar nenhuma.
• Expor dados demais, entregando bases inteiras quando um recorte resolveria, o que aumenta custo e risco.
• Esquecer o schema de entrada, deixando o modelo enviar parâmetros inválidos e a tool falhar de forma silenciosa.
• Ignorar o controle de acesso, publicando um servidor sem chaves nem limite de escopo.

Como fazer isso sem construir do zero

Construir e manter um servidor MCP dá trabalho: além do código das tools, há transport, autenticação, versionamento e a atualização constante do que é exposto. Quando o objetivo é dar aos agentes acesso ao conhecimento da organização, dá para pular essa engenharia.

A Attlas funciona como um servidor MCP sobre a sua base. Você conecta as fontes, e a plataforma expõe esse conteúdo como tools, resources e prompts, com chaves por organização e uma config pronta para colar no cliente. Os mesmos agentes de IA que o time já usa passam a responder com base no que a empresa sabe, sem ninguém manter um servidor à mão.

Conclusão

Criar um servidor MCP é, no fundo, decidir o que expor e registrar isso como tools, resources e prompts sobre um transport, com acesso controlado. Vale fazer do zero para casos específicos, e vale usar uma camada pronta como a Attlas quando o que você quer é expor a base de conhecimento para os agentes rápido e com segurança.