Como Eu Construí um Servidor MCP Conectado ao Claude Desktop com Typescript

O Protocolo de Contexto do Modelo (MCP) representa um avanço significativo na forma como assistentes de IA interagem com ferramentas externas e fontes de dados. Desenvolvido pela Anthropic, o MCP permite que Claude se comunique de maneira integrada com servidores personalizados, possibilitando o acesso a informações em tempo real, a execução de fluxos de trabalho complexos e a interação com APIs sem sair do contexto da conversa. Essa capacidade transforma Claude de um LLM autônomo em um assistente versátil que pode aproveitar funcionalidades externas enquanto mantém a coerência da conversa.

Neste guia abrangente, iremos passar pelo processo de construção de um servidor MCP em TypeScript do zero e conectá-lo ao Claude Desktop. Ao implementar essa integração, você permitirá que Claude realize tarefas como recuperar dados em tempo real, executar cálculos ou interagir diretamente com sua lógica de negócios personalizada dentro das conversas.

Antes de mergulharmos na implementação do nosso servidor MCP, vale mencionar que sua escolha de ferramenta para desenvolvimento de API pode impactar significativamente a eficiência do seu fluxo de trabalho.

Embora o Postman tenha sido por muito tempo o padrão da indústria, o Apidog surgiu como uma alternativa superior que complementa perfeitamente fluxos de trabalho de desenvolvimento modernos como o que estamos construindo.
Diferente das limitações do Postman com APIs em desenvolvimento, o Apidog oferece sincronização em tempo real entre suas especificações de API e solicitações, garantindo que sua documentação e testes permaneçam automaticamente atualizados à medida que suas APIs evoluem.
Com a criação visual de especificações de API, execuções ilimitadas de coleções (se comparado ao limite de 25/mês do Postman) e recursos poderosos como solicitações geradas automaticamente e respostas simuladas, o Apidog agiliza todo o ciclo de vida da API. Suas capacidades abrangentes de teste, incluindo criação visual de testes e runners autoadministrados, o tornam ideal para equipes que implementam integrações complexas como nosso servidor MCP.

Enquanto construímos nosso servidor MCP em TypeScript, considere como os recursos colaborativos do Apidog e a abordagem focada no desenvolvimento podem aumentar a produtividade da sua equipe e garantir que suas APIs permaneçam consistentes, bem testadas e completamente documentadas ao longo do processo.

botão

Entendendo o Protocolo de Contexto do Modelo

O Protocolo de Contexto do Modelo define uma maneira padronizada para Claude se comunicar com serviços externos. Quando Claude identifica que precisa de informação de uma fonte externa, ele pode invocar um servidor MCP por meio de uma solicitação JSON especialmente formatada. O servidor processa essa solicitação e retorna os dados solicitados, que Claude pode então incorporar em sua resposta.

O MCP oferece várias vantagens em relação às abordagens tradicionais de integração de IA:

Consciência contextual: Claude mantém todo o histórico da conversa ao fazer solicitações
Comunicação bidirecional: O protocolo suporta interações complexas entre Claude e seu servidor
Segurança e controle: Você determina quais funcionalidades expor e como as solicitações são processadas
Experiência fluida: Os usuários interagem com Claude de forma natural, sem a necessidade de saber sobre as integrações subjacentes

Pré-requisitos

Antes de começarmos a construir nosso servidor MCP, verifique se você tem o seguinte:

Node.js (v18 ou superior) instalado
Um editor de código como o Visual Studio Code
Conhecimento básico de TypeScript
Aplicativo Claude Desktop instalado
Familiaridade com Express.js (para construir os endpoints do servidor)

Configurando Seu Projeto TypeScript

Vamos começar criando um novo projeto TypeScript para nosso servidor MCP:

mkdir claude-mcp-server
cd claude-mcp-server
npm init -y
npm install typescript @types/node ts-node express @types/express cors @types/cors
npx tsc --init

Em seguida, atualize seu tsconfig.json para incluir estas configurações:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "outDir": "./dist",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  }
}

Implementando o Servidor MCP

Crie um novo arquivo chamado server.ts no diretório raiz do seu projeto. Este será o ponto de entrada para nosso servidor MCP:

import express from 'express';
import cors from 'cors';
import { Request, Response } from 'express';

// Defina tipos para o protocolo MCP
interface MCPRequest {
  query: string;
  conversation_id: string;
  request_id: string;
  parameters?: Record<string, any>;
}

interface MCPResponse {
  response: string;
  status: 'success' | 'error';
  error?: string;
}

const app = express();
app.use(cors());
app.use(express.json());

// Endpoint de verificação de saúde
app.get('/health', (req: Request, res: Response) => {
  res.status(200).json({ status: 'healthy' });
});

// Endpoint MCP
app.post('/mcp', (req: Request, res: Response) => {
  try {
    const mcpRequest = req.body as MCPRequest;
    console.log('Recebida solicitação MCP:', JSON.stringify(mcpRequest, null, 2));

    // Processar a solicitação com base na consulta
    const response = processQuery(mcpRequest);
    
    res.status(200).json({
      status: 'success',
      response
    } as MCPResponse);
  } catch (error) {
    console.error('Erro ao processar solicitação MCP:', error);
    res.status(500).json({
      status: 'error',
      error: error instanceof Error ? error.message : 'Erro desconhecido',
      response: 'Desculpe, houve um erro ao processar sua solicitação.'
    } as MCPResponse);
  }
});

// Função para processar diferentes tipos de consulta
function processQuery(request: MCPRequest): string {
  const { query, parameters } = request;

  // Exemplo de manipulação de consulta - personalize isso para seu caso de uso
  switch (query) {
    case 'getCurrentTime':
      return `A hora atual é ${new Date().toLocaleTimeString()}`;
    
    case 'getWeather':
      const location = parameters?.location || 'Desconhecido';
      // Em um aplicativo real, você chamaria uma API de clima aqui
      return `O clima em ${location} é atualmente ensolarado e 22°C`;
    
    case 'calculateSum':
      if (parameters?.numbers && Array.isArray(parameters.numbers)) {
        const sum = parameters.numbers.reduce((a: number, b: number) => a + b, 0);
        return `A soma dos números é ${sum}`;
      }
      return 'Parâmetros inválidos para cálculo da soma';

    default:
      return `Consulta não reconhecida: ${query}`;
  }
}

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`Servidor MCP em execução na porta ${PORT}`);
});

Executando Seu Servidor MCP

Para executar seu servidor, execute:

npx ts-node server.ts

Seu servidor MCP deve estar em execução na porta 3000 (ou na porta que você especificou).

Conectando ao Claude Desktop

Agr agora que seu servidor MCP está em execução, você precisa configurar o Claude Desktop para se conectar a ele. Aqui está como:

Abra o aplicativo Claude Desktop
Vá para Configurações (geralmente no canto superior direito)
Navegue até a seção "Recursos Experimentais"
Ative o toggle "Protocolo de Contexto do Modelo"
Adicione um novo endpoint MCP com a URL http://localhost:3000/mcp
Salve suas configurações

O Claude Desktop agora será capaz de se comunicar com seu servidor MCP personalizado.

Testando a Integração

Para testar seu servidor MCP com o Claude, tente fazer perguntas a Claude que acionariam as consultas específicas que você implementou. Por exemplo:

"Que horas são agora?" (deve acionar a consulta getCurrentTime)
"Como está o clima em São Francisco?" (deve acionar a consulta getWeather com "São Francisco" como parâmetro de localização)
"Você pode calcular a soma de 5, 10, 15 e 20?" (deve acionar a consulta calculateSum)

Quando Claude reconhecer que precisa de informações externas para responder a essas perguntas, ele enviará automaticamente uma solicitação MCP para seu servidor e incorporará a resposta em sua resposta.

Extendendo Seu Servidor MCP

O servidor básico que construímos é apenas um ponto de partida. Aqui estão algumas ideias para expandir sua funcionalidade:

Adicionar Autenticação

Para proteger seu servidor MCP, adicione autenticação:

// Middleware para autenticação básica
const authenticateMCP = (req: Request, res: Response, next: Function) => {
  const apiKey = req.headers['x-api-key'];
  if (!apiKey || apiKey !== process.env.MCP_API_KEY) {
    return res.status(401).json({
      status: 'error',
      error: 'Não autorizado',
      response: 'Falha na autenticação'
    });
  }
  next();
};

// Aplicar middleware ao endpoint MCP
app.post('/mcp', authenticateMCP, (req: Request, res: Response) => {
  // Código existente do manipulador
});

Implementar Integração com Banco de Dados

Conecte seu servidor MCP a um banco de dados para recuperar ou armazenar informações:

import { MongoClient } from 'mongodb';

// Inicializar conexão com banco de dados
const dbClient = new MongoClient('mongodb://localhost:27017');
let db: any;

async function connectToDb() {
  await dbClient.connect();
  db = dbClient.db('mcpDatabase');
  console.log('Conectado ao banco de dados');
}

connectToDb().catch(console.error);

// Adicionar um manipulador de consulta para interações com o banco de dados
case 'getUserData':
  if (parameters?.userId) {
    const user = await db.collection('users').findOne({ id: parameters.userId });
    return user ? JSON.stringify(user) : 'Usuário não encontrado';
  }
  return 'ID de usuário inválido';

Adicionar Suporte a Webhooks

Implemente funcionalidade de webhook para notificar serviços externos:

case 'sendNotification':
  if (parameters?.message && parameters?.destination) {
    // Chamar serviço externo de notificação
    await fetch('https://your-webhook-url.com', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ message: parameters.message })
    });
    return `Notificação enviada para ${parameters.destination}`;
  }
  return 'Parâmetros de notificação inválidos';

Melhores Práticas para Desenvolvimento de Servidores MCP

Trate erros de forma elegante: Sempre capture exceções e retorne mensagens de erro informativas
Implemente logging: Registre todas as solicitações e respostas para depuração e auditoria
Use interfaces TypeScript: Defina interfaces claras para todas as estruturas de dados
Defina timeouts: Implemente timeouts de solicitações para evitar operações penduradas
Valide entradas: Valide cuidadosamente todos os parâmetros de entrada antes de processá-los
Adicione testes unitários: Teste seus manipuladores de consulta minuciosamente para garantir confiabilidade

Conclusão

Construir um servidor MCP em TypeScript abre possibilidades empolgantes para expandir as capacidades do Claude. Seguindo este guia, você criou uma base para integrar Claude com seus próprios serviços e dados. O Protocolo de Contexto do Modelo possibilita uma experiência do usuário fluida, onde Claude pode acessar informações externas sem quebrar o fluxo da conversa.

À medida que o MCP continua a evoluir, podemos esperar integrações ainda mais sofisticadas entre modelos de linguagem grande e sistemas externos. Seja você construindo ferramentas de produtividade, sistemas de gerenciamento de conhecimento ou aplicativos de negócios personalizados, o MCP proporciona uma forma poderosa de combinar a inteligência do Claude com sua funcionalidade especializada.

Comece a explorar as possibilidades estendendo seu servidor com manipuladores de consulta adicionais específicos para os seus casos de uso e compartilhe suas experiências com a crescente comunidade de desenvolvedores do MCP.