Ferramenta gratuita

De API REST a servidor MCP em TypeScript

O que realmente é preciso para expor uma API REST como servidor MCP em TypeScript: o SDK, uma ferramenta que funciona e a parte que decide se um agente a usa direito.

SDK oficial modelcontextprotocol/typescript-sdk
Instalação
npm install @modelcontextprotocol/sdk zod
Uma ferramenta MCP funcional em TypeScript 
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";

const server = new McpServer({ name: "my-server", version: "1.0.0" });

server.tool(
  "get_order",
  "Look up one order by its id and return its current status.",
  { orderId: z.string().describe("The order id to look up") },
  async ({ orderId }) => ({ content: [{ type: "text", text: await fetchOrder(orderId) }] })
);
Teste o que você criou Gere ferramentas a partir de uma spec OpenAPI

Funciona. Só que mais ninguém vê isso.

Um servidor que funciona é onde o esforço termina e a venda começa. Aponte o MCP Showcase para ele e tenha um playground ao vivo que seus clientes podem experimentar, com documentação gerada para cada ferramenta.

Comece Gratuitamente Explore o diretório de servidores MCP

Como funciona

link
Instale o SDK

Mostrado acima, junto com a informação de ser mantido oficialmente ou ser um projeto da comunidade, o que pesa mais em algumas linguagens do que em outras.

play_circle
Encapsule um endpoint

Comece com uma única ferramenta, não com toda a sua API. As definições de ferramentas são enviadas ao modelo a cada requisição, e o acerto na escolha cai conforme a lista cresce.

checklist
Teste antes de conectar um agente

Passe a URL publicada pelo MCP Inspector para confirmar que o handshake completa e que as ferramentas aparecem como você pretendia.

O SDK de TypeScript

npm install @modelcontextprotocol/sdk zod — modelcontextprotocol/typescript-sdk, mantido oficialmente.

Seu esquema Zod é o contrato que o modelo vê

O SDK de TypeScript constrói o JSON Schema a partir do Zod, então `.describe()` em cada campo não é documentação para os seus colegas: é o que diz ao modelo o que colocar ali. Esquemas escritos sem isso validam perfeitamente e deixam o agente adivinhando em cada parâmetro.

Encapsular um endpoint REST

Um servidor MCP é uma camada fina sobre código que você já tem. Cada ferramenta precisa de três coisas: um nome, uma descrição dizendo o que ela faz e quando escolhê-la, e um esquema de entrada. O SDK de TypeScript cuida do protocolo; o que você escreve é o mapeamento desses argumentos para a sua chamada HTTP existente.

Comece por um endpoint em vez de toda a sua API. As definições de ferramentas são reenviadas ao modelo a cada requisição, então cada uma é um custo de contexto permanente, e o acerto do modelo ao escolher cai conforme a lista cresce. Oito ferramentas bem descritas valem mais que oitenta.

A parte que não é sobre TypeScript

Seja qual for a linguagem, são as descrições que decidem se o agente se comporta. Elas são lidas pelo modelo, não pelos seus colegas, e uma ferramenta descrita em três palavras é chamada no chute. Você pode conferir as suas com o linter de esquemas MCP e ver quanto a lista custa por requisição com a calculadora de tokens.

Ferramentas e guias relacionados

Um servidor que funciona é metade do trabalho

Depois que ele roda, resta o problema de ninguém conseguir dizer o que ele faz. Um prospect não consegue ler o seu código TypeScript e não vai instalar um cliente para descobrir. O MCP Showcase aponta para a mesma URL e produz um playground ao vivo com documentação gerada para cada ferramenta, para que avaliar o seu servidor custe um clique.

Perguntas frequentes

Encapsule em uma ferramenta cada endpoint que um agente deva alcançar: um nome, uma frase dizendo o que ela faz e quando usá-la, e um esquema de entrada. O SDK de TypeScript cuida do protocolo; o que você escreve é o mapeamento dos argumentos da ferramenta para a sua chamada HTTP existente.

Não, e esse é o erro mais comum. As definições de ferramentas são reenviadas a cada requisição: oitenta endpoints são oitenta descrições na janela de contexto de cada turno, e a capacidade do modelo de escolher a certa cai bastante conforme a lista cresce. Comece pelas poucas de que um agente realmente precisa.

O selo acima do código informa. Onde não há SDK oficial, as opções da comunidade acompanham a especificação com fidelidade variável: confira quando a biblioteca seguiu uma revisão do protocolo pela última vez, principalmente em transportes, antes de construir sobre ela.

Streamable HTTP para tudo o que estiver publicado. Os clientes cada vez mais tentam esse primeiro e alguns já não recorrem ao antigo HTTP+SSE, o que aparece como um cliente que simplesmente não vê o seu servidor, e não como um erro.

Você não descobre relendo o próprio código, porque já sabe o que as ferramentas fazem. Passe o servidor pelo linter de esquemas: ele analisa as descrições e os esquemas de entrada do jeito que um modelo os lê e sinaliza os que fariam um agente adivinhar.

Mais ferramentas MCP gratuitas

MCP Inspector online

Cole a URL de um servidor MCP e veja todas as ferramentas, recursos e prompts expostos, com esquemas completos e o log de requisições. Nada para instalar.
Testador de servidor MCP

Confirme que o seu servidor MCP funciona de verdade. Cole a URL e receba um relatório de aprovado/reprovado sobre a conexão, o handshake, o transporte e as ferramentas anunciadas.
Scanner de segurança MCP

Antes de apontar um agente para um servidor MCP, veja o que ele está pedindo. Nota de A a F em transporte, autenticação, indícios de tool poisoning e parâmetros perigosos.
Calculadora de tokens MCP

Definições de ferramentas são enviadas em toda requisição, não uma única vez. Cole a URL do seu servidor MCP e veja quantos tokens são, quais ferramentas pesam mais e quanto custa.
Ver todas as ferramentas gratuitas