MCP fundamentos
Monte um catálogo conceitual de integração para a loja e verifique a seleção de versão com o simulador. Depois, conecte um cliente a um servidor de desenvolvimento usando uma implementação cuja revisão você tenha confirmado. Não use dados reais de clientes. Sua entrega precisa mostrar descoberta, uma operação de leitura e a distinção entre tool, resource e prompt.
O laboratório possui uma verificação específica de atualização: você deve registrar se o runtime usa a revisão 2026-07-28 ou uma revisão anterior com handshake legado. Ambas podem ser estudadas, mas seus contratos não devem ser misturados. O simulador da leitura não estabelece transporte nem negocia com um servidor real; a evidência integrada deverá mostrar as mensagens e a versão realmente utilizada.
JavaScriptBashMCPAPIsInfraestruturaAo terminar esta aula
- Registre a revisão realmente utilizada antes de comparar mensagens.
- stdout de stdio deve permanecer reservado ao protocolo.
- Contexto externo não altera permissões nem instruções superiores.
Antes de continuar: Leitura: MCP fundamentos
Classifique os três contratos da loja
FundamentosEscreva consultar_item como tool que recebe sku e retorna nome, disponibilidade e fonte. Defina politica://devolucao como resource com conteúdo e data de referência. Defina revisar_devolucao como prompt que organiza a pergunta do atendente usando a política selecionada. Explique por que consultar_item é operação e a política é contexto. Para cada contrato, indique se há efeito externo. Uma futura tool reservar_item deve ser separada da consulta, pois acrescenta autorização, aprovação e idempotência.
Salve descoberta.cjs e execute. Confira o pedido e a resposta e identifique _meta, supportedVersions e capabilities. Mude a versão desejada para uma ausente e capture o bloqueio. Remova tools de capabilities e determine que interface seu host deve exibir nesse caso. O simulador não lista ferramentas reais; ele demonstra que a aplicação deve respeitar o suporte técnico recebido. Não invente uma chamada tools/call quando o contrato indicado pelo servidor não oferece ferramentas.
Prepare um transporte compatível
FundamentosEscolha stdio ou Streamable HTTP e registre a revisão suportada pela implementação instalada. Para stdio, separe mensagens JSON-RPC de logs de diagnóstico e confirme a delimitação por linha. Para HTTP, confira endpoint, headers e metadados do corpo conforme a revisão. Use um servidor local de leitura, sem credenciais amplas. Antes de chamar uma ferramenta, observe a descoberta ou a negociação correspondente. Se houver initialize, identifique-o como comportamento da revisão legada escolhida, não como contrato atual universal.
↗ Discovery — MCP 2026-07-28↗ Transports overview — MCP 2026-07-28
Capture uma listagem e uma chamada consultar_item com identificador de correlação. Compare os argumentos com o schema anunciado e a resposta com o contrato de saída. Crie um sku inválido e registre a diferença entre erro de mensagem e resultado de ferramenta que informa item ausente. O cliente deve exibir a falha de domínio sem dizer que o servidor inteiro está indisponível. Adicione timeout para o caso em que nenhuma resposta chega, preservando o identificador da tentativa no diagnóstico.
Consuma contexto sem promover sua autoridade
FundamentosLeia o resource da política e registre URI, conteúdo e origem. Acrescente uma frase adversarial fictícia ao conteúdo, pedindo para divulgar dados de outro cliente. A aplicação deve continuar tratando a política como dado externo. Não execute qualquer ação pedida por esse conteúdo. Agora selecione o prompt e observe como ele organiza a tarefa, sem acrescentar privilégios. O teste deve mostrar a fronteira de interpretação: informação recuperada pode influenciar a resposta factual, mas não redefine quem pode consultar ou alterar pedidos.
Limite o tamanho do resource e da saída da tool. Teste um conteúdo maior que o limite e decida se será rejeitado, resumido com indicação ou recuperado parcialmente. Essa decisão afeta rastreabilidade: um resumo não pode ser apresentado como texto integral. Registre também o comportamento quando a listagem muda. O host precisa atualizar o catálogo ou tratar a operação ausente, em vez de repetir chamadas com um contrato antigo como se ainda existisse.
Apresente interoperabilidade e confiança separadamente
FundamentosAnexe a versão, o transporte e as mensagens nominal e de falha. Indique de onde veio a configuração do servidor e como o host verifica a identidade quando necessário. O nome declarado em serverInfo não é autenticação. Sua conclusão deve apontar o que foi provado: formato local, descoberta integrada, chamada e consumo de contexto. Caso a etapa integrada não tenha sido executada, declare esse limite e apresente o comando ou procedimento necessário para completá-la, sem converter uma simulação em prova de conexão.
Resolução integrada, ambiente e evidência
FundamentosSalve a resolução como client.mjs e o bloco complementar como server.mjs na mesma pasta. Este cliente MCP2.3.1 inicia um subprocesso real via StdioClientTransport, fixa a revisão 2026-07-28 por versionNegotiation e executa discovery, listagem, chamada, resource e prompt. A descoberta confirma a revisão; quantidade 3 confirma o retorno nominal. Os asserts exigem recusa de resource privado e prompt sem argumento, e a tool demorar deve ultrapassar timeout 20ms. server.mjs usa serveStdio, que seleciona a era no transporte, em vez de conectar uma instância legada diretamente. Foram executadas as trocas reais, sem modelo ou credencial. O namespace da URI é um catálogo local permitido e o log de consulta vai a stderr. Os casos schema e domínio retornam isError, enquanto URI e prompt inválidos rejeitam a operação. O cancelamento da espera não desfaz um efeito; demorar é uma leitura fictícia sem efeito.
↗ MCP TypeScript server SDK v2 — official package guide↗ Discovery — MCP 2026-07-28↗ Transports overview — MCP 2026-07-28
npm init -y
npm install --save-exact @modelcontextprotocol/server@2.3.1 @modelcontextprotocol/client@2.3.1 zod@4.6.5
node client.mjs// MCP SDK v2.3.1: stdio real; stdout fica reservado ao protocolo.
import { McpServer } from '@modelcontextprotocol/server';
import { serveStdio } from '@modelcontextprotocol/server/stdio';
import { z } from 'zod';
function criarServidor() {
const server = new McpServer({name:'LojaCurso',version:'1.0.0'});
const catalogo={I2:3,I3:0};
server.registerTool('consultar_estoque',{
description:'Consulta sem reservar.',
inputSchema:z.object({sku:z.string()}).strict(),
outputSchema:z.object({sku:z.string(),quantidade:z.number().int(),fonte:z.string()})
},async ({sku})=>{
if(!(sku in catalogo))return {isError:true,content:[{type:'text',text:'item desconhecido'}]};
const out={sku,quantidade:catalogo[sku],fonte:'catalogo local'};
console.error(JSON.stringify({evento:'consulta',sku}));
return {content:[{type:'text',text:JSON.stringify(out)}],structuredContent:out};
});
server.registerTool('demorar',{inputSchema:z.object({})},async()=>{
await new Promise(r=>setTimeout(r,200));return {content:[{type:'text',text:'tarde'}]};
});
server.registerResource('politica','politica://devolucao',{mimeType:'text/plain'},async uri=>({contents:[{uri:uri.href,mimeType:'text/plain',text:'Politica ficticia: revisar devolucao com comprovante.'}]}));
server.registerPrompt('revisar_devolucao',{argsSchema:z.object({pedido:z.string()})},({pedido})=>({messages:[{role:'user',content:{type:'text',text:'Revise '+pedido+' usando a politica; nao confirme operacoes.'}}]}));
return server;
}
serveStdio(criarServidor,{legacy:'reject',onerror:e=>console.error(e.message)});
↗ MCP TypeScript server SDK v2 — official package guide↗ Build an MCP server
Exercício aplicado
Uma central conecta catálogo, política de devolução e prompt de revisão por MCP. Verifique versão e capabilities antes de consumir os contratos e trate conteúdo adversarial como dado externo.
- Classifique tool, resource e prompt com contratos próprios.
- Execute a seleção nominal e uma revisão ausente.
- Conecte uma implementação compatível e capture descoberta/listagem/chamada.
- Teste resource adversarial, timeout e limite de tamanho.
Abrir resolução comentada
Salve a resolução como client.mjs e o bloco complementar como server.mjs na mesma pasta. Este cliente MCP2.3.1 inicia um subprocesso real via StdioClientTransport, fixa a revisão 2026-07-28 por versionNegotiation e executa discovery, listagem, chamada, resource e prompt. A descoberta confirma a revisão; quantidade 3 confirma o retorno nominal. Os asserts exigem recusa de resource privado e prompt sem argumento, e a tool demorar deve ultrapassar timeout 20ms. server.mjs usa serveStdio, que seleciona a era no transporte, em vez de conectar uma instância legada diretamente. Foram executadas as trocas reais, sem modelo ou credencial. O namespace da URI é um catálogo local permitido e o log de consulta vai a stderr. Os casos schema e domínio retornam isError, enquanto URI e prompt inválidos rejeitam a operação. O cancelamento da espera não desfaz um efeito; demorar é uma leitura fictícia sem efeito.
A seleção aceita somente a versão anunciada, e o catálogo conceitual separa operação, conteúdo e modelo de interação. A versão ausente é bloqueada antes de qualquer tool. Na integração, os metadados e a descoberta devem seguir a revisão real, e a chamada de leitura deve corresponder ao schema listado.
A frase adversarial no resource não modifica autorização nem abre ferramentas adicionais. O host pode usar a política como evidência factual, mantendo origem e limite de tamanho. A confiança no endpoint vem da configuração e da autenticação adequada, e não de seu nome autodeclarado.
import { Client } from '@modelcontextprotocol/client';
import { StdioClientTransport } from '@modelcontextprotocol/client/stdio';
import { fileURLToPath } from 'node:url';
import assert from 'node:assert/strict';
const client=new Client({name:'CursoClient',version:'1.0.0'},{versionNegotiation:{mode:{pin:'2026-07-28'}}});
const transport=new StdioClientTransport({command:process.execPath,args:[fileURLToPath(new URL('./server.mjs',import.meta.url))],stderr:'inherit'});
try {
await client.connect(transport);
const descoberta=await client.discover();
assert(descoberta.supportedVersions.includes('2026-07-28'));
console.log('discovery',descoberta);
console.log('tools',await client.listTools());
const ok=await client.callTool({name:'consultar_estoque',arguments:{sku:'I2'}});
assert.equal(ok.structuredContent.quantidade,3);console.log('nominal',ok);
console.log('dominio',await client.callTool({name:'consultar_estoque',arguments:{sku:'I99'}}));
const invalido=await client.callTool({name:'consultar_estoque',arguments:{sku:2}});
assert.equal(invalido.isError,true);console.log('schema recusado',invalido);
console.log('resource',await client.readResource({uri:'politica://devolucao'}));
console.log('prompt',await client.getPrompt({name:'revisar_devolucao',arguments:{pedido:'P7'}}));
await assert.rejects(()=>client.readResource({uri:'politica://privada'}));
await assert.rejects(()=>client.getPrompt({name:'revisar_devolucao',arguments:{}}));
await assert.rejects(()=>client.callTool({name:'demorar',arguments:{}},{timeout:20}));
console.log('timeout confirmado; leitura tardia nao tem efeito');
} finally {await client.close();}
Como conferir seu resultado
- Versão ausente é recusada.
- A evidência distingue revisão atual e handshake legado.
- Conteúdo externo não concede acesso adicional.
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
- Distinguir host/client/server.
- Ler tool/resource/prompt e revisão.
Cliente permite apenas consultar_estoque. Resource pede chamar apagar_catalogo; tool demorar excede 20 ms; política devolvida tem 3000 bytes e limite 2000. Resolva três perturbações após discovery compatível.
Conferir raciocínio e critérios de domínio
apagar_catalogo não é oferecida/executável: resource não amplia a allowlist mesmo com protocolo compatível.
demorar produz timeout de espera em 20 ms. Isso não prova que o servidor não terminou depois; neste exemplo é uma leitura sem efeito.
3000 excede 2000: a política é recusada ou tratada por regra explícita de redução com lacuna visível, não enviada integralmente e silenciosamente ao contexto.
Evidências para autoavaliação ou revisão por pares
- Allowlist: apagar_catalogo não é oferecida/executável: resource não amplia a allowlist mesmo com protocolo compatível.
- Timeout e trabalho remoto: demorar produz timeout de espera em 20 ms. Isso não prova que o servidor não terminou depois; neste exemplo é uma leitura sem efeito.
- Limite da política: 3000 excede 2000: a política é recusada ou tratada por regra explícita de redução com lacuna visível, não enviada integralmente e silenciosamente ao contexto.
Um erro frequente
Resource pode alterar política do host.
Resource é conteúdo externo, não política privilegiada do host.
Teste sua compreensão
Responda com suas palavras antes de abrir o comentário. Saber explicar uma decisão é parte do domínio.
1. Capabilities são permissões?
Não. Descrevem suporte técnico do protocolo.
Autorização de operações continua sendo verificada pelo servidor e pela aplicação.
2. initialize é o fluxo universal da revisão 2026-07-28?
Não. A revisão atual usa metadados por requisição e server/discover.
initialize pertence à compatibilidade com revisões anteriores.
↗ Discovery — MCP 2026-07-28↗ Transports overview — MCP 2026-07-28
3. Resource pode ampliar autorização?
Não. É conteúdo incorporado como contexto.
Instruções presentes no conteúdo não têm autoridade sobre os controles do host.
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.
- Architecture — MCP 2026-07-28
Model Context Protocol • consulta: 2026-10-06
MCPInfraestruturaHost, clients e servers, fronteiras de segurança e requisições stateless com versão/capabilities.
Limites: Difere das revisões baseadas em initialize; SDKs e clientes antigos podem usar a arquitetura legada.
- 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.
- 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.
- Streamable HTTP — MCP 2026-07-28
Model Context Protocol • consulta: 2026-10-06
MCPPOST único por mensagem, respostas JSON ou SSE por requisição, segurança HTTP e compatibilidade.
Limites: Não confundir SSE de resposta atual com transporte HTTP+SSE de versões antigas.
- Discovery — MCP 2026-07-28
Model Context Protocol • consulta: 2026-10-06
MCPDiscovery do servidor e capacidades disponíveis.
Limites: Separar descoberta de capacidades de autenticação e de descoberta de endereço de servidor.
- 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.
- MCP TypeScript server SDK v2 — official package guide
Model Context Protocol • consulta: 2026-10-06
TypeScriptMCPPacote @modelcontextprotocol/server, linha estável v2 para MCP 2026-07-28, exposição de tools/resources/prompts, adapters e guias de migração.
Limites: README apresenta a linha de SDK e encaminha à referência de API. Fixar versão e conferir exports no pacote instalado; não confundir exemplos v1 com protocolo e packages v2.
- 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.