O que é o Model Context Protocol (MCP)

O Model Context Protocol, ou MCP, e um padrão aberto lançado pela Anthropic em novembro de 2024 para conectar assistentes de IA a fontes de dados externas de forma padronizada. Em vez de cada ferramenta de IA implementar sua própria lógica de integração, o MCP define um protocolo único que qualquer cliente compatível pode consumir.

Pense no MCP como o USB das integrações de IA: antes do USB, cada dispositivo tinha seu próprio conector. O MCP faz o mesmo para IA: você cria um servidor uma vez, e ele funciona com Claude, GitHub Copilot, Cursor e qualquer outro cliente que suporte o protocolo.

O protocolo nasceu de uma necessidade real: desenvolvedores estavam criando a mesma integração diversas vezes, uma para cada ferramenta de IA. Com o MCP, você escreve o servidor uma única vez e conecta em qualquer lugar.

Como funciona

O MCP usa JSON-RPC 2.0 como protocolo de comunicação. O cliente de IA (como o Claude Desktop) inicia um processo servidor local e se comunica via standard input/output (stdio) ou HTTP com Server-Sent Events (SSE). A comunicação e bidirecional: o servidor expõe capacidades, o cliente as descobre e as invoca conforme necessário.

O servidor MCP expõe três tipos de primitivas: Tools (funções que o modelo pode chamar), Resources (dados que o modelo pode ler, como arquivos ou banco de dados) e Prompts (templates de instruções pre-configuradas para tarefas específicas).

Quando você conversa com Claude e pede algo que requer acesso a uma ferramenta externa, o Claude identifica qual tool do MCP deve chamar, envia os parâmetros no formato correto, recebe o resultado e incorpora na resposta. O usuário não precisa fazer nada manualmente.

💡
Dica

O transporte via stdio e o mais simples para começar: sem configuração de rede, sem autenticação de endpoint. Ideal para servidores que rodam localmente no computador do usuário. O transporte HTTP/SSE e preferido quando o servidor precisa ser acessado remotamente ou por múltiplos clientes.

Principais recursos do SDK TypeScript

O SDK oficial do MCP para TypeScript oferece tudo que você precisa para criar um servidor robusto. Ele esta publicado no npm como @modelcontextprotocol/sdk e e mantido pela Anthropic no GitHub.

  • Server e StdioServerTransport: as classes base para criar o servidor e definir o transporte.
  • Schemas de validação: ListToolsRequestSchema e CallToolRequestSchema garantem que requisições estejam no formato correto.
  • Suporte a Resources: para expor arquivos, banco de dados ou qualquer dado estruturado ao modelo.
  • Suporte a Prompts: templates reutilizáveis que o usuário pode acionar pelo cliente.
  • TypeScript nativo: tipos completos para todas as estruturas do protocolo, facilitando o desenvolvimento.

A instalação e direta via npm. Você precisara também do Node.js 18 ou superior, pois o SDK usa fetch nativo e outros recursos modernos do runtime.

Para integrações com serviços Microsoft como OneNote, SharePoint e Outlook, você precisara também da biblioteca @azure/msal-node para autenticação via OAuth 2.0 com o Microsoft Graph.

Como começar: instalação passo a passo

Vamos criar um servidor MCP do zero. O exemplo abaixo mostra como criar um servidor básico com suporte ao Microsoft Graph.

Passo 1: crie o projeto Node.js e instale as dependências:

mkdir meu-servidor-mcp
cd meu-servidor-mcp
npm init -y
npm install @modelcontextprotocol/sdk @azure/msal-node node-fetch
npm install -D TypeScript @types/node tsx

Passo 2: configure o tsconfig.json para usar ES modules:

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

Passo 3: crie o arquivo src/índex.ts com o servidor e configure as variáveis de ambiente com as credenciais do Azure. Veja o exemplo prático na próxima secao.

⚠️
Atenção

Nunca coloque credenciais (client_id, client_secret) diretamente no código. Use variáveis de ambiente ou um arquivo .env com dotenv. O Claude Desktop le o arquivo claude_desktop_config.json onde você pode definir as variáveis de ambiente que serão passadas para o servidor MCP.

Exemplo prático: servidor MCP para o OneNote

Veja como criar um servidor MCP que lista os notebooks do OneNote do usuário via Microsoft Graph. Primeiro, registre um aplicativo no Azure Active Directory e obtenha client_id, client_secret e tenant_id.

import { Server } from "@modelcontextprotocol/sdk/server/índex.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
import { ConfidentialClientApplication } from "@azure/msal-node";

const msalClient = new ConfidentialClientApplication({
  auth: {
    clientId: process.env.AZURE_CLIENT_ID!,
    authority: `https://login.microsoftonline.com/${process.env.AZURE_TENANT_ID}`,
    clientSecret: process.env.AZURE_CLIENT_SECRET!,
  }
});

async function getToken(): Promise {
  const result = await msalClient.acquireTokenByClientCredential({
    scopes: ["https://graph.microsoft.com/.default"]
  });
  return result!.accessToken;
}

const server = new Server(
  { name: "onenote-server", version: "1.0.0" },
  { capabilities: { tools: {} } }
);

server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [{
    name: "listar_notebooks",
    description: "Lista os notebooks do OneNote",
    inputSchema: { type: "object", properties: {} }
  }]
}));

server.setRequestHandler(CallToolRequestSchema, async (req) => {
  if (req.params.name === "listar_notebooks") {
    const token = await getToken();
    const resp = await fetch("https://graph.microsoft.com/v1.0/me/onenote/notebooks", {
      headers: { Authorization: `Bearer ${token}` }
    });
    const data = await resp.json();
    return { content: [{ type: "text", text: JSON.stringify(data.value, null, 2) }] };
  }
  throw new Error("Tool não encontrada");
});

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

O fluxo e: Claude recebe uma pergunta sobre os seus notebooks, identifica que deve chamar a tool listar_notebooks, o servidor busca o token do Azure, faz a chamada ao Microsoft Graph e retorna os dados para o Claude formatar a resposta ao usuário.

Para registrar o servidor no Claude Desktop, adicione uma entrada no arquivo claude_desktop_config.json dentro da pasta de configuração do Claude.

Comparação com alternativas

Antes do MCP, as principais formas de integrar IA com dados externos eram: function calling direto na API, LangChain Tools e integração customizada por produto.

  • vs function calling direto: O MCP adiciona uma camada de padronização. Com function calling direto, você define as ferramentas por requisição. Com MCP, o servidor e persistente e pode ser compartilhado entre vários clientes.
  • vs LangChain Tools: LangChain e um framework Python com mais funcionalidades, mas muito mais opinionated. MCP e um protocolo leve, sem dependências de framework.
  • vs integração customizada: Sem padrão, você reescreve a mesma lógica para Claude, Copilot e Cursor. Com MCP, escreve uma vez e funciona em todos.

O principal diferencial do MCP e a portabilidade: um servidor escrito hoje funciona automaticamente com qualquer cliente que adotar o padrão no futuro, sem nenhuma alteração no seu código.

🚀
Pro tip

Use o MCP Inspector (ferramenta oficial da Anthropic disponível no npm como @modelcontextprotocol/inspector) para testar seu servidor localmente antes de conectar ao Claude. Ele simula um cliente MCP com interface visual, economizando muito tempo de debug.

Pontos positivos e limitações

O MCP oferece vantagens claras para quem quer construir integrações de IA padronizadas, mas e um ecossistema relativamente novo e tem limitações que você precisa conhecer antes de adotar.

O que funciona bem: padronização que elimina retrabalho entre ferramentas; SDK TypeScript completo com tipos bem definidos; comunidade ativa com centenas de servidores já disponíveis no GitHub; suporte nativo no Claude Desktop, Cursor, VS Code Copilot e outros clientes populares.

Limitações reais: o ecossistema ainda esta crescendo e documentação pode ser escassa para casos de uso mais avançados; depuração de servidores MCP e mais complexa do que debug de APIs REST convencionais; o suporte a autenticação OAuth no transporte HTTP ainda esta evoluindo; e a maioria dos tutoriais disponíveis e em inglês, com poucos recursos em português.

Casos de uso reais

O MCP brilha em situações onde você quer que um assistente de IA acesse dados privados de forma segura e controlada.

Desenvolvedor que usa Claude para trabalhar: cria um servidor MCP que acessa seu Jira, GitHub e Confluence. Agora o Claude responde perguntas como "qual a próxima task do sprint" ou "resuma os PRs abertos desta semana" sem sair do chat.

Empresa com dados internos: cria um servidor MCP que conecta o Claude ao banco de dados de produtos ou ao sistema de CRM. A equipe de atendimento pode perguntar ao Claude sobre status de pedidos sem precisar abrir sistemas legados.

Time de infraestrutura: servidor MCP para consultar logs, métricas do CloudWatch ou status de deploys no Kubernetes. O engenheiro de plantão pode perguntar ao Claude o que esta causando o aumento de latência e receber o contexto relevante automaticamente.

Dicas e boas práticas

💡
Dica

Implemente tratamento de erro explicativo nas suas tools. Quando o token expirar ou a API retornar erro, retorne uma mensagem descritiva como "Token expirado - reautentique via Azure Portal" em vez de lançar uma exceção genérica. O Claude vai passar essa mensagem ao usuário de forma contextualizada.

💡
Dica

Mantenha as tools com escopo pequeno e bem definido. Uma tool "buscar_tudo_no_onenote" e difícil de usar pelo modelo. Prefira "listar_notebooks", "listar_paginas_da_secao" e "ler_pagina" separadas, permitindo que o Claude navegue de forma incremental e precisa.

🔴
Cuidado

Não exponha tools que executem operações destrutivas sem confirmação. Uma tool de exclusão ou edição acessível diretamente pelo Claude pode levar a alterações indesejadas se o modelo interpretar mal a intenção do usuário. Adicione um passo de confirmação explicitamente no fluxo.

Outra boa prática: versionamento do servidor. Use o campo version no construtor do Server e incremente seguindo semver quando houver mudanças de API. Clientes MCP podem expor a versão ao usuário, facilitando o suporte.

Vale a pena?

Para quem vale: desenvolvedores que querem criar integrações de IA reutilizáveis, times que usam múltiplas ferramentas de IA (Claude, Copilot, Cursor) e não querem reescrever integrações, e empresas que querem conectar assistentes de IA a dados internos de forma padronizada e auditavel.

O MCP ainda e relativamente novo, mas já tem adoção expressiva. A Anthropic, a Microsoft e dezenas de outras empresas publicaram servidores oficiais. Quanto mais cedo você aprender o protocolo, mais preparado vai estar para o ecossistema de IA dos próximos anos.

Próximo passo: instale o MCP Inspector com npm install -g @modelcontextprotocol/inspector, crie um servidor básico com uma tool simples e teste localmente antes de integrar ao Claude Desktop. A curva de aprendizado e baixa e o ganho de produtividade e imediato.