MCP Server
Um servidor MCP bem projetado traduz capacidades de um sistema em contratos que o cliente consegue descobrir e validar. A loja desta semana expõe uma consulta de estoque, uma política de devolução e um prompt para revisar solicitações. O desafio é manter essas três interfaces coerentes sem colocar regras críticas apenas em descrições textuais. Vamos construir o núcleo do servidor como uma função local e depois discutir o transporte que o torna acessível a um cliente.
A especificação usada é MCP 2026-07-28. O exemplo mostra um descritor de tool e seu executor, mas não pretende implementar todo o protocolo. O servidor completo precisa também cumprir metadados, discovery, listagens e transporte da revisão escolhida. Essa separação permite testar a regra de negócio sem rede e verificar o contrato de comunicação em uma etapa própria. Logs, schemas, resources e prompts serão tratados como partes de uma interface revisável.
JavaScriptMCPAo terminar esta aula
- Núcleo de domínio e adaptador MCP devem ser verificáveis separadamente.
- Schemas precisam corresponder à implementação e não garantem fatos sozinhos.
- Logs e resources exigem limites para não corromper protocolo nem expor dados.
Antes de continuar: Laboratório: MCP fundamentos
Comece pelo domínio, não pelo transporte
FundamentosA consulta de estoque recebe sku e retorna quantidade e fonte. Ela não reserva item nem altera pedido. Essa definição estreita o privilégio necessário e torna a operação adequada para o primeiro servidor. O núcleo de domínio deve funcionar independentemente de MCP, para que uma falha de schema ou transporte não esconda um erro no cálculo. Valide identificadores, formato e limites antes de consultar. Um inputSchema descreve a forma aceita, mas a aplicação continua responsável por verificar se o sku existe e se o chamador pode acessar esse catálogo.
Uma ferramenta com vários modos, como consultar ou reservar dependendo de um campo, complica a revisão de permissões. Prefira separar a operação de leitura da operação com efeito, dando a cada uma nome, descrição e executor próprios. Não use descrições promocionais ou instruções para o modelo ignorar outros controles. O nome deve indicar a capacidade; o schema deve informar argumentos; a documentação deve explicar erros e limites. Para um catálogo multitenant, o tenant autorizado deve vir do contexto autenticado, e não de um argumento livre que o modelo pode preencher.
Schemas são contratos verificáveis
FundamentosinputSchema estabelece tipos, propriedades exigidas e limites relevantes. outputSchema descreve a estrutura que o cliente espera quando a ferramenta retorna conteúdo estruturado. O exemplo exige sku e quantidade na saída e proíbe propriedades extras na entrada. Essa regra reduz ambiguidades, mas não prova que quantidade corresponde ao estoque real. A validação semântica compara resultado com a fonte e com o domínio. Teste campos ausentes, tipos errados, propriedades extras e item desconhecido. Cada caso exercita uma defesa diferente e deve produzir um erro identificável.
O servidor precisa manter alinhamento entre schema e implementação. Se declarar quantidade como inteiro e retornar uma string, o cliente não deveria ter que adivinhar a conversão. Se mudar o nome de um campo, atualize contrato e consumidores ou versionar a interface conforme a política. O resultado MCP da revisão atual possui superfícies como content e structuredContent e o tipo de resultado previsto pelo protocolo. Não monte um envelope de outra revisão a partir da memória. O adaptador de transporte deve seguir a especificação efetivamente utilizada, enquanto o domínio permanece com objetos simples.
Resources e prompts precisam de origem e limites
FundamentosA política de devolução é um resource identificado por URI, com conteúdo e tipo de mídia. Sua origem e validade importam porque o atendente usa esse texto como evidência. O servidor deve impedir acesso a recursos privados fora do escopo do chamador e limitar o tamanho retornado. Uma URI não é autorização nem caminho de arquivo que possa ser lido arbitrariamente. Quando há templates parametrizados, valide os parâmetros e resolva o recurso dentro do conjunto permitido, impedindo que o cliente atravesse diretórios ou consulte dados de outro tenant.
O prompt de revisão organiza a tarefa usando argumentos como pedido e motivo, mas não deve embutir credenciais nem comandos que ampliem privilégio. Ele pode pedir para comparar a solicitação com a política selecionada e devolver lacunas. O host decide como incorpora esse prompt e seu contexto. Um texto gerado por prompt não confirma a devolução; a operação de confirmação continua em outra ferramenta. Mantenha versões e exemplos dos prompts para detectar mudanças que alterem expectativas do consumidor, principalmente quando um cliente conserva uma seleção ou cache do catálogo.
const descritor={name:'consultar_estoque',description:'Consulta estoque sem reservar.',inputSchema:{type:'object',properties:{sku:{type:'string'}},required:['sku'],additionalProperties:false},outputSchema:{type:'object',properties:{sku:{type:'string'},quantidade:{type:'integer'},fonte:{type:'string'}},required:['sku','quantidade','fonte']}};
const catalogo={I2:3,I3:0};
function consultar(args) {
if (!args || typeof args.sku!=='string' || Object.keys(args).some(k=>k!=='sku')) throw new Error('argumentos invalidos');
if (!(args.sku in catalogo)) throw new Error('item desconhecido');
return {sku:args.sku,quantidade:catalogo[args.sku],fonte:'catalogo local'};
}
console.log(descritor,consultar({sku:'I2'}));
for (const args of [{sku:'I99'},{sku:'I2',quantidade:2}]) {try { consultar(args); }catch(e){console.log(e.message);}}Logs e transporte precisam preservar o protocolo
FundamentosEm stdio, stdout transporta mensagens delimitadas por linha. Um console.log de diagnóstico misturado às respostas pode tornar o servidor impossível de interpretar. Use stderr para diagnóstico operacional quando adequado e os mecanismos de logging MCP conforme a revisão, sem confundir os dois canais. Logs devem indicar correlação, operação e status, evitando segredos e dados pessoais desnecessários. O fato de um cliente poder receber logs não significa que deve receber detalhes internos de credenciais ou consultas privadas.
↗ Logging — MCP 2026-07-28↗ Transports overview — MCP 2026-07-28
A criação do servidor completo envolve registrar discovery, capabilities, listagens e chamadas no runtime compatível, além de abrir o transporte. Verifique a revisão do SDK antes de copiar um tutorial. O guia oficial de construção ajuda essa etapa, mas versões de pacotes e métodos precisam ser fixados na entrega real. Avalie nominal, schema inválido, resource proibido e falha interna. Uma falha do domínio não deve derrubar o processo inteiro, e um erro interno não deve vazar stack ou segredo para o cliente.
Exercício aplicado
Publique consulta de estoque, política de devolução e prompt de revisão para uma loja. Valide campos e preserve a disponibilidade do servidor diante de chamadas inválidas.
- Execute o núcleo com item conhecido, desconhecido, tipo errado e campo extra.
- Registre os contratos em um runtime MCP de versão conhecida.
- Capture discovery, listagem e chamada em transporte real.
- Teste resource recusado, prompt incompleto e logs sem segredos.
Abrir resolução comentada
O descritor anuncia consultar_estoque com entrada sku e saída estruturada. O executor aceita somente o objeto com a chave prevista, consulta o catálogo e devolve os campos prometidos. O caso quantidade extra é recusado como argumento inválido; o sku desconhecido é uma falha do domínio. Essa separação torna possível identificar se o pedido estava malformado ou se o item simplesmente não existe.
O núcleo local deve ser conectado a um servidor MCP com versão fixada e envelopes corretos. Acrescente resource e prompt sem misturar suas responsabilidades com a tool. A evidência de servidor completo exige um cliente realizando discovery, listagem e chamada no transporte real, além dos testes locais do executor.
const descritor={name:'consultar_estoque',description:'Consulta estoque sem reservar.',inputSchema:{type:'object',properties:{sku:{type:'string'}},required:['sku'],additionalProperties:false},outputSchema:{type:'object',properties:{sku:{type:'string'},quantidade:{type:'integer'},fonte:{type:'string'}},required:['sku','quantidade','fonte']}};
const catalogo={I2:3,I3:0};
function consultar(args) {
if (!args || typeof args.sku!=='string' || Object.keys(args).some(k=>k!=='sku')) throw new Error('argumentos invalidos');
if (!(args.sku in catalogo)) throw new Error('item desconhecido');
return {sku:args.sku,quantidade:catalogo[args.sku],fonte:'catalogo local'};
}
console.log(descritor,consultar({sku:'I2'}));
for (const args of [{sku:'I99'},{sku:'I2',quantidade:2}]) {try { consultar(args); }catch(e){console.log(e.message);}}Como conferir seu resultado
- Entrada e saída correspondem aos schemas anunciados.
- Uma consulta válida funciona depois da falha.
- stdout de stdio não contém diagnóstico comum.
Aplique em um problema novo
Primeiro resolva sem consultar a resposta. Explique suas decisões e guarde a evidência. A conclusão de leitura é independente desta autoavaliação.
Confira seus pré-requisitos
- Separar executor de transporte MCP.
- Definir schemas de entrada/saída.
Tool retorna estoque como string embora schema exija inteiro. Logs de debug entram emstdout. Diagnostique cliente e servidor.
Conferir raciocínio e critérios de domínio
Saída viola contrato; validar e corrigir executor/schema, sem conversão adivinhada.
Uma falha de operação não deve encerrar todas próximas consultas.
Stdio usa stdout para protocolo; diagnóstico vai a stderr/mecanismo apropriado.
Evidências para autoavaliação ou revisão por pares
- Schema: Saída viola contrato; validar e corrigir executor/schema, sem conversão adivinhada.
- Disponibilidade: Uma falha de operação não deve encerrar todas próximas consultas.
- Canais: Stdio usa stdout para protocolo; diagnóstico vai a stderr/mecanismo apropriado.
Um erro frequente
JSON parseável implica contrato correto.
JSON válido pode violar tipos e regras do domínio.
Teste sua compreensão
Responda com suas palavras antes de abrir o comentário. Saber explicar uma decisão é parte do domínio.
1. inputSchema substitui autorização?
Não. Ele descreve e valida forma de argumentos.
O executor precisa verificar identidade e acesso ao catálogo.
2. Resource é um caminho arbitrário de arquivo?
Não. A URI deve ser resolvida dentro do conjunto permitido.
Ler caminhos livres pode expor conteúdo fora do escopo.
3. O núcleo local já é um servidor MCP completo?
Não. Falta o adaptador compatível e a evidência de transporte.
Domínio e protocolo são camadas com verificações próprias.
Seu progresso fica salvo neste navegador. Concluir a leitura não substitui demonstrar o domínio nos exercícios.
Referências e aprofundamento
Documentação oficial e trabalhos originais. As referências registram o escopo e as limitações para você conferir o que sustentam.
- Build an MCP server
Model Context Protocol • consulta: 2026-10-06
MCPCriação de servidor e tools usando SDKs oficiais; execução e teste local.
Limites: Sintaxe varia por linguagem e geração de SDK; exemplos precisam de implementação da autorização de negócio.
- Base protocol — MCP 2026-07-28
Model Context Protocol • consulta: 2026-10-06
MCPJSON-RPC, schema, versão/capabilities em _meta e JSON Schema2020-12.
Limites: Fonte aberta contém versão por requisição; compatibilidade com revisões antigas exige implementação explícita.
- Tools — MCP 2026-07-28
Model Context Protocol • consulta: 2026-10-06
MCPtools/list/call, inputSchema/outputSchema, resultados, segurança e logs para auditoria.
Limites: Anotações e descrição não concedem autorização; outputs continuam não confiáveis.
- Resources — MCP 2026-07-28
Model Context Protocol • consulta: 2026-10-06
MCPResources, URIs, leitura, templates e notificações.
Limites: Recursos são contexto fornecido por servidor, não instruções automaticamente confiáveis.
- Prompts — MCP 2026-07-28
Model Context Protocol • consulta: 2026-10-06
MCPDescobrir prompts, buscar mensagens e parametrizar templates; capability em DiscoverResult.
Limites: Prompt vem do servidor; controle do usuário sobre seleção não garante segurança do conteúdo.
- Logging — MCP 2026-07-28
Model Context Protocol • consulta: 2026-10-06
MCPMensagens de logging, níveis e logLevel por requisição.
Limites: Logging MCP não é armazenamento de auditoria imutável; evitar segredos nos logs.
- Transports overview — MCP 2026-07-28
Model Context Protocol • consulta: 2026-10-06
MCPJSON-RPC, stdio e Streamable HTTP; regras para transportes customizados.
Limites: HTTP+SSE legado não deve ser ensinado como o transporte remoto atual; streaming é opção do binding.