MCP (Model Context Protocol): O Guia Completo para Desenvolvedores

O Model Context Protocol (MCP) é um padrão aberto criado pela Anthropic que define como modelos de AI se comunicam com ferramentas externas, fontes de dados e serviços. Pense nele como o "USB-C da AI" - um conector universal que permite que qualquer agente de AI se comunique com qualquer ferramenta através de uma interface padronizada.

Desde o seu lançamento, o MCP ultrapassou 97 milhões de downloads mensais do SDK e foi adotado por todos os principais provedores de AI: Anthropic, OpenAI, Google, Microsoft e Amazon. Neste guia, exploraremos tudo o que você precisa saber para construir com MCP.

Por Que o MCP Existe

Antes do MCP, cada aplicação de AI precisava construir integrações personalizadas para cada ferramenta que queria usar. Quer que sua AI leia arquivos? Escreva código personalizado. Consultar um banco de dados? Mais código personalizado. Postar no Slack? Mais uma integração.

Isso criou um problema N×M: N aplicações de AI, cada uma precisando de M integrações personalizadas, levando a esforço duplicado e ecossistemas fragmentados.

O MCP resolve isso com um único protocolo que qualquer cliente de AI pode usar para se comunicar com qualquer servidor MCP:

Conceitos Fundamentais

O MCP possui três primitivas fundamentais:

1. Ferramentas (Tools)

Ferramentas são funções que a AI pode chamar. Representam ações como "criar um arquivo", "consultar um banco de dados" ou "enviar uma mensagem". Cada ferramenta tem um nome, uma descrição e um JSON Schema para seus parâmetros.

{
  name: "create_issue",
  description: "Create a new GitHub issue",
  inputSchema: {
    type: "object",
    properties: {
      title: { type: "string", description: "Issue title" },
      body: { type: "string", description: "Issue body" },
      repo: { type: "string", description: "Repository name" }
    },
    required: ["title", "repo"]
  }
}

2. Recursos (Resources)

Recursos são dados que a AI pode ler. Representam arquivos, registros de banco de dados, respostas de API ou qualquer outra fonte de dados. Os recursos são identificados por URIs.

{
  uri: "file:///Users/dev/project/README.md",
  name: "Project README",
  mimeType: "text/markdown"
}

3. Prompts

Prompts são templates reutilizáveis que ajudam a estruturar interações. Podem incluir parâmetros dinâmicos e são úteis para padronizar fluxos de trabalho comuns.

{
  name: "code_review",
  description: "Review code changes for quality and security",
  arguments: [
    { name: "diff", description: "The code diff to review", required: true }
  ]
}

Arquitetura

O MCP segue uma arquitetura cliente-servidor:

• Host: A aplicação de AI (Claude Desktop, Cursor, sua aplicação personalizada)
• Cliente: Mantém uma conexão 1:1 com um servidor MCP
• Servidor: Expõe ferramentas, recursos e prompts ao cliente
• Transporte: A comunicação acontece via JSON-RPC 2.0 sobre stdio (local) ou Server-Sent Events (remoto)

Construindo um Servidor MCP

Vamos construir um servidor MCP prático que interage com uma lista de tarefas armazenada em um arquivo JSON.

Configuração Inicial

mkdir mcp-todo-server && cd mcp-todo-server
npm init -y
npm install @modelcontextprotocol/sdk zod

Implementação do Servidor

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

const TODO_FILE = "./todos.json";

function readTodos(): { id: number; text: string; done: boolean }[] {
  if (!fs.existsSync(TODO_FILE)) return [];
  return JSON.parse(fs.readFileSync(TODO_FILE, "utf-8"));
}

function writeTodos(todos: { id: number; text: string; done: boolean }[]) {
  fs.writeFileSync(TODO_FILE, JSON.stringify(todos, null, 2));
}

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

// Tool: Add a todo
server.tool(
  "add_todo",
  "Add a new todo item",
  { text: z.string().describe("The todo text") },
  async ({ text }) => {
    const todos = readTodos();
    const newTodo = { id: Date.now(), text, done: false };
    todos.push(newTodo);
    writeTodos(todos);
    return { content: [{ type: "text", text: `Added: "${text}"` }] };
  }
);

// Tool: List todos
server.tool(
  "list_todos",
  "List all todo items",
  {},
  async () => {
    const todos = readTodos();
    const list = todos
      .map((t) => `${t.done ? "✅" : "⬜"} [${t.id}] ${t.text}`)
      .join("\n");
    return { content: [{ type: "text", text: list || "No todos yet." }] };
  }
);

// Tool: Complete a todo
server.tool(
  "complete_todo",
  "Mark a todo as completed",
  { id: z.number().describe("The todo ID to complete") },
  async ({ id }) => {
    const todos = readTodos();
    const todo = todos.find((t) => t.id === id);
    if (!todo) return { content: [{ type: "text", text: "Todo not found." }] };
    todo.done = true;
    writeTodos(todos);
    return { content: [{ type: "text", text: `Completed: "${todo.text}"` }] };
  }
);

// Resource: Current todos as a readable resource
server.resource(
  "todos://list",
  "Current todo list",
  async () => ({
    contents: [{
      uri: "todos://list",
      mimeType: "application/json",
      text: JSON.stringify(readTodos(), null, 2),
    }],
  })
);

// Start the server
const transport = new StdioServerTransport();
await server.connect(transport);

Configuração

Para usar este servidor com o Claude Desktop, adicione-o à sua configuração:

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

Construindo um Cliente MCP

Você também pode construir um cliente personalizado que se conecta a qualquer servidor MCP:

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const transport = new StdioClientTransport({
  command: "npx",
  args: ["tsx", "./src/index.ts"],
});

const client = new Client({ name: "my-client", version: "1.0.0" });
await client.connect(transport);

// List available tools
const { tools } = await client.listTools();
console.log("Available tools:", tools.map((t) => t.name));

// Call a tool
const result = await client.callTool({
  name: "add_todo",
  arguments: { text: "Write MCP blog post" },
});
console.log(result);

Servidores MCP Populares

O ecossistema MCP cresceu rapidamente. Aqui estão alguns dos servidores mais populares:

MCP vs A2A (Agent-to-Agent)

Enquanto o MCP lida com a comunicação agente-ferramenta, o protocolo A2A (Agent-to-Agent) do Google lida com a comunicação agente-agente. Eles são complementares:

• MCP: Como um agente de AI usa ferramentas (integração vertical)
• A2A: Como agentes de AI colaboram entre si (integração horizontal)

Boas Práticas

1. Mantenha os servidores focados: Um servidor por domínio (servidor GitHub, servidor Slack, etc.). Não construa servidores monolíticos.
2. Valide entradas com Zod: Sempre valide as entradas das ferramentas com schemas apropriados.
3. Trate erros com elegância: Retorne mensagens de erro significativas, não stack traces.
4. Use recursos para dados somente leitura: Se a AI só precisa ler dados, exponha-os como recurso em vez de ferramenta.
5. Adicione descrições adequadas: Boas descrições de ferramentas e parâmetros ajudam a AI a entender quando e como usar cada ferramenta.
6. Teste com o MCP Inspector: Use npx @modelcontextprotocol/inspector para testar seu servidor de forma interativa.

Primeiros Passos

# Create a new MCP server from template
npx @modelcontextprotocol/create-server my-server

# Test with the MCP Inspector
npx @modelcontextprotocol/inspector npx tsx ./src/index.ts

Conclusão

O MCP se tornou o padrão de facto para uso de ferramentas de AI em 2026. Seja construindo agentes de AI personalizados, estendendo o Claude Code ou criando integrações para plataformas existentes, entender o MCP é essencial. O protocolo é simples o suficiente para aprender em uma tarde, mas poderoso o suficiente para construir fluxos de trabalho de AI de nível de produção.

Próximos passos:

• Explore a Especificação MCP
• Navegue pelos servidores MCP existentes para inspiração
• Construa seu primeiro servidor com o SDK TypeScript ou Python
• Teste com o Claude Desktop ou o MCP Inspector