Ir para o conteúdo principal
Português— Escolher um idioma
Menu

O Servidor MCP: Ferramentas, Resultados e Implementação

Aula 5 de 14 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. O servidor, a sua identidade e as suas instruções
  2. Uma ferramenta por ação
  3. Resultados úteis sem interface
  4. Anotações e elicitação
  5. Múltiplas contas e conhecimento da empresa
  6. Implementação do endpoint
  7. Evoluir sem quebrar
  8. Lembretes de segurança
  9. Pontos-chave

Lição reescrita a 3 de novembro de 2026 com base na página Build an MCP server da documentação de Plugins da OpenAI e no código do MCP TypeScript SDK (1.32.2). A lição anterior descrevia “ações” (defineAction, ActionError) de um SDK inexistente; esta função pertence agora às ferramentas MCP. Fontes: Build an MCP server · MCP TypeScript SDK.

O servidor, a sua identidade e as suas instruções

Crie um servidor MCP com um nome e uma versão estáveis. Durante a inicialização, pode também devolver um campo instructions que o ChatGPT e o Codex leem em conjunto com os metadados das ferramentas. Reserve este campo para diretrizes aplicáveis a todas as ferramentas — como uma ordem de chamada obrigatória ou um limite de taxa partilhado — e mantenha o conteúdo central dentro dos primeiros 512 caracteres. Não copie e cole aqui descrições de ferramentas e não tente alterar a personalidade do modelo.

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";

const server = new McpServer(
  { name: "acme-projects", version: "1.0.0" },
  {
    instructions:
      "Before modifying a project, call get_project to confirm its ID and status.",
  }
);

Uma ferramenta por ação

Crie uma ferramenta para cada ação distinta: list_projects, get_project, update_project, em vez de uma única ferramenta genérica com numerosos modos. Cada ferramenta combina um nome orientado para a ação, um título legível, uma descrição que explica quando utilizá-la, um esquema de entrada explícito, um esquema de saída se devolver dados estruturados, anotações precisas e um manipulador que autoriza o pedido antes de atuar. O modelo depende destes metadados para decidir se e como chamar a ferramenta — trate-os como parte da experiência do utilizador.

import { z } from "zod";

const project = z.object({ id: z.string(), name: z.string(), status: z.enum(["active", "archived"]) });

server.registerTool(
  "get_project",
  {
    title: "View a project",
    description:
      "Use when the user wants details about a specific project in their Acme workspace. " +
      "Requires the ID returned by list_projects.",
    inputSchema: { id: z.string().min(1) },
    outputSchema: { project: project },
    annotations: { readOnlyHint: true, openWorldHint: false, destructiveHint: false },
  },
  async ({ id }, extra) => {
    const user = await authenticate(extra); // Your access control (Lesson 8)
    const found = await loadProject(user, id); // Your data access
    if (!found) {
      return {
        isError: true,
        content: [{ type: "text", text: `No project ${id} is accessible with this account.` }],
      };
    }
    return {
      structuredContent: { project: found },
      content: [{ type: "text", text: `Project "${found.name}" (${found.status}).` }],
    };
  }
);

authenticate e loadProject são as suas próprias funções. O ponto crítico é a sua colocação: a autorização ocorre no servidor, com cada pedido. Nunca confie no modelo para decidir se um utilizador tem permissão para aceder a dados.

Resultados úteis sem interface

Um resultado de ferramenta pode conter três elementos:

  • structuredContent: dados concisos que o modelo pode inspecionar e reutilizar em chamadas subsequentes;
  • content: texto ou outro conteúdo MCP que o ajude a responder;
  • _meta: dados destinados ao cliente, ocultos ao modelo.

Devolva informação suficiente para o modelo concluir a tarefa sem um componente visual, utilizando IDs estáveis que ferramentas subsequentes possam reutilizar. Dois comportamentos do SDK merecem destaque. Uma ferramenta que declare um outputSchema deve devolver structuredContent compatível em todos os resultados bem-sucedidos; caso contrário, o SDK lança um erro de validação. Um erro de negócio — como um projeto em falta ou uma ação negada — é sinalizado por um resultado com isError: true acompanhado de texto explicativo que o modelo pode retransmitir ao utilizador; este tipo de resultado ignora a validação do esquema de saída.

Nunca inclua segredos, tokens de acesso ou dados pessoais desnecessários num resultado e não trate _meta como um esconderijo seguro: este campo está oculto do modelo, mas não está protegido.

Anotações e elicitação

As anotações devem refletir o comportamento real da ferramenta: defina readOnlyHint como true apenas se não puder modificar nada, destructiveHint como true se puder causar um efeito irreversível ou difícil de desfazer, e openWorldHint como true se tocar na internet pública ou em entidades externas abertas. Elas ajudam o ChatGPT e o Codex a escolher o comportamento de confirmação adequado; não substituem a lógica de autorização, validação ou confirmação no seu servidor.

Quando o servidor necessitar de informações estruturadas em falta na chamada — como uma data ou uma escolha entre duas opções — pode solicitá-las através da elicitação, um mecanismo do protocolo MCP. Limite isto ao que o utilizador pode razoavelmente fornecer; nunca o utilize para recolher segredos ou contornar a autenticação normal.

Múltiplas contas e conhecimento da empresa

Duas compatibilidades opcionais melhoram a integração. Para ajudar utilizadores que ligam múltiplas contas, exponha uma ferramenta de perfil que seja autenticada, só de leitura e marcada com _meta["openai/profile"]: true. A OpenAI utiliza isto para identificar contas ligadas e ajudar os utilizadores a distingui-las. O perfil é derivado das credenciais validadas do pedido e cada chamada permanece limitada a essas credenciais.

A funcionalidade company knowledge do ChatGPT pode utilizar as suas ferramentas só de leitura. Para tornar um plugin elegível como fonte, implemente os esquemas de entrada padrão para ferramentas search e fetch, marque outras ferramentas só de leitura com readOnlyHint: true e devolva URLs absolutos, abertos pelo utilizador, para as fontes que o modelo deve citar.

Implementação do endpoint

O envio público requer um servidor num endereço HTTPS estável e publicamente acessível. Este endpoint deve suportar o transporte streamable HTTP, responder num URL estável (tipicamente terminando em /mcp), satisfazer as exigências de latência e disponibilidade dos seus fluxos de trabalho, alcançar os seus serviços e dados, preservar os limites de autenticação e autorização e produzir registos e métricas para falhas de inicialização e chamadas de ferramentas.

O Secure MCP Tunnel da OpenAI permite ligar um servidor privado ao ChatGPT, mas não satisfaz os requisitos de envio público, tal como um túnel temporário ou um endereço local. Se o servidor tiver de permanecer privado, coloque um proxy HTTPS público à sua frente: o mTLS gerido pela OpenAI autentica o ChatGPT como cliente, o OAuth 2.1 autentica os seus utilizadores e uma lista de permissão de IP — incluindo intervalos publicados pela OpenAI para conectores do ChatGPT, atualizados automaticamente — pode ser adicionada, mas nunca substitui a autenticação.

Antes de entrar em produção: injete credenciais através do gestor de segredos do seu hospedeiro, configure o servidor de autorização e redirecionamentos, defina tempos limite e limites de taxa para ferramentas dispendiosas ou visíveis externamente, remova respostas de depuração e dados pessoais desnecessários e verifique se os registos não contêm tokens ou resultados sensíveis. Após a implementação, reproduza o MCP Inspector contra o endereço de produção.

Evoluir sem quebrar

Mantenha os nomes e esquemas de ferramentas publicados compatíveis com versões anteriores: adicione campos ou ferramentas, mas não quebre contratos existentes. Se os metadados mudarem, atualize a ligação e reproduza o seu conjunto de avaliação antes de submeter. Para uma interface, altere o ID do recurso quando o HTML, JavaScript ou CSS evoluírem de forma a poder quebrar um componente em cache.

Lembretes de segurança

  • Toda a entrada de ferramentas não é confiável: valide-a e imponha a autorização no servidor
  • Exija confirmação para escritas de alto impacto
  • Mantenha segredos e dados sensíveis fora dos metadados e resultados
  • Registe o suficiente para investigar, mas exclua credenciais e dados pessoais desnecessários
  • Limite a taxa de ações dispendiosas ou visíveis externamente

Pontos-chave

  • Um servidor nomeado e versionado com instructions curtas e transversais
  • Uma ferramenta por ação, com título, descrição da intenção, esquemas, anotações e autorização no manipulador
  • structuredContent compatível com o esquema de saída, isError: true para erros de negócio, nada secreto em _meta
  • Publicação: HTTPS estável e público via streamable HTTP; o Secure MCP Tunnel é insuficiente
  • Contratos compatíveis com versões anteriores e IDs de recursos versionados