GuiaMCP-BR

🌐 Guia Completo sobre Model Context Protocol (MCP)

📑 Índice

• O que é o Model Context Protocol (MCP)?
• Por que o MCP é importante?
• Arquitetura básica do MCP
• Componentes principais do MCP
• Criando sua primeira aplicação MCP
• Implantando um servidor MCP na Vercel
• Casos de uso avançados
• Melhores práticas
• Recursos adicionais
• Conclusão

🔍 O que é o Model Context Protocol (MCP)?

O Model Context Protocol (MCP) é um padrão aberto desenvolvido pela Anthropic que permite criar conexões seguras e bidirecionais entre modelos de IA e diversas fontes de dados. Funciona como uma "porta USB-C" para aplicações de IA, permitindo conectar modelos a diferentes fontes de dados e ferramentas de maneira padronizada.

⚡ Por que o MCP é importante?

Mesmo os modelos de linguagem mais avançados são limitados pelo contexto que recebem. O MCP resolve este problema ao:

🏗️ Arquitetura básica do MCP

O MCP segue uma arquitetura cliente-servidor:

1. Servidores MCP: Expõem dados e funcionalidades (como APIs, bancos de dados, sistemas internos)
2. Clientes MCP: Aplicações de IA que consomem esses recursos (Claude, ChatGPT e outros)

🧩 Componentes principais do MCP

O MCP oferece três tipos fundamentais de capacidades:

• 📁 Recursos (Resources): Dados semelhantes a arquivos que podem ser lidos pelos clientes
• 🛠️ Ferramentas (Tools): Funções que podem ser chamadas pelo modelo de IA (com aprovação do usuário)
• 📝 Prompts: Templates pré-escritos que auxiliam os usuários a realizar tarefas específicas

🚀 Criando sua primeira aplicação MCP

Vamos criar um aplicativo MCP simples que permite a um modelo de IA acessar dados do clima e compartilhar esses dados com o usuário.

Pré-requisitos

• Node.js instalado
• Conhecimento básico de JavaScript/TypeScript
• Conta no Vercel (opcional, para implantação)

Passo 1: Configurar o projeto

# Criar novo diretório para o projeto
mkdir meu-app-mcp
cd meu-app-mcp

# Inicializar projeto Node.js
npm init -y

# Instalar dependências
npm install @anthropic-ai/mcp-kit @anthropic-ai/mcp-nodejs

Passo 2: Criar o servidor MCP

Crie um arquivo chamado servidor-mcp.js com o seguinte conteúdo:

const { createStdioServer } = require('@anthropic-ai/mcp-nodejs');
const { defineResource, defineTool } = require('@anthropic-ai/mcp-kit');

// Definindo uma ferramenta para obter informações sobre o clima
const getClima = defineTool({
  name: 'obter_clima',
  description: 'Obtém informações sobre o clima de uma cidade',
  parameters: {
    type: 'object',
    properties: {
      cidade: {
        type: 'string',
        description: 'Nome da cidade para obter informações sobre o clima'
      }
    },
    required: ['cidade']
  },
  handler: async ({ cidade }) => {
    // Em um caso real, faríamos uma chamada API para um serviço de clima
    // Aqui usamos dados simulados para demonstração
    const temperaturas = {
      'São Paulo': '23°C',
      'Rio de Janeiro': '30°C',
      'Brasília': '26°C',
      'Recife': '32°C',
      'Porto Alegre': '18°C'
    };
    
    const temperatura = temperaturas[cidade] || 'Dados não disponíveis';
    
    return {
      temperatura,
      previsao: 'Ensolarado com nuvens ocasionais',
      data: new Date().toLocaleDateString('pt-BR')
    };
  }
});

// Definindo um recurso estático com informações sobre o MCP
const sobMcp = defineResource({
  name: 'sobre_mcp',
  description: 'Informações sobre o Model Context Protocol',
  get: async () => {
    return `
      O Model Context Protocol (MCP) é um padrão aberto que permite conectar modelos de IA
      a diferentes fontes de dados e ferramentas de maneira segura e padronizada.
      Desenvolvido pela Anthropic, ele resolve o problema de silos de informação em sistemas de IA.
    `;
  }
});

// Criar e iniciar o servidor MCP
const server = createStdioServer({
  tools: [getClima],
  resources: [sobMcp],
});

server.start();

Passo 3: Criar um cliente de teste

Para testar nosso servidor, vamos criar um cliente simples. Crie um arquivo chamado cliente-teste.js:

const { MCPClient } = require('@anthropic-ai/mcp-kit');

async function testarMCP() {
  // Conectar ao servidor MCP (assumindo que está rodando como um processo separado)
  const client = new MCPClient({
    transport: { type: 'subprocess', command: 'node servidor-mcp.js' }
  });

  try {
    // Listar ferramentas e recursos disponíveis
    const capacidades = await client.getCapabilities();
    console.log('Capacidades disponíveis:', JSON.stringify(capacidades, null, 2));

    // Chamar a ferramenta de clima
    const resultadoClima = await client.invokeTool('obter_clima', {
      cidade: 'São Paulo'
    });
    console.log('Resultado do clima:', resultadoClima);

    // Acessar o recurso estático
    const infoMCP = await client.getResource('sobre_mcp');
    console.log('Informações sobre MCP:', infoMCP);

  } catch (erro) {
    console.error('Erro ao testar MCP:', erro);
  } finally {
    await client.close();
  }
}

testarMCP();

Passo 4: Executar o aplicativo

node cliente-teste.js

💡 Dica: Para verificar se seu servidor MCP está funcionando corretamente, verifique o console para ver as capacidades disponíveis e as respostas das chamadas.

🚢 Implantando um servidor MCP na Vercel

A Vercel oferece um template pronto para implantar servidores MCP, facilitando a criação de aplicações baseadas em IA.

Requisitos

• Conta na Vercel
• Vercel CLI instalado

Processo de implantação

1. Clonando o template:

npx degit vercel-labs/mcp-on-vercel meu-servidor-mcp
cd meu-servidor-mcp

2. Configurando o Redis:

   • Crie uma instância do Upstash Redis na Vercel
   • Associe-a ao seu projeto com a variável de ambiente REDIS_URL

3. Personalizando o servidor:

   • Edite api/server.ts para adicionar suas ferramentas, prompts e recursos
   • Siga a documentação do SDK TypeScript do MCP

4. Implantando:

vercel deploy

O que fazer após escolher o template

O template da Vercel "Model Context Protocol (MCP) with Vercel Functions" é um projeto pré-configurado que facilita a criação de servidores MCP. Depois de clonar este template, você precisa:

O template já inclui toda a estrutura necessária, incluindo gerenciamento de sessões via Redis e configuração básica. Seu foco deve ser adicionar as funcionalidades específicas que seu servidor MCP oferecerá.

🔮 Casos de uso avançados

1. Integração com bancos de dados

const consultarBancoDados = defineTool({
  name: 'consultar_db',
  description: 'Consulta informações no banco de dados',
  parameters: {
    type: 'object',
    properties: {
      tabela: { type: 'string' },
      filtro: { type: 'object' }
    },
    required: ['tabela']
  },
  handler: async ({ tabela, filtro }) => {
    // Lógica para consultar o banco de dados
    // Retorna os resultados
  }
});

2. Processamento de documentos

const analisarDocumento = defineTool({
  name: 'analisar_documento',
  description: 'Analisa um documento e extrai informações-chave',
  parameters: {
    type: 'object',
    properties: {
      url: { type: 'string' },
      tipo: { type: 'string', enum: ['pdf', 'docx', 'txt'] }
    },
    required: ['url']
  },
  handler: async ({ url, tipo }) => {
    // Lógica para baixar e processar o documento
    // Retorna informações estruturadas
  }
});

3. Interfaces multimodais

const gerarImagem = defineTool({
  name: 'gerar_imagem',
  description: 'Gera uma imagem com base em uma descrição',
  parameters: {
    type: 'object',
    properties: {
      descricao: { type: 'string' },
      estilo: { type: 'string', default: 'realista' }
    },
    required: ['descricao']
  },
  handler: async ({ descricao, estilo }) => {
    // Lógica para gerar imagem usando um serviço como DALL-E ou Midjourney
    // Retorna URL da imagem
  }
});

🔒 Melhores práticas

📚 Recursos adicionais

• Documentação oficial do MCP
• Repositório GitHub de servidores MCP
• SDK TypeScript do MCP
• Template MCP da Vercel

🔮 Conclusão

O Model Context Protocol (MCP) representa um passo importante para conectar sistemas de IA com o mundo real de maneira padronizada e segura. Ao criar aplicativos com MCP, você está participando de um ecossistema em rápido crescimento que promete transformar como interagimos com tecnologias de IA.

À medida que mais empresas e desenvolvedores adotam este padrão, podemos esperar uma proliferação de servidores MCP especializados que expandirão significativamente as capacidades dos assistentes de IA, tornando-os mais úteis e relevantes para tarefas do mundo real.