Nível 3 — Automação e escala · Módulo 3.1 — MCP: conectando o Claude aos sistemas

3.1.6 · Construindo seu próprio servidor MCP

5 min de vídeo TEC

Objetivo: ao final, o consultor gera um servidor MCP mínimo que expõe uma ferramenta do catálogo interno da Wayon, testa e conecta ao Claude Code.

O que você precisa levar desta aula

O caminho recomendado hoje é o plugin oficial: /plugin install mcp-server-dev@claude-plugins-official, depois /mcp-server-dev:build-mcp-server — ele pergunta o caso de uso e gera o esqueleto, HTTP remoto ou stdio local.
O que decide se a ferramenta será bem usada é a descrição, não a implementação: diga o que faz e quando usar, com tipos nos parâmetros. É o mesmo princípio da description de skill (aula 2.4.6).
Com tool search, as instruções do servidor orientam o Claude a buscar suas ferramentas — e são truncadas em 2KB, então o essencial vai no começo.

Quando construir, em vez de instalar

Situação	O que fazer
Sistema comum, com servidor de comunidade disponível	Avaliar o existente (aula 3.1.5) — Faixa 2
Serviço com conector gerenciado (Drive, Slack, M365)	Usar o conector — Faixa 1
Sistema interno da Wayon (catálogo de RICEFW, base de conhecimento)	Construir — Faixa 2, com aprovação de arquitetura antes de expor dado de cliente

O caso de construir é quase sempre o terceiro: sistema que só a Wayon tem.

Gerando o esqueleto

/plugin install mcp-server-dev@claude-plugins-official
/mcp-server-dev:build-mcp-server

Se o marketplace não estiver registrado, adicione com /plugin marketplace add anthropics/claude-plugins-official.

A skill pergunta sobre o caso de uso e gera servidor HTTP remoto ou stdio local. Para servidor interno em rede da Wayon, HTTP; para teste na sua máquina, stdio.

O que faz uma ferramenta ser bem usada

O código é a parte fácil. O que decide se o Claude chama a ferramenta na hora certa é a interface declarada:

Elemento	Ruim	Bom
Nome	`query`	`buscar_ricefw`
Descrição	"Consulta o catálogo"	"Busca um RICEFW pelo número ou pelo módulo. Use quando a pergunta envolver status, responsável ou fase de um item do catálogo."
Parâmetros	`args: dict`	`numero: str`, `modulo: str \\| None`, com tipos
Retorno	Texto solto	Estrutura previsível, com os campos nomeados

A regra é a mesma da aula 2.4.6 sobre por que skill não dispara: a descrição é o gatilho, e precisa conter as palavras que a pessoa realmente usa. "RICEFW", "status", "fase" — não "entidade do catálogo".

Instruções do servidor

Com tool search (aula 3.1.3), as instruções do servidor têm papel novo: elas ajudam o Claude a decidir buscar as ferramentas do seu servidor. Diga:

que categoria de tarefa suas ferramentas atendem
quando o Claude deveria procurar por elas
as capacidades principais

Truncadas em 2KB. Essencial no começo.

Testando e conectando

# stdio, para testar local — atenção ao duplo hífen
claude mcp add catalogo -- python servidor.py

Depois, na sessão, /mcp confirma a conexão e mostra a contagem de ferramentas. Servidor que anuncia capacidade de ferramenta e expõe zero é sinalizado no painel — é o primeiro sintoma de erro de implementação.

Regra Wayon Servidor MCP construído pela Wayon passa por aprovação de arquitetura antes de expor qualquer dado de cliente — é Faixa 2, como qualquer outro. Duas exigências específicas: o usuário técnico do servidor tem escopo mínimo (aula 3.1.5), e o servidor não expõe ferramenta de escrita enquanto não houver decisão explícita de que precisa dela. Ferramenta de leitura que alguém depois "só acrescenta um update" é como a fronteira de ambiente é atravessada sem ninguém decidir atravessá-la.

📖 Construir servidor MCP · Troubleshooting de skill — módulo 2.4.6

Quiz — 4 questões

1.Qual é o caminho recomendado hoje para começar um servidor MCP?

a)Instalar o plugin mcp-server-dev@claude-plugins-official e rodar /mcp-server-dev:build-mcp-server, que pergunta o caso de uso e gera o esqueleto
Correto — e repare que a sintaxe de instalação é plugin@marketplace, da aula 3.3.2.
b)Criar um projeto em branco e implementar o protocolo a partir da especificação
Funciona e é muito mais trabalhoso do que necessário; existe geração de esqueleto oficial.
c)Copiar um servidor da comunidade e adaptar o código ao caso interno
Traz o risco da aula 3.1.5 para dentro de casa, e o esqueleto oficial resolve o ponto de partida sem isso.

Ver resposta e por quê

✅a) Correto — e repare que a sintaxe de instalação é plugin@marketplace, da aula 3.3.2.

❌b) Funciona e é muito mais trabalhoso do que necessário; existe geração de esqueleto oficial.

❌c) Traz o risco da aula 3.1.5 para dentro de casa, e o esqueleto oficial resolve o ponto de partida sem isso.

2.Você escreveu a ferramenta buscar_ricefw, com implementação correta, mas o Claude quase nunca a chama quando deveria. Qual é a causa mais provável?

a)O servidor está conectado em escopo local em vez de project
Escopo afeta quem herda a configuração, não se o modelo decide chamar a ferramenta.
b)O transporte stdio é mais lento e o Claude prefere não usar a ferramenta
O modelo não escolhe ferramenta por latência de transporte.
c)A descrição da ferramenta não diz quando usar, nem usa as palavras que o consultor realmente digita
Correto. É o mesmo princípio da aula 2.4.6: a descrição é o gatilho.

Ver resposta e por quê

❌a) Escopo afeta quem herda a configuração, não se o modelo decide chamar a ferramenta.

❌b) O modelo não escolhe ferramenta por latência de transporte.

✅c) Correto. É o mesmo princípio da aula 2.4.6: a descrição é o gatilho.

3.Com tool search ligado, por que as instruções do servidor merecem cuidado especial?

a)Porque elas são o que o consultor lê no /mcp para entender o servidor
O /mcp mostra servidores e contagem de ferramentas; o papel das instruções é outro.
b)Porque são elas que ajudam o Claude a decidir buscar as ferramentas do servidor — e são truncadas em 2KB
Correto, então o essencial vai no começo.
c)Porque substituem a descrição de cada ferramenta individual
As duas coexistem e têm papéis diferentes; a descrição de cada ferramenta continua sendo o gatilho dela.

Ver resposta e por quê

❌a) O /mcp mostra servidores e contagem de ferramentas; o papel das instruções é outro.

✅b) Correto, então o essencial vai no começo.

❌c) As duas coexistem e têm papéis diferentes; a descrição de cada ferramenta continua sendo o gatilho dela.

4.A Wayon vai construir um servidor MCP para o catálogo interno de RICEFW. Qual é a postura correta sobre ferramenta de escrita?

a)Não expor ferramenta de escrita enquanto não houver decisão explícita de que é necessária
Correto. Ferramenta de leitura em que alguém depois "só acrescenta um update" é como a fronteira de ambiente é atravessada sem ninguém decidir.
b)Expor leitura e escrita desde o início, já que o servidor é interno e não toca sistema de cliente
O catálogo contém dado de projeto de cliente, e a exposição de escrita é decisão de arquitetura, não conveniência de implementação.
c)Expor escrita, mas protegê-la com um hook PreToolUse que exige confirmação
O hook é boa segunda camada, mas não substitui a decisão de arquitetura sobre a capacidade existir.

Ver resposta e por quê

✅a) Correto. Ferramenta de leitura em que alguém depois "só acrescenta um update" é como a fronteira de ambiente é atravessada sem ninguém decidir.

❌b) O catálogo contém dado de projeto de cliente, e a exposição de escrita é decisão de arquitetura, não conveniência de implementação.

❌c) O hook é boa segunda camada, mas não substitui a decisão de arquitetura sobre a capacidade existir.