Aula/documento sobre a diferença entre API, MCP e Claude Code…

INEMA

"@modelcontextprotocol/sdk": "latest", "zod": "latest" }, "devDependencies": { "@types/node": "latest", "tsx": "latest", "typescript": "latest" } } ``` Depois rode:

bash npm run start

Ele provavelmente não vai mostrar nada no terminal, porque MCP via stdio espera ser chamado por um cliente MCP. Isso é normal.

4. Conectar no Claude Desktop ou Claude Code⌗

Você cria uma configuração apontando para esse servidor.

Exemplo genérico:

{ "mcpServers": { "tarefas": { "command": "npx", "args": ["tsx", "/CAMINHO/ABSOLUTO/meu-primeiro-mcp/src/server.ts"] } } }

A parte importante é usar o caminho absoluto do arquivo.

Depois, no cliente que suporta MCP, você poderá pedir algo como:

Adicione uma tarefa: comprar café.

Ou:

Liste minhas tarefas.

A IA verá as tools disponíveis e poderá chamar:

adicionar_tarefa() listar_tarefas() marcar_concluida()

Segundo a documentação oficial, o fluxo do MCP é: o cliente envia a pergunta ao modelo, o modelo analisa as ferramentas disponíveis, o cliente executa a tool escolhida via servidor MCP, o resultado volta ao modelo, e então o modelo responde ao usuário. (Model Context Protocol)

5. Como transformar isso em algo mais útil⌗

Depois desse primeiro MCP, você pode trocar o arquivo tarefas.json por algo real.

Opção A: MCP para Gmail⌗

Tools:

buscar_emails(query) ler_email(id) criar_rascunho(email_id, texto) arquivar_email(id)

Por baixo, essas tools chamariam a Gmail API.

Fluxo:

IA → MCP Gmail → Gmail API → Gmail

Opção B: MCP para empresa⌗

Tools:

buscar_cliente(nome) consultar_pedido(id) criar_tarefa_comercial(cliente, descricao) gerar_resumo_atendimento(id)

Por baixo, ele pode chamar banco de dados, planilha, CRM ou API interna.

Opção C: MCP para código⌗

Tools:

buscar_erro(log) rodar_teste(nome) listar_arquivos(path) abrir_ticket(titulo, descricao)

Esse tipo combina bem com Claude Code.

6. Estrutura mental para criar qualquer MCP⌗

Sempre pense em 4 partes:

1. Qual problema quero resolver? 2. Quais ferramentas a IA precisa? 3. Que entrada cada ferramenta recebe? 4. Que saída cada ferramenta retorna?

Exemplo Gmail:

```Problema: Organizar emails.

Ferramentas: buscar_emails, ler_email, criar_rascunho, arquivar_email.

Entradas: query, email_id, texto.

Saídas: lista de emails, conteúdo do email, confirmação.```

7. Regra de ouro⌗

Não comece criando um MCP enorme.

Comece com 2 ou 3 tools simples:

listar buscar criar

Depois adicione ações mais perigosas, como:

enviar deletar alterar

Para Gmail, eu começaria com:

buscar_emails() ler_email() criar_rascunho()

E deixaria enviar_email() para depois, com confirmação humana.

8. Resumo prático⌗

Para criar um MCP prático:

1. Crie um servidor Node/TypeScript 2. Instale @modelcontextprotocol/sdk 3. Registre tools com nome, descrição e schema 4. Implemente cada tool como uma função 5. Conecte via StdioServerTransport 6. Configure no cliente MCP 7. Teste com comandos simples

O primeiro MCP ideal é um de tarefas locais. Depois que isso funcionar, você conecta Gmail, banco de dados, WhatsApp, CRM ou qualquer sistema com API.

O jeito mais prático é começar com um MCP bem pequeno, sem Gmail real no começo, só para entender a lógica.

A ideia do MCP é:

IA → chama uma ferramenta → seu MCP executa → retorna resultado

Vamos criar um MCP de tarefas locais, com 3 ferramentas:

adicionar_tarefa(texto) listar_tarefas() marcar_concluida(id)

Isso é simples, útil e depois você pode trocar por Gmail, banco de dados, WhatsApp, sistema interno etc.

A documentação oficial recomenda criar um McpServer, registrar tools, escolher um transporte — stdio para integração local ou Streamable HTTP para servidores remotos — e conectar o servidor ao transporte. (GitHub)

1. Criar o projeto⌗

No terminal:

mkdir meu-primeiro-mcp cd meu-primeiro-mcp npm init -y npm install @modelcontextprotocol/sdk zod npm install -D typescript tsx @types/node

Crie um tsconfig.json:

{ "compilerOptions": { "target": "ES2022", "module": "NodeNext", "moduleResolution": "NodeNext", "strict": true, "esModuleInterop": true, "skipLibCheck": true } }

2. Criar o servidor MCP⌗

Crie o arquivo:

mkdir src touch src/server.ts

Dentro de src/server.ts, coloque:

```import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"; import { z } from "zod"; import fs from "node:fs/promises";

const DB_FILE = "tarefas.json";

type Tarefa = { id: number; texto: string; concluida: boolean; };

async function carregarTarefas(): Promise { try { const data = await fs.readFile(DB_FILE, "utf-8"); return JSON.parse(data); } catch { return []; } }

async function salvarTarefas(tarefas: Tarefa[]) { await fs.writeFile(DB_FILE, JSON.stringify(tarefas, null, 2)); }

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

server.registerTool( "adicionar_tarefa", { title: "Adicionar tarefa", description: "Adiciona uma nova tarefa na lista local", inputSchema: { texto: z.string().describe("Texto da tarefa") } }, async ({ texto }) => { const tarefas = await carregarTarefas();

const novaTarefa: Tarefa = {
  id: tarefas.length ? Math.max(...tarefas.map(t => t.id)) + 1 : 1,
  texto,
  concluida: false
};

tarefas.push(novaTarefa);
await salvarTarefas(tarefas);

return {
  content: [
    {
      type: "text",
      text: `Tarefa adicionada: #${novaTarefa.id} - ${novaTarefa.texto}`
    }
  ]
};

} );

server.registerTool( "listar_tarefas", { title: "Listar tarefas", description: "Lista todas as tarefas salvas", inputSchema: {} }, async () => { const tarefas = await carregarTarefas();

if (tarefas.length === 0) {
  return {
    content: [{ type: "text", text: "Nenhuma tarefa encontrada." }]
  };
}

const texto = tarefas
  .map(t => `${t.concluida ? "✅" : "⬜"} #${t.id} - ${t.texto}`)
  .join("\n");

return {
  content: [{ type: "text", text: texto }]
};

} );

server.registerTool( "marcar_concluida", { title: "Marcar tarefa como concluída", description: "Marca uma tarefa como concluída pelo ID", inputSchema: { id: z.number().describe("ID da tarefa") } }, async ({ id }) => { const tarefas = await carregarTarefas(); const tarefa = tarefas.find(t => t.id === id);

if (!tarefa) {
  return {
    content: [{ type: "text", text: `Tarefa #${id} não encontrada.` }]
  };
}

tarefa.concluida = true;
await salvarTarefas(tarefas);

return {
  content: [{ type: "text", text: `Tarefa #${id} marcada como concluída.` }]
};

} );

const transport = new StdioServerTransport(); await server.connect(transport);```

Esse é um MCP real e prático: ele expõe ferramentas que uma IA pode chamar.

3. Testar se roda⌗

Adicione no package.json:

```json { "scripts": { "start": "tsx src/server.ts" }, "dependencies": {

Criei um documento completo no canvas com:

API vs MCP
MCP como “funções” para IA
exemplo com Gmail
Claude Code Channels
arquitetura de webhook
canais de uma via e duas vias
segurança, permissões e prompt injection
quando usar API, MCP ou Channel
próximos passos práticos

Usei como base a documentação oficial de Claude Code Channels, que define channels como servidores MCP que enviam eventos para uma sessão do Claude Code, com suporte a webhooks, alertas, chat bridges e reply tools. A página também informa que o recurso está em research preview, exige Claude Code v2.1.80+ e login via claude.ai.

Os tópicos:

O que é Claude Code Channel

Um jeito de enviar mensagens/eventos externos para uma sessão do Claude Code.

Para que serve

Conectar Claude Code com Telegram, Discord, webhooks, CI/CD, monitoramento e bots.

Como funcionam os Channels

Um channel é um servidor MCP que entrega eventos para o Claude Code.

OpenClaw ou similares

Vimos que a página não menciona OpenClaw diretamente, mas a ideia poderia ser integrada se ele enviasse mensagens/webhooks ou tivesse um MCP.

Como criar seu próprio MCP Channel

Exemplo de um webhook local que recebe uma mensagem e envia para o Claude Code.

Diferença entre API e MCP

API: seu sistema chama um serviço/modelo.
MCP: a IA ganha ferramentas para chamar e usar.

API vs MCP usando Gmail

Gmail API: você programa cada passo.
Gmail MCP: a IA pode usar funções como buscar, ler, enviar e arquivar emails.

MCP como função de código

Você comparou com uma função que recebe algo e retorna algo.
Concluímos que uma MCP tool é parecida com isso: uma função que a IA pode chamar.

Vantagem principal do MCP

Você entrega ferramentas para a IA agir com mais autonomia, em vez de definir todo o fluxo manualmente.

Imagem da solução

Criamos um infográfico comparando “Usando API diretamente” vs “Usando MCP”, com exemplo do Gmail.

Canais , MCP e API

chatgpt.com ↗

Aula/documento sobre a diferença entre API, MCP e Claude Code…

4. Conectar no Claude Desktop ou Claude Code⌗

5. Como transformar isso em algo mais útil⌗

Opção A: MCP para Gmail⌗

Opção B: MCP para empresa⌗

Opção C: MCP para código⌗

6. Estrutura mental para criar qualquer MCP⌗

7. Regra de ouro⌗

8. Resumo prático⌗

1. Criar o projeto⌗

2. Criar o servidor MCP⌗

3. Testar se roda⌗

Recursos