Construindo um Servidor MCP que Conecta ao OpenAI: Um Guia Completo para Desenvolvedores

mkdir mcp-server-openai
cd mcp-server-openai
npm init -y
npm install @modelcontextprotocol/sdk openai dotenv express cors
npm install --save-dev typescript @types/node ts-node

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "lib": ["ES2020"],
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  }
}

python -m venv venv
source venv/bin/activate  # No Windows: venv\Scripts\activate
pip install mcp openai python-dotenv fastapi uvicorn

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import {
  CallToolRequestSchema,
  ListToolsRequestSchema,
} from "@modelcontextprotocol/sdk/types.js";

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

// Defina suas ferramentas
const tools = [
  {
    name: "get_customer_info",
    description: "Recupera informações do cliente pelo ID",
    inputSchema: {
      type: "object",
      properties: {
        customer_id: {
          type: "string",
          description: "Identificador único do cliente",
        },
      },
      required: ["customer_id"],
    },
  },
  // Adicione mais ferramentas aqui
];

// Lida com solicitações de listagem de ferramentas
server.setRequestHandler(ListToolsRequestSchema, async () => {
  return { tools };
});

// Lida com solicitações de execução de ferramentas
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;

  if (name === "get_customer_info") {
    // Implemente a lógica da ferramenta aqui
    const customerId = args.customer_id;
    // Consulte seu banco de dados ou API
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify({
            id: customerId,
            name: "John Doe",
            email: "john@example.com",
          }),
        },
      ],
    };
  }

  return {
    content: [{ type: "text", text: `Ferramenta desconhecida: ${name}` }],
    isError: true,
  };
});

// Inicia o servidor
const transport = new StdioServerTransport();
server.connect(transport);

from mcp.server import Server
from mcp.types import Tool, TextContent, ToolResult
import json

app = Server("openai-mcp-server")

# Defina suas ferramentas
TOOLS = [
    Tool(
        name="get_customer_info",
        description="Recupera informações do cliente pelo ID",
        inputSchema={
            "type": "object",
            "properties": {
                "customer_id": {
                    "type": "string",
                    "description": "Identificador único do cliente"
                }
            },
            "required": ["customer_id"]
        }
    )
]

@app.list_tools()
async def list_tools():
    return TOOLS

@app.call_tool()
async def call_tool(name: str, arguments: dict):
    if name == "get_customer_info":
        customer_id = arguments.get("customer_id")
        # Implemente a lógica da ferramenta
        result = {
            "id": customer_id,
            "name": "John Doe",
            "email": "john@example.com"
        }
        return ToolResult(
            content=[TextContent(type="text", text=json.dumps(result))]
        )

    return ToolResult(
        content=[TextContent(type="text", text=f"Ferramenta desconhecida: {name}")],
        isError=True
    )

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000)

import { Pool } from "pg"; // Exemplo com PostgreSQL

const pool = new Pool({
  connectionString: process.env.DATABASE_URL,
});

async function getCustomerInfo(customerId: string) {
  try {
    const result = await pool.query(
      "SELECT id, name, email, account_status FROM customers WHERE id = $1",
      [customerId]
    );

    if (result.rows.length === 0) {
      return {
        error: "Cliente não encontrado",
        status: 404,
      };
    }

    return result.rows[0];
  } catch (error) {
    return {
      error: "Falha na consulta ao banco de dados",
      details: error.message,
      status: 500,
    };
  }
}

import axios from "axios";

async function searchExternalDatabase(query: string) {
  try {
    const response = await axios.get(
      "https://api.external-service.com/search",
      {
        params: { q: query },
        headers: {
          Authorization: `Bearer ${process.env.EXTERNAL_API_KEY}`,
        },
      }
    );

    return response.data;
  } catch (error) {
    return {
      error: "Falha na chamada à API externa",
      details: error.message,
    };
  }
}

function validateInput(args: any, schema: any): { valid: boolean; error?: string } {
  // Valide campos obrigatórios
  for (const required of schema.required || []) {
    if (!(required in args)) {
      return { valid: false, error: `Parâmetro obrigatório ausente: ${required}` };
    }
  }

  // Valide tipos de campos
  for (const [key, property] of Object.entries(schema.properties || {})) {
    if (key in args) {
      const value = args[key];
      const expectedType = (property as any).type;

      if (typeof value !== expectedType) {
        return {
          valid: false,
          error: `O parâmetro ${key} deve ser do tipo ${expectedType}`,
        };
      }
    }
  }

  return { valid: true };
}

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
import OpenAI from "openai";

class MCPOpenAIBridge {
  private mcpClient: Client;
  private openaiClient: OpenAI;
  private availableTools: any[] = [];

  constructor() {
    this.openaiClient = new OpenAI({
      apiKey: process.env.OPENAI_API_KEY,
    });
  }

  async initialize() {
    // Conecta ao servidor MCP
    const transport = new StdioClientTransport({
      command: "node",
      args: ["dist/server.js"],
    });

    this.mcpClient = new Client({
      name: "openai-mcp-client",
      version: "1.0.0",
    });

    await this.mcpClient.connect(transport);

    // Descobre ferramentas disponíveis
    const toolsResponse = await this.mcpClient.listTools();
    this.availableTools = toolsResponse.tools;
  }

  async executeWithOpenAI(userMessage: string) {
    const messages = [{ role: "user" as const, content: userMessage }];

    // Converte ferramentas MCP para formato de função OpenAI
    const tools = this.availableTools.map((tool) => ({
      type: "function" as const,
      function: {
        name: tool.name,
        description: tool.description,
        parameters: tool.inputSchema,
      },
    }));

    let response = await this.openaiClient.chat.completions.create({
      model: "gpt-4",
      messages,
      tools,
    });

    // Lida com chamadas de ferramenta em loop
    while (response.choices[0].finish_reason === "tool_calls") {
      const toolCalls = response.choices[0].message.tool_calls || [];

      for (const toolCall of toolCalls) {
        const toolName = toolCall.function.name;
        const toolArgs = JSON.parse(toolCall.function.arguments);

        // Executa ferramenta no servidor MCP
        const toolResult = await this.mcpClient.callTool({
          name: toolName,
          arguments: toolArgs,
        });

        // Adiciona resultado da ferramenta às mensagens
        messages.push({
          role: "assistant",
          content: response.choices[0].message.content || "",
        });

        messages.push({
          role: "tool",
          content: JSON.stringify(toolResult),
          tool_call_id: toolCall.id,
        });
      }

      // Obtém próxima resposta do OpenAI
      response = await this.openaiClient.chat.completions.create({
        model: "gpt-4",
        messages,
        tools,
      });
    }

    return response.choices[0].message.content;
  }
}

// Uso
const bridge = new MCPOpenAIBridge();
await bridge.initialize();
const result = await bridge.executeWithOpenAI(
  "Qual é o histórico de pedidos do cliente 12345?"
);
console.log(result);

import crypto from "crypto";

class APIKeyManager {
  private validKeys: Set<string> = new Set();

  constructor() {
    // Carregue as chaves de API válidas do ambiente ou armazenamento seguro
    const keys = process.env.VALID_API_KEYS?.split(",") || [];
    this.validKeys = new Set(keys);
  }

  validateRequest(apiKey: string): boolean {
    return this.validKeys.has(apiKey);
  }

  generateNewKey(): string {
    return crypto.randomBytes(32).toString("hex");
  }
}

import crypto from "crypto";

function signRequest(payload: any, secret: string): string {
  return crypto
    .createHmac("sha256", secret)
    .update(JSON.stringify(payload))
    .digest("hex");
}

function verifySignature(payload: any, signature: string, secret: string): boolean {
  const expectedSignature = signRequest(payload, secret);
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

import rateLimit from "express-rate-limit";

const limiter = rateLimit({
  windowMs: 15 * 60 * 1000, // 15 minutos
  max: 100, // limita cada IP a 100 solicitações por janela
  message: "Muitas solicitações deste IP, tente novamente mais tarde.",
});

app.use("/api/", limiter);

function sanitizeInput(input: string): string {
  // Remove caracteres potencialmente perigosos
  return input
    .replace(/[<>]/g, "")
    .trim()
    .substring(0, 1000); // Limita tamanho
}

function validateCustomerId(customerId: string): boolean {
  // Permite apenas alfanuméricos e hífens
  return /^[a-zA-Z0-9-]+$/.test(customerId);
}

import { getCustomerInfo } from "../tools/customer";

describe("Ferramentas de Cliente", () => {
  test("deve retornar info do cliente para ID válido", async () => {
    const result = await getCustomerInfo("cust_123");
    expect(result).toHaveProperty("id");
    expect(result).toHaveProperty("name");
    expect(result).toHaveProperty("email");
  });

  test("deve retornar erro para ID inválido", async () => {
    const result = await getCustomerInfo("invalid");
    expect(result).toHaveProperty("error");
  });

  test("deve lidar graciosamente com erros do banco de dados", async () => {
    // Simula erro de banco
    const result = await getCustomerInfo("cust_error");
    expect(result).toHaveProperty("error");
    expect(result.status).toBe(500);
  });
});

describe("Integração do Servidor MCP", () => {
  let server: Server;

  beforeAll(async () => {
    server = new Server({ name: "test-server", version: "1.0.0" });
    // Inicializa o servidor
  });

  test("deve listar todas as ferramentas disponíveis", async () => {
    const tools = await server.listTools();
    expect(tools.length).toBeGreaterThan(0);
    expect(tools[0]).toHaveProperty("name");
    expect(tools[0]).toHaveProperty("description");
  });

  test("deve executar ferramenta e retornar resultado", async () => {
    const result = await server.callTool({
      name: "get_customer_info",
      arguments: { customer_id: "cust_123" },
    });
    expect(result).toBeDefined();
  });
});

FROM node:18-alpine

WORKDIR /app

COPY package*.json ./
RUN npm ci --only=production

COPY dist ./dist

EXPOSE 8000

CMD ["node", "dist/server.js"]

docker build -t my-mcp-server:1.0.0 .
docker push myregistry.azurecr.io/my-mcp-server:1.0.0

apiVersion: apps/v1
kind: Deployment
metadata:
  name: mcp-server
spec:
  replicas: 3
  selector:
    matchLabels:
      app: mcp-server
  template:
    metadata:
      labels:
        app: mcp-server
    spec:
      containers:
      - name: mcp-server
        image: myregistry.azurecr.io/my-mcp-server:1.0.0
        ports:
        - containerPort: 8000
        env:
        - name: OPENAI_API_KEY
          valueFrom:
            secretKeyRef:
              name: openai-secrets
              key: api-key
        - name: DATABASE_URL
          valueFrom:
            secretKeyRef:
              name: db-secrets
              key: connection-string
        resources:
          requests:
            memory: "256Mi"
            cpu: "250m"
          limits:
            memory: "512Mi"
            cpu: "500m"

# .env.production
OPENAI_API_KEY=sk-...
DATABASE_URL=postgresql://user:pass@host:5432/db
MCP_SERVER_PORT=8000
LOG_LEVEL=info
ENABLE_METRICS=true

async function processCustomerRefund(customerId: string, orderId: string, amount: number) {
  // Obtem info do cliente
  const customer = await getCustomerInfo(customerId);
  
  // Obtem detalhes do pedido
  const order = await getOrderDetails(orderId);
  
  // Verifica se o pedido pertence ao cliente
  if (order.customerId !== customerId) {
    throw new Error("O pedido não pertence ao cliente");
  }
  
  // Processa reembolso
  const refund = await createRefund(orderId, amount);
  
  // Envia notificação
  await sendNotification(customer.email, `Reembolso de R$${amount} processado`);
  
  return refund;
}

import NodeCache from "node-cache";

const cache = new NodeCache({ stdTTL: 600 }); // TTL de 10 minutos

async function getCustomerInfoWithCache(customerId: string) {
  const cacheKey = `customer_${customerId}`;
  
  // Verifica o cache primeiro
  const cached = cache.get(cacheKey);
  if (cached) {
    return cached;
  }
  
  // Busca no banco de dados
  const customer = await getCustomerInfo(customerId);
  
  // Armazena no cache
  cache.set(cacheKey, customer);
  
  return customer;
}

import Bull from "bull";

const jobQueue = new Bull("mcp-jobs");

jobQueue.process(async (job) => {
  const { toolName, arguments: args } = job.data;
  
  // Executa ferramenta
  const result = await executeTool(toolName, args);
  
  return result;
});

async function executeToolAsync(toolName: string, args: any) {
  const job = await jobQueue.add(
    { toolName, arguments: args },
    { attempts: 3, backoff: { type: "exponential", delay: 2000 } }
  );
  
  return job.id;
}

import winston from "winston";

const logger = winston.createLogger({
  format: winston.format.json(),
  transports: [
    new winston.transports.File({ filename: "error.log", level: "error" }),
    new winston.transports.File({ filename: "combined.log" }),
  ],
});

logger.info("Ferramenta executada", {
  toolName: "get_customer_info",
  customerId: "cust_123",
  duration: 145,
  status: "success",
});

import prometheus from "prom-client";

const toolExecutionDuration = new prometheus.Histogram({
  name: "mcp_tool_execution_duration_ms",
  help: "Duração da execução da ferramenta em milissegundos",
  labelNames: ["tool_name", "status"],
});

const toolExecutionCounter = new prometheus.Counter({
  name: "mcp_tool_executions_total",
  help: "Número total de execuções de ferramentas",
  labelNames: ["tool_name", "status"],
});

async function executeToolWithMetrics(toolName: string, args: any) {
  const startTime = Date.now();
  
  try {
    const result = await executeTool(toolName, args);
    const duration = Date.now() - startTime;
    
    toolExecutionDuration.labels(toolName, "success").observe(duration);
    toolExecutionCounter.labels(toolName, "success").inc();
    
    return result;
  } catch (error) {
    const duration = Date.now() - startTime;
    
    toolExecutionDuration.labels(toolName, "error").observe(duration);
    toolExecutionCounter.labels(toolName, "error").inc();
    
    throw error;
  }
}