Seu primeiro servidor MCP em 20 minutos

O que o MCP realmente é

Model Context Protocol é o padrão aberto da Anthropic para dar aos assistentes de IA acesso estruturado a ferramentas e dados externos. Pense nele como um contrato de API bem tipado entre o seu host de modelo (Claude Code, Cursor, etc.) e qualquer capacidade que você queira expor: um banco de dados, um web scraper, um observador de arquivos, um bot do Slack, um gatilho de CI.

Quando você constrói um servidor MCP, você está construindo uma ponte. O modelo chama suas ferramentas pelo nome com argumentos estruturados; seu servidor executa e retorna resultados estruturados. Chega de "acesse esta URL e me diga o que você vê" — apenas chamadas de função tipadas.

Pré-requisitos

• Node.js 22+
• Uma configuração de Claude Code ou Cursor que suporte MCP
• 20 minutos

Passo 1: Estruturar o servidor

mkdir my-mcp-server && cd my-mcp-server
npm init -y
npm install @modelcontextprotocol/sdk zod
npm install -D typescript @types/node tsx

Crie o tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "outDir": "./dist",
    "strict": true
  }
}

Passo 2: Escreva sua primeira ferramenta

Crie src/index.ts:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

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

// Tool: fetch and summarize a URL's title
server.tool(
  "get_page_title",
  "Fetches the <title> tag from a given URL",
  { url: z.string().url().describe("The URL to fetch") },
  async ({ url }) => {
    try {
      const res = await fetch(url, { signal: AbortSignal.timeout(5000) });
      const html = await res.text();
      const match = html.match(/<title[^>]*>(.*?)<\/title>/is);
      const title = match?.[1]?.trim() ?? "No title found";
      return { content: [{ type: "text", text: title }] };
    } catch (err) {
      return {
        content: [{ type: "text", text: `Error: ${String(err)}` }],
        isError: true,
      };
    }
  }
);

// Tool: simple math evaluator
server.tool(
  "calculate",
  "Evaluates a safe arithmetic expression",
  { expression: z.string().describe("e.g. '2 + 2 * 10'") },
  async ({ expression }) => {
    // Only allow digits, operators, spaces, parens
    if (!/^[0-9+\-*/.() ]+$/.test(expression)) {
      return {
        content: [{ type: "text", text: "Invalid expression" }],
        isError: true,
      };
    }
    const result = Function(`"use strict"; return (${expression})`)();
    return { content: [{ type: "text", text: String(result) }] };
  }
);

async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
}

main().catch(console.error);

Passo 3: Conectar ao Claude Code

Adicione à sua configuração MCP do Claude Code (geralmente ~/.claude/mcp.json ou o .mcp.json do workspace):

{
  "mcpServers": {
    "my-first-mcp": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/my-mcp-server/src/index.ts"]
    }
  }
}

Reinicie o Claude Code. Abra a paleta de ferramentas — suas duas ferramentas devem aparecer.

Passo 4: Teste sem um host

Use o inspetor MCP:

npx @modelcontextprotocol/inspector tsx src/index.ts

Isso abre uma UI local onde você pode invocar suas ferramentas, inspecionar schemas e ver mensagens JSON-RPC brutas. Essencial para depurar antes de conectar a um host real.

O que construir a seguir

Depois de dominar o padrão, servidores MCP se destacam em:

• Memória persistente — leia/escreva em um armazenamento JSON local para que seu agente lembre o contexto entre sessões
• Busca ciente do projeto — exponha busca semântica sobre seu código via embeddings
• APIs internas — envolva qualquer API da empresa em uma interface tipada limpa que o modelo pode chamar
• Controle do navegador — envolva o Playwright para interação web estruturada
• Hooks de CI — acione builds, leia resultados de testes, abra PRs de dentro do seu loop de agente

A percepção-chave

MCP transforma seu agente de uma interface de chat em um runtime programável. O modelo para de descrever o que faria e começa a realmente fazer — por meio de suas chamadas de função tipadas, auditáveis e registradas. Esse é o salto do vibecoding para a construção de sistemas agenticos reais.

20 minutos para sua primeira ferramenta. O resto é escopo.