Crie um servidor MCP

Adicione um servidor MCP quando um caso de uso do plug-in precisar de dados em tempo real, autenticação, ações controladas ou código executado em uma infraestrutura que você opera. O servidor define as ferramentas disponíveis para o ChatGPT e o Codex. Ele não precisa retornar uma interface personalizada.

Comece pelos objetivos contemplados no seu inventário de casos de uso. Cada ferramenta deve ajudar a alcançar um objetivo claro do usuário e expor apenas os dados e as ações necessários para esse objetivo.

Escolha um kit de desenvolvimento de software para MCP

Os kits oficiais de desenvolvimento de software fornecem utilitários para esquemas, uma estrutura inicial de servidor e transporte HTTP com suporte a streaming:

• SDK para TypeScript, publicado como @modelcontextprotocol/sdk.
• SDK para Python, publicado como mcp.

Instale o SDK compatível com as tecnologias do seu servidor:

# TypeScript
npm install @modelcontextprotocol/sdk zod

# Python
pip install mcp

Crie o servidor

Crie um servidor MCP com nome e versão estáveis:

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

const server = new McpServer({
  name: "acme-projects",
  version: "1.0.0",
});

Os servidores MCP também podem retornar um campo instructions durante a inicialização. O ChatGPT e o Codex usam essas instruções junto com os metadados das ferramentas.

Use as instruções do servidor para orientações que se apliquem a várias ferramentas, como sequências obrigatórias de ferramentas ou limites de taxa compartilhados. Coloque os detalhes mais importantes nos primeiros 512 caracteres. Não repita a descrição de cada ferramenta nem tente mudar a personalidade do modelo.

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

Defina ferramentas com base nos objetivos do usuário

Crie uma ferramenta para cada ação distinta que o plug-in deve oferecer. Prefira operações específicas, como list_projects, get_project e update_project, a uma única ferramenta com vários modos sem relação entre si.

Cada ferramenta precisa de:

• Um nome que indique a ação e um título compreensível para as pessoas.
• Uma descrição que explique quando usá-la.
• Um esquema de entrada explícito.
• Um esquema de saída quando a ferramenta retornar dados estruturados.
• Anotações de segurança precisas.
• Uma função de tratamento que autorize a solicitação e execute a operação.

O modelo usa esses metadados para decidir se deve chamar a ferramenta e como fazer isso. Trate nomes, descrições, esquemas e anotações como parte do comportamento do plug-in percebido pelo usuário.

import { z } from "zod";

server.registerTool(
  "list_projects",
  {
    title: "List projects",
    description:
      "Use this when the user wants to find or review projects in their Acme workspace.",
    inputSchema: {
      status: z.enum(["active", "archived"]).optional(),
    },
    outputSchema: {
      projects: z.array(
        z.object({
          id: z.string(),
          name: z.string(),
          status: z.string(),
        })
      ),
    },
    annotations: {
      readOnlyHint: true,
      openWorldHint: false,
      destructiveHint: false,
    },
  },
  async ({ status }) => {
    const projects = await listProjects({ status });

    return {
      structuredContent: { projects },
      content: [
        {
          type: "text",
          text: `Found ${projects.length} projects.`,
        },
      ],
    };
  }
);

Retorne resultados úteis sem uma interface

O resultado de uma ferramenta pode incluir:

• structuredContent: dados concisos que o modelo pode examinar e usar em chamadas posteriores.
• content: texto ou outro conteúdo MCP que ajude o modelo a responder ao usuário.
• _meta: dados específicos do cliente, ocultos do modelo.

Retorne informações suficientes para que o modelo conclua o fluxo de trabalho sem um componente. Use identificadores estáveis nos resultados estruturados para que as ferramentas chamadas depois possam fazer referência aos mesmos registros.

Não inclua segredos, tokens de acesso ou dados pessoais desnecessários nos resultados das ferramentas. Trate _meta como algo oculto do modelo, não como um substituto para autorização ou armazenamento seguro.

Importe habilidades do servidor MCP

Configure o servidor MCP para fornecer habilidades quando quiser versionar e implantar as instruções e os arquivos de apoio delas junto com o servidor. Durante o envio do plug-in, Verificar ferramentas importa uma cópia estática dessas habilidades para o rascunho.

Atualmente, a OpenAI oferece suporte a um subconjunto estático e delimitado do rascunho da extensão de Habilidades SEP-2640. Essa proposta ainda não faz parte da especificação estável do MCP.

Anuncie a extensão

Declare io.modelcontextprotocol/skills nas capacidades de inicialização do servidor:

{
  "capabilities": {
    "extensions": {
      "io.modelcontextprotocol/skills": {}
    }
  }
}

A declaração deve estar em capabilities.extensions. A OpenAI não reconhece a declaração anterior em experimental.

Liste as habilidades e seus recursos

Ofereça suporte ao método paginado skills/list. Cada entrada deve incluir:

• Um uri que aponte para o SKILL.md da habilidade.
• frontmatter contendo todas as entradas extraídas do cabeçalho de metadados de SKILL.md. Inclua as entradas name e description.
• Uma lista resources completa contendo SKILL.md e todos os arquivos de apoio.
• Um hash SHA-256 para cada recurso no formato sha256:<64 lowercase hexadecimal characters>.

Use a convenção de URI skill://. O diretório que contém SKILL.md deve ter o mesmo nome da habilidade. Por exemplo:

{
  "skills": [
    {
      "uri": "skill://dice-roller/tabletop-dice/SKILL.md",
      "frontmatter": {
        "name": "tabletop-dice",
        "description": "Roll one or more dice and report each result and the total."
      },
      "resources": [
        {
          "uri": "skill://dice-roller/tabletop-dice/SKILL.md",
          "digest": "sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
        },
        {
          "uri": "skill://dice-roller/tabletop-dice/references/notation.md",
          "digest": "sha256:abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789"
        }
      ]
    }
  ],
  "nextCursor": "optional-next-page-cursor"
}

Os hashes do exemplo mostram o formato exigido. Para um recurso de texto, calcule o hash dos bytes UTF-8 de content.text. Para um recurso blob, decodifique de base64 o conteúdo de content.blob e depois calcule o hash dos bytes decodificados.

Ofereça também suporte a skills/get para cada URI listado de SKILL.md. Retorne um objeto skill com a mesma estrutura completa das entradas de skills/list.

Use estes parâmetros de solicitação:

• Para a primeira solicitação de skills/list, aceite um objeto vazio ({}).
• Para cada solicitação posterior de skills/list, aceite o cursor retornado, como { "cursor": "next-page-cursor" }.
• Para skills/get, aceite o URI do catálogo, como { "uri": "skill://dice-roller/tabletop-dice/SKILL.md" }.

Retorne todos os recursos listados

Ofereça suporte a resources/read para todos os URIs do manifesto. Retorne exatamente um item de conteúdo cujo URI corresponda ao da solicitação. A OpenAI aceita texto UTF-8 ou um blob codificado em base64.

Durante a importação, a OpenAI verifica se:

• A OpenAI consegue obter todos os recursos listados e confirmar seus hashes.
• O cabeçalho de metadados do SKILL.md obtido corresponde exatamente à entrada do catálogo.
• Os caminhos dos recursos são seguros, únicos e livres de conflitos de normalização.
• A habilidade completa respeita os limites de importação.

O importador aceita até cinco habilidades com nomes únicos, distribuídas por 10 páginas de catálogo. Cada habilidade pode conter até 100 arquivos, com os seguintes limites de tamanho:

O limite combinado dos arquivos compactados inclui o espaço adicional do empacotamento ZIP.

Se alguma entrada falhar na validação ou exceder um limite, Verificar ferramentas ainda retornará as ferramentas do servidor, mas não atualizará as habilidades importadas do rascunho. Corrija o servidor e execute a verificação novamente.

As habilidades importadas via MCP são cópias do momento do envio, não recursos atualizados em tempo de execução. Após alterar uma habilidade, execute Verificar ferramentas novamente, revise as habilidades importadas e envie uma nova versão do plug-in. Consulte Enviar plug-ins para ver o fluxo completo.

Autentique e autorize solicitações

Adicione autenticação quando uma ferramenta ler dados privados ou executar ações para um usuário. Exija autorização no servidor MCP para cada solicitação; nunca dependa do modelo para decidir se um usuário tem acesso.

Consulte Autenticar usuários para saber mais sobre descoberta OAuth, esquemas de segurança e desafios de autorização.

Para melhorar a experiência de uso de várias contas, disponibilize uma ferramenta de perfil autenticada e somente leitura e marque-a com _meta["openai/profile"]: true. A OpenAI usa as informações do perfil para identificar as contas conectadas de forma consistente e ajudar os usuários a diferenciá-las. Determine o perfil a partir das credenciais validadas da solicitação e mantenha cada chamada de ferramenta restrita ao escopo dessas credenciais. Os usuários podem conectar várias contas sem uma ferramenta de perfil. Consulte Oferecer suporte a várias contas para ver o esquema e o exemplo de implementação.

Anotações de ferramentas e elicitação

Defina as anotações de acordo com o comportamento real:

• readOnlyHint: true somente quando a ferramenta não puder alterar o estado.
• destructiveHint: true quando uma ferramenta puder causar resultados irreversíveis ou difíceis de reverter.
• openWorldHint: true quando uma ferramenta acessar a internet pública ou entidades externas sem escopo delimitado, inclusive por meio de ações somente leitura, como pesquisa na Web. Uma ferramenta restrita a uma conta privada ou a um workspace de escopo delimitado pode definir esse valor como false, mesmo quando o serviço for hospedado externamente.

As anotações ajudam o ChatGPT e o Codex a escolher o comportamento adequado de confirmação e segurança. Elas não substituem a autorização, a validação nem a confirmação no seu servidor.

Use a elicitação do MCP quando o servidor precisar de informações estruturadas que não foram fornecidas na chamada original da ferramenta. Limite a elicitação a informações que o usuário possa razoavelmente fornecer. Não a use para coletar segredos nem contornar a autenticação normal.

Compatibilidade com o conhecimento da empresa

O conhecimento da empresa pode usar ferramentas somente leitura do seu servidor MCP. Para tornar um plug-in elegível como fonte de conhecimento da empresa, implemente os esquemas padrão de entrada das ferramentas search e fetch e marque as outras ferramentas somente leitura com readOnlyHint: true.

Retorne URLs absolutas que o usuário possa abrir para as fontes que o modelo deve citar. Mantenha os identificadores internos dos documentos no campo id do resultado. Para consultar os esquemas e formatos de resultado exigidos, veja Criar servidores MCP para o ChatGPT e integrações com a API.

Execute e teste localmente

Exponha um endpoint HTTP com suporte a streaming, normalmente em /mcp, e inspecione-o com o MCP Inspector:

npx @modelcontextprotocol/inspector

Na interface do Inspector, selecione Streamable HTTP e insira http://localhost:3000/mcp.

Use o inspetor para:

1. Confirmar que a inicialização é concluída com sucesso.
2. Revisar as instruções do servidor e a lista de ferramentas anunciadas.
3. Chamar cada ferramenta com entradas representativas e inválidas.
4. Verificar esquemas, resultados, erros e anotações.
5. Confirmar que a autorização é exigida para dados privados e ações de escrita.

Em seguida, conecte o servidor ao ChatGPT no modo de desenvolvedor e execute as solicitações diretas, indiretas, de casos extremos e fora do escopo do seu inventário de casos de uso.

Implante o endpoint

Para enviar um plug-in para publicação, implante o servidor MCP em um endpoint HTTPS estável e acessível publicamente. O Túnel MCP seguro pode conectar um servidor MCP privado no modo de desenvolvedor, mas não atende aos requisitos de envio para publicação.

O endpoint de produção deve:

• Oferecer suporte ao transporte Streamable HTTP do MCP.
• Responder em uma URL estável, normalmente terminada em /mcp.
• Atender às necessidades de latência e disponibilidade dos fluxos de trabalho do plug-in.
• Acessar os serviços e repositórios de dados necessários.
• Preservar os limites de autenticação e autorização.
• Gerar logs e métricas para falhas de inicialização e de chamadas de ferramentas.

Se o servidor MCP precisar permanecer privado, implante um proxy HTTPS público que encaminhe as solicitações MCP ao servidor privado. Use mTLS gerenciado pela OpenAI para autenticar o ChatGPT como cliente MCP e use OAuth 2.1 quando seu plug-in exigir autenticação do usuário. Se sua rede exigir uma lista de IPs permitidos, use os intervalos de IP dos conectores do ChatGPT publicados e atualize a lista automaticamente. Uma lista de IPs permitidos não substitui a autenticação nem a autorização.

O endpoint público deve permanecer acessível para a revisão do plug-in e a verificação de domínio. Não use apenas o Túnel MCP seguro, um túnel temporário ou um endpoint local para o envio para publicação.

Escolha a infraestrutura

Você pode implantar o servidor MCP em uma infraestrutura sem servidor, de contêineres, de borda ou tradicional para aplicativos. Escolha uma plataforma com base em:

• Suporte ao ambiente de execução e às dependências.
• Comportamento das respostas em streaming.
• Latência de inicialização a frio e das solicitações.
• Acesso pela rede aos serviços necessários.
• Requisitos de residência de dados e conformidade.
• Gerenciamento de segredos.
• Registro de logs, rastreamento e alertas.
• Suporte a reversão e versionamento.

Se o servidor também hospedar arquivos de interface opcionais, implante esses arquivos em origens estáveis permitidas pela política de segurança de conteúdo do componente.

Configure o endpoint de produção

Antes da implantação:

1. Defina as credenciais de produção pelo sistema de gerenciamento de segredos do host.
2. Configure o servidor de autorização e o comportamento de redirecionamento permitido.
3. Aplique tempos limite e limites de taxa a ferramentas de alto custo ou visíveis externamente.
4. Remova as respostas de depuração e os dados pessoais desnecessários.
5. Confirme que os logs não contêm tokens de acesso nem resultados sensíveis de ferramentas.

Após a implantação, chame o endpoint de produção com o MCP Inspector. Verifique a inicialização, as instruções do servidor, as ferramentas, os esquemas, as anotações, a autenticação, os resultados e os erros.

Planeje as atualizações

Mantenha a compatibilidade dos nomes e esquemas das ferramentas publicadas com versões anteriores. Adicione campos ou ferramentas sem quebrar os contratos existentes. Se os metadados mudarem, atualize a conexão no modo de desenvolvedor e execute novamente o conjunto de avaliações antes do envio.

Para interfaces opcionais, versione os identificadores de recursos quando alterações no HTML, JavaScript ou CSS puderem impedir o funcionamento de um componente em cache.

Adicione uma interface opcional

Depois que as ferramentas funcionarem de ponta a ponta, decida se algum caso de uso precisa de interação visual. Uma tabela, um mapa, uma agenda editável ou uma visualização comparativa pode se beneficiar de uma interface. Uma consulta, uma verificação de status ou uma ação em segundo plano geralmente não precisa disso.

Continue com Adicionar uma interface ao seu servidor MCP para registrar um recurso MCP Apps e associá-lo às ferramentas selecionadas.

Lembretes de segurança

• Trate toda entrada de ferramenta como não confiável.
• Valide os parâmetros e exija autorização no servidor.
• Exija confirmação para ações de escrita com consequências significativas.
• Não inclua segredos nem dados sensíveis nos metadados e resultados das ferramentas.
• Registre contexto suficiente nos logs para investigar falhas, sem registrar credenciais ou dados pessoais desnecessários.
• Aplique limites de taxa a ações custosas ou visíveis externamente.