Tutorial de Servidor MCP: Construa suas Próprias Ferramentas de IA em 30 Minutos

Você irá construir um servidor MCP com três ferramentas de IA personalizadas em 30 minutos: uma ferramenta de consulta a banco de dados, uma ferramenta de notificação e uma ferramenta de operações de arquivos. Ao final deste tutorial, você terá um servidor MCP funcional com esquemas de ferramentas validados pelo Zod, limitação de taxa, resiliência de disjuntor e integração total com o SDK NeuroLink para chamadas de ferramentas de IA de ponta a ponta.

O Protocolo de Contexto de Modelo (MCP) desacopla sua lógica de negócios da camada de orquestração de IA. Em vez de codificar logicamente as ferramentas em seu aplicativo, você define ferramentas em um servidor que qualquer agente de IA pode descobrir e executar em tempo de execução. Agora você irá configurar o servidor e construir sua primeira ferramenta.

O que é o Protocolo de Contexto de Modelo?

O MCP padroniza como os modelos de IA descobrem e executam ferramentas. O protocolo define um ciclo de vida claro: um servidor registra ferramentas com seus esquemas, um agente de IA descobre essas ferramentas no momento da conexão, o modelo decide quando chamar uma ferramenta com base na solicitação do usuário, o servidor executa a lógica da ferramenta e o resultado flui de volta para o modelo para incorporação na resposta final.

sequenceDiagram
    participant U as Usuário
    participant A as Agente de IA
    participant M as Servidor MCP
    participant T as Implementação da Ferramenta

    U->>A: Fazer pergunta
    A->>M: Descobrir ferramentas disponíveis
    M-->>A: Lista de ferramentas com esquemas
    A->>A: LLM decide chamar a ferramenta
    A->>M: Executar ferramenta com parâmetros
    M->>T: Executar lógica da ferramenta
    T-->>M: Retornar resultado
    M-->>A: Resultado da ferramenta
    A-->>U: Resposta final usando dados da ferramenta

A chave é a separação de preocupações. Seu servidor MCP encapsula a lógica de negócios -- consultas a banco de dados, chamadas de API, operações de arquivos -- por trás de uma interface de ferramenta limpa. O agente de IA não precisa saber como o banco de dados funciona ou como as notificações são enviadas. Ele apenas chama a ferramenta com os parâmetros que o esquema define.

Esse padrão tem vários benefícios práticos:

• Reusabilidade: O mesmo servidor MCP pode atender a vários agentes de IA, diferentes modelos e diferentes aplicativos.
• Testabilidade: As ferramentas têm entradas e saídas definidas, tornando-as fáceis de testar em isolamento.
• Segurança: A execução da ferramenta acontece no lado do servidor, onde você controla o acesso, a limitação de taxa e o registro de auditoria.
• Descoberta: Os agentes aprendem automaticamente quais ferramentas estão disponíveis e como chamá-las.

Passo 1 -- Criar um Servidor MCP

Comece criando um servidor usando a função de fábrica createMCPServer(). O servidor precisa de um ID, título, descrição e categoria.

import { createMCPServer } from "@juspay/neurolink";

const server = createMCPServer({
  id: "meus-ferramentas-de-negócios",
  title: "Servidor de Ferramentas de Negócios",
  description: "Ferramentas personalizadas para operações de negócios",
  category: "negócios",
  version: "1.0.0",
});

console.log("Servidor criado:", server.id);
console.log("Categoria:", server.category); // "negócios"

O campo category classifica seu servidor para descoberta e organização. O NeuroLink suporta as seguintes categorias: aiProviders, frameworks, development, business, content, data, integrations, automation, analysis e custom. Escolha a que melhor descreve o propósito das suas ferramentas.

O objeto servidor é um contêiner leve que mantém registros de ferramentas e fornece métodos para validação e execução. Ele não inicia um servidor HTTP ou escuta em uma porta. É um agrupamento lógico de ferramentas que pode ser incorporado em qualquer aplicativo, exposto via HTTP ou usado diretamente em processo.

Passo 2 -- Registrar Ferramentas

As ferramentas são o núcleo do seu servidor MCP. Cada ferramenta precisa de um name, uma description (usada pelo LLM para decidir quando chamá-la), um esquema de parameters (definido com Zod para validação em tempo de execução e inferência de tipo) e uma função execute que contém sua lógica de negócios.

import { z } from "zod";

// Ferramenta 1: Ferramenta de consulta ao banco de dados
server.registerTool({
  name: "queryDatabase",
  description: "Executar uma consulta SQL somente leitura contra o banco de dados de análises",
  parameters: z.object({
    query: z.string().describe("Consulta SQL SELECT"),
    limit: z.number.