Construindo um servidor MCP mínimo

Um servidor mínimo expõe uma capacidade restrita com argumentos e resultados previsíveis. Comece com estoque fictício e sem gravações.

Este é um laboratório conceitual ou externo. Não pressupõe que o aplicativo exponha todos os controles descritos.

Como funciona, passo a passo

Manipulador de demonstração e testes

O manipulador de demonstração abaixo usa apenas dados fictícios. Para um servidor MCP real, registre-o com o SDK e o transporte escolhidos e, em seguida, teste a descoberta e as chamadas com um cliente compatível. stdio se adapta aos subprocessos locais; HTTP streamável é adequado para endpoints remotos. Verifique explicitamente a compatibilidade com SSE herdado ou revisões mais recentes.

const stock = new Map([['LX-240', 3], ['P-12', 5], ['A-7', 2]]);

function getProductStock(input) {
    if (!input || typeof input.sku !== 'string' || !input.sku.trim())
        throw new TypeError('A nonempty sku is required.');
    const sku = input.sku.trim();
    return stock.has(sku)
        ? { status: 'found', sku, quantity: stock.get(sku), synthetic: true }
        : { status: 'not_found', sku, synthetic: true };
}

console.log(getProductStock({ sku: 'LX-240' }));
// { status: 'found', sku: 'LX-240', quantity: 3, synthetic: true }

O esquema explicativo

Siga as setas sólidas para o fluxo principal. As setas azuis tracejadas fornecem dados ou contexto; setas rosa tracejadas mostram feedback ou retorno de resultados. Cores e formas distinguem modelos, lojas, decisões e resultados. Em telas pequenas, role na horizontal para acompanhar o esquema completo.

Um exemplo completo

get_product_stock aceita um sku de string. LX-240 retorna quantidade=3; SKU desconhecido retorna not_found em vez de zero. Um servidor real também verifica as permissões do catálogo.

{"name":"get_product_stock","description":"Read fictional stock; never reserve it","inputSchema":{"type":"object","properties":{"sku":{"type":"string","minLength":1}},"required":["sku"],"additionalProperties":false}}

Experimente você mesmo

1. Implemente o contrato usando o fixture e teste entradas ausentes, desconhecidas e válidas.
2. Registre a entrada, a fonte e o resultado esperado antes de executar o experimento. Use apenas os dados fictícios do exemplo.
3. Siga as etapas do diagrama. A cada passo registre quais informações são recebidas e produzidas; não confunda o resultado intermediário com o resultado final.
4. Repita após remover as informações necessárias ou tornar a entrada ambígua. Verifique se o sistema esclarece, interrompe ou inventa uma resposta.
5. Compare com a solução explicada. Guarde a configuração, data, resultado e explicação das diferenças. Mude uma coisa e teste novamente.

Uma solução explicada

O contrato distingue encontrado, não encontrado e falha para que os clientes não precisem adivinhar. Um exercício bem-sucedido permite mostrar a conexão entre entradas, etapas e resultados. Quando falta informação, uma resposta cautelosa é mais útil do que detalhes inventados. Compare mais do que estilo: verifique também as condições, fontes e operações.

Quando esta abordagem ajuda e quais são seus limites

Pin SDK e revisão de protocolo; um exemplo de contrato não é um aperto de mão completo. Escolha esta abordagem quando ela melhorar uma necessidade medida. Mantenha uma linha de base simples e compare os resultados usando dados idênticos. Um exemplo de sucesso não estabelece confiabilidade em todas as situações.

Verifique o que aprendeu

Um servidor com ferramentas oferece recursos e prompts automaticamente?

Não. Os recursos são opcionais e devem ser descobertos e verificados.

Quem executa uma chamada proposta pelo modelo?

O aplicativo ou serviço de host após a validação. O modelo não obtém automaticamente acesso irrestrito.

Que resultado este exercício deve produzir?

O contrato distingue encontrado, não encontrado e falha para que os clientes não precisem adivinhar.

Termos para lembrar

• Servidor MCP: um serviço que expõe recursos por meio do Model Context Protocol.
• Chamada de ferramenta: uma solicitação estruturada para usar um recurso externo.
• Autorizar / Autorização: Verificando o direito de acesso a uma operação ou recurso.

Fontes e sua próxima etapa

• Model Context Protocol — Specification
• LangGraph — Fluxos de trabalho e agentes
• OWASP — Injeção de prompt

Para preparar: M03 — Segurança e solução de problemas do MCP