1~
2O **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.
3~
4Desde 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.
5~
6## Por Que o MCP Existe
7~
8Antes 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.
9~
10Isso 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.
11~
12```mermaid
13graph TD
14    subgraph "Before MCP (N×M)"
15        A1[AI App 1] --> T1[GitHub Integration]
16        A1 --> T2[Slack Integration]
17        A1 --> T3[DB Integration]
18        A2[AI App 2] --> T4[GitHub Integration]
19        A2 --> T5[Slack Integration]
20        A2 --> T6[DB Integration]
21    end
22```
23~
24O MCP resolve isso com um **único protocolo** que qualquer cliente de AI pode usar para se comunicar com qualquer servidor MCP:
25~
26```mermaid
27graph TD
28    subgraph "With MCP (N+M)"
29        A1[AI App 1] --> MCP[MCP Protocol]
30        A2[AI App 2] --> MCP
31        MCP --> S1[GitHub Server]
32        MCP --> S2[Slack Server]
33        MCP --> S3[DB Server]
34    end
35```
36~
37## Conceitos Fundamentais
38~
39O MCP possui três primitivas fundamentais:
40~
41### 1. Ferramentas (Tools)
42Ferramentas 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.
43~
44```typescript
45{
46  name: "create_issue",
47  description: "Create a new GitHub issue",
48  inputSchema: {
49    type: "object",
50    properties: {
51      title: { type: "string", description: "Issue title" },
52      body: { type: "string", description: "Issue body" },
53      repo: { type: "string", description: "Repository name" }
54    },
55    required: ["title", "repo"]
56  }
57}
58```
59~
60### 2. Recursos (Resources)
61Recursos 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.
62~
63```typescript
64{
65  uri: "file:///Users/dev/project/README.md",
66  name: "Project README",
67  mimeType: "text/markdown"
68}
69```
70~
71### 3. Prompts
72Prompts 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.
73~
74```typescript
75{
76  name: "code_review",
77  description: "Review code changes for quality and security",
78  arguments: [
79    { name: "diff", description: "The code diff to review", required: true }
80  ]
81}
82```
83~
84## Arquitetura
85~
86O MCP segue uma arquitetura cliente-servidor:
87~
88```mermaid
89graph LR
90    subgraph "Host Application"
91        Client[MCP Client]
92    end
93~
94    subgraph "MCP Server"
95        Server[Server Process]
96        Server --> Tools[Tools]
97        Server --> Resources[Resources]
98        Server --> Prompts[Prompts]
99    end
100~
101    Client -- "JSON-RPC 2.0\n(stdio or SSE)" --> Server
102```
103~
104- **Host**: A aplicação de AI (Claude Desktop, Cursor, sua aplicação personalizada)
105- **Cliente**: Mantém uma conexão 1:1 com um servidor MCP
106- **Servidor**: Expõe ferramentas, recursos e prompts ao cliente
107- **Transporte**: A comunicação acontece via JSON-RPC 2.0 sobre stdio (local) ou Server-Sent Events (remoto)
108~
109## Construindo um Servidor MCP
110~
111Vamos construir um servidor MCP prático que interage com uma lista de tarefas armazenada em um arquivo JSON.
112~
113### Configuração Inicial
114~
115```bash
116mkdir mcp-todo-server && cd mcp-todo-server
117npm init -y
118npm install @modelcontextprotocol/sdk zod
119```
120~
121### Implementação do Servidor
122~
123```typescript
124// src/index.ts
125import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
126import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
127import { z } from "zod";
128import fs from "fs";
129~
130const TODO_FILE = "./todos.json";
131~
132function readTodos(): { id: number; text: string; done: boolean }[] {
133  if (!fs.existsSync(TODO_FILE)) return [];
134  return JSON.parse(fs.readFileSync(TODO_FILE, "utf-8"));
135}
136~
137function writeTodos(todos: { id: number; text: string; done: boolean }[]) {
138  fs.writeFileSync(TODO_FILE, JSON.stringify(todos, null, 2));
139}
140~
141const server = new McpServer({
142  name: "todo-server",
143  version: "1.0.0",
144});
145~
146// Tool: Add a todo
147server.tool(
148  "add_todo",
149  "Add a new todo item",
150  { text: z.string().describe("The todo text") },
151  async ({ text }) => {
152    const todos = readTodos();
153    const newTodo = { id: Date.now(), text, done: false };
154    todos.push(newTodo);
155    writeTodos(todos);
156    return { content: [{ type: "text", text: `Added: "${text}"` }] };
157  }
158);
159~
160// Tool: List todos
161server.tool(
162  "list_todos",
163  "List all todo items",
164  {},
165  async () => {
166    const todos = readTodos();
167    const list = todos
168      .map((t) => `${t.done ? "✅" : "⬜"} [${t.id}] ${t.text}`)
169      .join("\n");
170    return { content: [{ type: "text", text: list || "No todos yet." }] };
171  }
172);
173~
174// Tool: Complete a todo
175server.tool(
176  "complete_todo",
177  "Mark a todo as completed",
178  { id: z.number().describe("The todo ID to complete") },
179  async ({ id }) => {
180    const todos = readTodos();
181    const todo = todos.find((t) => t.id === id);
182    if (!todo) return { content: [{ type: "text", text: "Todo not found." }] };
183    todo.done = true;
184    writeTodos(todos);
185    return { content: [{ type: "text", text: `Completed: "${todo.text}"` }] };
186  }
187);
188~
189// Resource: Current todos as a readable resource
190server.resource(
191  "todos://list",
192  "Current todo list",
193  async () => ({
194    contents: [{
195      uri: "todos://list",
196      mimeType: "application/json",
197      text: JSON.stringify(readTodos(), null, 2),
198    }],
199  })
200);
201~
202// Start the server
203const transport = new StdioServerTransport();
204await server.connect(transport);
205```
206~
207### Configuração
208~
209Para usar este servidor com o Claude Desktop, adicione-o à sua configuração:
210~
211```json
212{
213  "mcpServers": {
214    "todo": {
215      "command": "npx",
216      "args": ["tsx", "/path/to/mcp-todo-server/src/index.ts"]
217    }
218  }
219}
220```
221~
222## Construindo um Cliente MCP
223~
224Você também pode construir um cliente personalizado que se conecta a qualquer servidor MCP:
225~
226```typescript
227import { Client } from "@modelcontextprotocol/sdk/client/index.js";
228import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
229~
230const transport = new StdioClientTransport({
231  command: "npx",
232  args: ["tsx", "./src/index.ts"],
233});
234~
235const client = new Client({ name: "my-client", version: "1.0.0" });
236await client.connect(transport);
237~
238// List available tools
239const { tools } = await client.listTools();
240console.log("Available tools:", tools.map((t) => t.name));
241~
242// Call a tool
243const result = await client.callTool({
244  name: "add_todo",
245  arguments: { text: "Write MCP blog post" },
246});
247console.log(result);
248```
249~
250## Servidores MCP Populares
251~
252O ecossistema MCP cresceu rapidamente. Aqui estão alguns dos servidores mais populares:
253~
254| Servidor | Descrição | Caso de Uso |
255|----------|-----------|-------------|
256| **GitHub** | Criar issues, PRs, gerenciar repos | Fluxos de trabalho de desenvolvimento |
257| **Slack** | Enviar mensagens, gerenciar canais | Comunicação da equipe |
258| **PostgreSQL** | Consultar e gerenciar bancos de dados | Acesso a dados |
259| **Filesystem** | Ler, escrever e pesquisar arquivos | Desenvolvimento local |
260| **Puppeteer** | Automação de navegador e scraping | Testes web |
261| **Sentry** | Monitoramento de erros e depuração | Suporte em produção |
262| **Supabase** | Banco de dados, auth, armazenamento | Operações de backend |
263~
264## MCP vs A2A (Agent-to-Agent)
265~
266Enquanto 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:
267~
268```mermaid
269graph TD
270    Agent1[Agent 1] -- "A2A Protocol" --> Agent2[Agent 2]
271    Agent1 -- "MCP Protocol" --> Tool1[GitHub MCP Server]
272    Agent2 -- "MCP Protocol" --> Tool2[Database MCP Server]
273```
274~
275- **MCP**: Como um agente de AI usa ferramentas (integração vertical)
276- **A2A**: Como agentes de AI colaboram entre si (integração horizontal)
277~
278## Boas Práticas
279~
2801. **Mantenha os servidores focados**: Um servidor por domínio (servidor GitHub, servidor Slack, etc.). Não construa servidores monolíticos.
2812. **Valide entradas com Zod**: Sempre valide as entradas das ferramentas com schemas apropriados.
2823. **Trate erros com elegância**: Retorne mensagens de erro significativas, não stack traces.
2834. **Use recursos para dados somente leitura**: Se a AI só precisa ler dados, exponha-os como recurso em vez de ferramenta.
2845. **Adicione descrições adequadas**: Boas descrições de ferramentas e parâmetros ajudam a AI a entender quando e como usar cada ferramenta.
2856. **Teste com o MCP Inspector**: Use `npx @modelcontextprotocol/inspector` para testar seu servidor de forma interativa.
286~
287## Primeiros Passos
288~
289```bash
290# Create a new MCP server from template
291npx @modelcontextprotocol/create-server my-server
292~
293# Test with the MCP Inspector
294npx @modelcontextprotocol/inspector npx tsx ./src/index.ts
295```
296~
297## Conclusão
298~
299O 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.
300~
301**Próximos passos:**
302- Explore a [Especificação MCP](https://spec.modelcontextprotocol.io/)
303- Navegue pelos [servidores MCP existentes](https://github.com/modelcontextprotocol/servers) para inspiração
304- Construa seu primeiro servidor com o SDK TypeScript ou Python
305- Teste com o Claude Desktop ou o MCP Inspector
306~