Engenharia de IA
Como criar um servidor MCP: guia prático para sistemas de negócio
Comece com ferramentas somente leitura. Para criar um servidor MCP, escolha um sistema que você quer que um assistente de IA alcance e exponha algumas ferramentas somente leitura sobre ele com um SDK oficial. Teste-as no MCP Inspector e depois conecte o resultado ao Claude ou ao ChatGPT. A primeira versão é pequena. Autenticação, permissões e hospedagem exigem mais cuidado do que o próprio protocolo.
Este guia é para um líder técnico, ou para um empresário que vai passar o briefing a um, que quer um servidor MCP sobre um CRM, banco de dados ou repositório de documentos. Ele segue o desenvolvimento em ordem, do que expor até como implantar e proteger. Se você quer primeiro a definição, leia o que é um servidor MCP. Se prefere entregar o desenvolvimento a outra equipe, o nosso serviço de desenvolvimento de servidores MCP começa em R$ 35.000.
Principais conclusões
- Comece com ferramentas somente leitura sobre um sistema. Acrescente ferramentas de escrita depois, atrás de aprovação humana.
- Use um SDK oficial em uma linguagem que a sua equipe já usa. Desenvolva sobre stdio e depois troque para Streamable HTTP quando outras pessoas precisarem compartilhar o servidor.
- Um servidor remoto deve usar OAuth, conferir se cada token foi emitido para ele e nunca repassar o token de um cliente para outro serviço.
- Escreva a descrição de cada ferramenta como um briefing para um colega novo, e teste cada ferramenta primeiro no MCP Inspector.
- Uma equipe técnica consegue seguir o quickstart oficial até um primeiro servidor. O nosso começa em R$ 35.000, com autenticação, permissões por usuário e implantação incluídas.
Como criar um servidor MCP: as decisões em ordem
Seis decisões moldam o desenvolvimento, e cada uma tem um padrão sensato. A tabela as lista na ordem em que aparecem, com o que escolheríamos para começar.
| Decisão | Opções | Com o que começaríamos |
|---|---|---|
| O que expor | Ferramentas, recursos, prompts | Ferramentas somente leitura |
| SDK | Dez linguagens oficiais | A linguagem habitual da sua equipe |
| Transporte | stdio, Streamable HTTP | stdio para desenvolver, HTTP para compartilhar |
| Autenticação | Credenciais do ambiente, OAuth | OAuth pelo seu provedor de identidade |
| Cliente | Claude, ChatGPT, outros | O que a sua equipe já usa hoje |
| Escrita | Desligada, ou ligada com aprovação | Desligada até a leitura funcionar |
Uma observação sobre versões. Lemos a revisão 2026-07-28 da especificação, a que estava no endereço “latest” de modelcontextprotocol.io em 1º de novembro de 2026. O changelog dela registra que foram removidas as sessões no nível do protocolo e o handshake initialize, então cada requisição agora carrega a própria versão do protocolo.
O que um servidor MCP deve expor?
Comece com ferramentas, e faça as primeiras somente leitura. A especificação descreve as ferramentas como controladas pelo modelo, ou seja, o modelo de linguagem consegue descobri-las e chamá-las por conta própria (especificação de ferramentas). Também existem recursos e prompts, mas as ferramentas são o que um assistente procura quando alguém faz uma pergunta sobre os seus dados.
Para um CRM, banco de dados ou repositório de documentos, comece pelas perguntas que a sua equipe já cola à mão em um assistente, como “Qual é o status deste negócio?”. Cada uma vira uma ferramenta com uma tarefa estreita. A equipe de engenharia da Anthropic, em um post de setembro de 2025 sobre como escrever ferramentas para agentes, observa que uma ferramenta pode fazer várias chamadas de API por baixo. Uma única ferramenta “encontrar os pedidos em aberto de um cliente” pode, portanto, substituir vários endpoints brutos. O mesmo post diz: “Mais ferramentas nem sempre levam a resultados melhores.”
Acrescente ferramentas de escrita, como atualizar um negócio, só depois que as de leitura funcionarem bem. A documentação da OpenAI diz que o ChatGPT exige confirmação para ações de escrita por padrão e respeita a anotação readOnlyHint. Mas não dependa de uma anotação para ter segurança. A especificação orienta os clientes a tratar as anotações de ferramentas como não confiáveis, a menos que venham de servidores confiáveis. Imponha o acesso somente leitura nas próprias credenciais do servidor, por exemplo com um perfil de banco de dados somente leitura.
Mantenha as ferramentas sem estado sempre que puder. A revisão atual não tem sessão no nível do protocolo, então uma tarefa que se estende por várias chamadas precisa de um identificador explícito que o servidor cria e, a cada chamada, confere se pertence a quem está chamando.
Qual SDK e qual transporte escolher?
Escolha um SDK oficial
Use o SDK oficial de uma linguagem que a sua equipe já usa. A página de SDKs lista TypeScript, Python, C#, Go, Rust e Ruby como Tier 1, Java como Tier 2 e Swift, PHP e Kotlin como Tier 3. Os tiers avaliam a completude de recursos, o suporte ao protocolo e o compromisso de manutenção. Quando a escolha está em aberto, ficaríamos com TypeScript ou Python.
O quickstart cria um servidor de previsão do tempo com duas ferramentas, get_alerts e get_forecast. Em Python (3.10 ou superior, com a versão 2.0.0 ou superior do SDK MCP para Python), você cria um objeto MCPServer e marca cada função de ferramenta com @mcp.tool(). O SDK gera a definição da ferramenta a partir das anotações de tipo e da docstring da função. Em TypeScript (Node.js 20 ou superior), você instala @modelcontextprotocol/server, cria um McpServer e registra cada ferramenta com registerTool.
Confira se qualquer tutorial corresponde à versão do SDK que você instala, já que versões anteriores podem dar outros nomes às coisas. A página de SDKs também diz que os SDKs adotam novas revisões no próprio ritmo, então verifique qual revisão o seu suporta.
Local (stdio) ou remoto (Streamable HTTP)?
Com stdio, o cliente inicia o seu servidor como um subprocesso na mesma máquina. Com Streamable HTTP, o servidor expõe um endpoint que aceita requisições POST, como https://example.com/mcp. O transporte antigo HTTP+SSE está descontinuado, e a página do Streamable HTTP diz que novas implementações não devem adotá-lo.
Desenvolva primeiro sobre stdio. Nada fica exposto a uma rede, e o Claude Desktop consegue iniciar o servidor a partir do arquivo claude_desktop_config.json. Um servidor stdio nunca deve escrever na saída padrão, porque isso corrompe as mensagens JSON-RPC. O print() do Python faz exatamente isso, então registre os logs no stderr.
Passe para Streamable HTTP quando mais de uma pessoa precisar do servidor. A central de ajuda do Claude trata os servidores locais em claude_desktop_config.json como algo separado dos conectores personalizados, e o ChatGPT pede um endereço de servidor ou um túnel.
Como funciona a autenticação em um servidor remoto?
Use OAuth por meio de um provedor de identidade que você já usa, e faça o seu servidor conferir os tokens em vez de emiti-los. Na revisão 2026-07-28, a autorização é opcional. Um servidor em um transporte baseado em HTTP deve seguir a especificação de autorização, que se apoia no OAuth 2.1. Um servidor stdio deve obter as credenciais do ambiente.
A especificação dá um papel a cada parte. O seu servidor MCP é um servidor de recursos OAuth e o cliente age em nome do usuário. Um servidor de autorização separado faz o login do usuário e emite os tokens, e ele pode ser o seu provedor de identidade atual.
O seu servidor tem quatro tarefas:
- Publicar o OAuth Protected Resource Metadata, para que os clientes encontrem o seu servidor de autorização.
- Responder a uma requisição sem token válido com HTTP 401 e um cabeçalho
WWW-Authenticateque aponta para esses metadados. - Conferir se cada access token foi emitido tendo o seu servidor como público-alvo.
- Não aceitar nenhum token que não seja válido para os seus próprios recursos, e nunca repassar o token de um cliente para uma API a jusante.
As orientações de segurança chamam esse último ponto de token passthrough, e a especificação de autorização o proíbe. Isso significa que o seu servidor precisa de uma credencial própria para o CRM, e aplicar as regras de acesso de cada usuário é trabalho seu, dentro do servidor.
A autenticação diz quem está pedindo, e as permissões decidem o que essa pessoa pode ver. A especificação permite que um servidor varie a lista de ferramentas conforme a autorização apresentada, por exemplo devolvendo só as ferramentas que os escopos concedidos a quem chama permitem.
Vale conferir duas coisas com o seu provedor de identidade. Ele deve suportar OAuth Client ID Metadata Documents, que a revisão prefere, porque o Dynamic Client Registration está descontinuado e foi mantido só por compatibilidade. Ele também deve emitir escopos estreitos. As orientações de segurança recomendam começar com escopos de leitura de baixo risco, pedir mais só quando uma operação privilegiada for tentada pela primeira vez e evitar escopos curinga como *.
Como escrever descrições de ferramentas que o modelo consegue usar?
Escreva cada descrição como você faria o briefing de um colega novo. O post de engenharia da Anthropic propõe esse teste e sugere nomear os parâmetros sem ambiguidade, com user_id em vez de user. Acrescente o que um recém-chegado precisaria saber, como o que a ferramenta devolve, quando usá-la em vez de uma ferramenta vizinha e como é uma entrada válida.
Segundo a especificação de ferramentas, cada ferramenta tem um name, uma description e um inputSchema em JSON Schema. Os nomes devem ter de 1 a 128 caracteres entre letras, dígitos, sublinhados, hifens e pontos. Três hábitos ajudam:
- Devolva o que a pessoa precisa. Nomes e status são melhores que identificadores internos. O post da Anthropic aconselha priorizar a relevância contextual e evitar identificadores técnicos de baixo nível.
- Limite o tamanho dos resultados. O mesmo post sugere paginação, seleção de intervalo, filtragem ou truncamento, para que uma tabela grande não inunde o contexto do modelo.
- Informe as falhas no resultado. A especificação separa erros de protocolo de erros de execução de ferramentas. Coloque falhas de API e entradas inválidas no resultado da ferramenta com
isError: truee diga o que estava errado, para que o modelo consiga se corrigir e tentar de novo.
Depois, teste as descrições em tarefas reais. A Anthropic recomenda tarefas de avaliação construídas a partir do uso real, e observa que muitos erros de parâmetros inválidos podem indicar que as descrições precisam ser mais claras.
Teste com o MCP Inspector e depois conecte o Claude ou o ChatGPT
Teste cada ferramenta no MCP Inspector antes que um assistente a veja. Ele é a ferramenta de referência para desenvolvedores testarem e depurarem servidores, distribuída como o pacote @modelcontextprotocol/inspector, e precisa do Node 22.19.0 ou mais recente. Rode npx @modelcontextprotocol/inspector para o cliente web, acrescente --cli para um cliente de linha de comando automatizável ou --tui para uma interface de terminal.
Passe como argumentos o comando que inicia o seu servidor, ou use --server-url com --transport http para um servidor remoto. Na linha de comando, --method tools/list lista as ferramentas e --method tools/call chama uma delas. O Inspector consegue exercitar as duas eras do protocolo, e o quickstart roda a verificação em TypeScript uma vez para cada uma com --protocol-era.
Conectar o Claude
Os nomes dos menus mudam, então estes passos seguem as páginas de ajuda dos fornecedores em 1º de novembro de 2026. Para um servidor stdio local, adicione-o na chave mcpServers do claude_desktop_config.json do Claude Desktop, usando caminhos absolutos, como mostra o quickstart.
Para um servidor remoto, adicione um conector personalizado em Customize > Connectors, ou em Organization settings > Connectors nos planos Team e Enterprise. A Claude Help Center acrescenta quatro pontos:
- Conectores personalizados estão disponíveis nos planos Free, Pro, Max, Ultra, Team e Enterprise, e usuários Free ficam limitados a um.
- Nos planos Team, só Owners e Primary Owners podem adicionar um.
- O seu servidor precisa ser acessível pela internet pública a partir das faixas de IP da Anthropic, então, em uma rede privada, libere esses endereços no seu firewall.
- O login normalmente é por OAuth, embora alguns conectores usem uma chave de API ou outra credencial fixa.
O guia de servidores remotos da documentação do MCP acrescenta que você pode ativar ou desativar ferramentas individuais nas configurações do conector, uma segunda camada útil de privilégio mínimo.
Conectar o ChatGPT
A página da OpenAI diz para usar o ChatGPT na web. Abra Plugins, selecione o botão de mais e escolha Add custom MCP server. Dê um nome e, em Connection, digite o endereço do servidor ou selecione Tunnel para um Secure MCP Tunnel. Os protocolos suportados são SSE e HTTP com streaming, e as opções de autenticação são OAuth, sem autenticação, ou OAuth ou sem autenticação. Depois você aceita um aviso de risco e cria o plugin.
As permissões do workspace e as restrições de segurança, incluindo o Lockdown, se aplicam. A página não diz quais planos podem adicionar um servidor personalizado, então verifique o seu. Desenvolva seguindo o transporte remoto da especificação e teste com o conector de cada cliente.
Implantar, monitorar e proteger o servidor
Implantar e monitorar
Um servidor MCP remoto é um serviço web com um endpoint HTTPS. A especificação do Streamable HTTP define regras que vale a pena incorporar desde o início:
- Valide o cabeçalho
Originem cada conexão e rejeite um inválido com HTTP 403, o que protege contra DNS rebinding. - Vincule um servidor rodando localmente a
127.0.0.1, e não a todas as interfaces de rede. - Atrás de um proxy como o nginx, envie
X-Accel-Buffering: nonas respostas em streaming para que os eventos não fiquem em buffer.
O monitoramento começa com uma linha de log para cada chamada de ferramenta, registrando quem chamou, qual ferramenta, quanto tempo levou e se deu certo. A especificação diz que os servidores devem limitar a taxa de chamadas de ferramentas. Nunca registre tokens nem registros completos de clientes, e crie alertas para falhas de autenticação e taxas de erro.
Proteja o servidor
- Mantenha uma pessoa no circuito. A especificação diz que sempre deve haver uma pessoa no circuito com a capacidade de negar chamadas de ferramentas. Mantenha as ferramentas de escrita estreitas, porque
update_deal_stageé mais fácil de aprovar do querun_crm_action. - Valide no servidor. A especificação diz que os servidores devem validar todas as entradas das ferramentas, implementar controles de acesso adequados, limitar a taxa de chamadas e sanitizar as saídas.
- Trate o texto devolvido como não confiável. O modelo lê tudo o que uma ferramenta devolve, então uma anotação que um cliente digitou no seu CRM pode conter instruções voltadas ao modelo. O post do National Cyber Security Centre (o centro nacional de cibersegurança britânico) Prompt injection is not SQL injection (it may be worse) diz que esses ataques talvez nunca sejam totalmente mitigados. Ele defende reduzir o risco e o impacto. Mantenha os escopos de leitura estreitos, devolva só os campos de que a tarefa precisa e mantenha a escrita atrás de aprovação.
- Cuidado com servidores de terceiros. A página da OpenAI diz para conectar apenas a servidores em que você confia, e a especificação trata as descrições do comportamento das ferramentas como não confiáveis, a menos que venham de um servidor confiável.
- Lembre que um servidor local roda com os privilégios do cliente. As orientações de segurança recomendam stdio para servidores executados localmente porque isso limita o acesso ao cliente. Instale-os apenas de fontes em que você confia.
Quanto custa, e o seu próximo passo
Uma equipe técnica consegue seguir o quickstart até um primeiro servidor funcional sem ajuda externa. Na nossa visão, o esforço está em torná-lo seguro para uso no trabalho, ou seja, OAuth com o seu provedor de identidade, permissões por usuário, hospedagem, monitoramento e uma revisão de segurança. Ele cresce com o número de sistemas e com a qualidade das APIs deles. O nosso guia de integração de APIs cobre a camada por baixo.
Desenvolvemos e operamos servidores MCP todos os dias no nosso próprio trabalho de engenharia. Ainda não temos um servidor MCP de cliente para mostrar, e preferimos dizer isso a inventar um. O padrão é jovem, então tratamos a segurança como o primeiro requisito. Os nossos preços publicados:
- Primeiro servidor MCP, a partir de R$ 35.000. Um sistema conectado ao Claude ou ao ChatGPT, com autenticação e permissões por usuário incorporadas, implantado como um servidor remoto que a sua equipe pode usar.
- Desenvolvimento de integração de IA, a partir de R$ 69.000. Servidores MCP para vários sistemas, como um CRM, um banco de dados e documentos. Inclui hospedagem remota na AWS, monitorada e mantida, com acesso definido por usuário.
- Suporte contínuo, a partir de R$ 2.800 por mês.
Escopo e preço são fechados e acordados antes de o trabalho começar. Em um desenvolvimento, você pode cancelar nos primeiros 21 dias e receber todo o seu dinheiro de volta. O código e a propriedade intelectual são seus depois que o trabalho é entregue e pago.
Se o sistema que você quer conectar não tem uma API utilizável, a conexão é o trabalho maior. O nosso serviço de integração de software corporativo conecta sistemas de ERP, CRM e finanças e encapsula sistemas legados com APIs modernas. Se você quer que um agente de IA aja por meio do servidor, com aprovação onde importa, esse é o nosso trabalho de agentes de IA.
O seu próximo passo é escolher um sistema e listar as cinco perguntas que as pessoas colam à mão em um assistente. Essa lista é o escopo de um primeiro servidor, e o briefing que pediríamos em uma call. Desenvolva você mesmo com o quickstart, ou passe para nós pela nossa página de desenvolvimento de servidores MCP, que tem os preços fechados.
Perguntas frequentes
Como criar um servidor MCP?
Escolha um sistema, escolha um SDK oficial e exponha algumas ferramentas somente leitura. Teste-as no MCP Inspector e depois conecte o servidor ao Claude ou ao ChatGPT. Desenvolva primeiro sobre stdio e passe para Streamable HTTP com OAuth quando uma equipe precisar compartilhá-lo. O quickstart oficial mostra passo a passo um servidor com duas ferramentas em Python ou TypeScript. Acrescente ferramentas de escrita só depois que as de leitura funcionarem bem, e mantenha-as atrás de aprovação humana.
Qual linguagem devo usar para criar um servidor MCP?
Use a linguagem que a sua equipe já usa. Os SDKs oficiais cobrem TypeScript, Python, C#, Go, Rust e Ruby no Tier 1, Java no Tier 2 e Swift, PHP e Kotlin no Tier 3. Se a escolha estiver em aberto, TypeScript ou Python são um começo seguro, porque os dois são Tier 1 e o quickstart oficial cria um servidor em cada uma.
Um servidor MCP precisa de autenticação?
Nem sempre. A especificação torna a autorização opcional e diz que um servidor stdio deve obter as credenciais do ambiente. Um servidor remoto em um transporte HTTP deve seguir a especificação de autorização, que se baseia no OAuth 2.1. O seu servidor atua como servidor de recursos, confere se cada token foi emitido para ele e não aceita nenhum outro. Qualquer servidor que toque em dados da empresa deve autenticar os seus usuários.
Como testar um servidor MCP?
Use o MCP Inspector, a ferramenta oficial de testes. Rode npx @modelcontextprotocol/inspector seguido do comando que inicia o seu servidor, ou acrescente a flag --cli para automatizá-lo em scripts. Ele precisa do Node 22.19.0 ou mais recente. Liste as ferramentas, chame cada uma com entradas válidas e inválidas e leia as mensagens brutas. Para um servidor remoto, passe o endereço com --server-url e --transport http.
Quanto custa criar um servidor MCP?
O nosso primeiro servidor MCP começa em R$ 35.000. Ele conecta um sistema ao Claude ou ao ChatGPT, com autenticação e permissões por usuário, implantado como um servidor remoto que a sua equipe pode usar. O desenvolvimento de integração de IA, que cobre vários sistemas com hospedagem na AWS que monitoramos e mantemos, começa em R$ 69.000. O suporte contínuo começa em R$ 2.800 por mês. Escopo e preço são fechados e acordados antes de o trabalho começar.
Conectando a IA aos seus próprios sistemas?
Agende uma consulta gratuita de 30 minutos e definimos o escopo de um primeiro servidor MCP para o sistema que você quer que o seu assistente de IA alcance.