Crie um servidor MCP

Adicione um servidor MCP quando um caso de uso do plugin exigir dados em tempo real, autenticação, ações controladas ou código executado em uma infraestrutura que você administra. O servidor define as ferramentas disponíveis para o ChatGPT e o Codex. Ele pode funcionar sem retornar uma interface personalizada.

Comece pelos objetivos que o plugin deve atender, conforme o seu inventário de casos de uso. Cada ferramenta deve ajudar o usuário a atingir um objetivo claro e disponibilizar apenas os dados e as ações necessários para isso.

Escolha um kit de desenvolvimento de software para MCP

Os kits oficiais de desenvolvimento de software oferecem utilitários para definir schemas, uma estrutura inicial para o 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:

1
2
3
4
5
6import { 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 o 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 orientar o uso de várias ferramentas, por exemplo, quando for obrigatório chamá-las em determinada ordem ou quando elas compartilharem um limite de taxa. 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.

1
2
3
4
5
6
7const 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 as ferramentas com base nos objetivos do usuário

Crie uma ferramenta para cada ação distinta que o plugin precisa 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 fácil de entender.
• Uma descrição que explique quando usá-la.
• Um schema de entrada explícito.
• Um schema de saída quando a ferramenta retornar dados estruturados.
• Anotações de segurança que reflitam o comportamento real da ferramenta.
• Uma função que autorize a requisição e execute a operação.

O modelo usa esses metadados para decidir se deve chamar a ferramenta e como fazer a chamada. Considere nomes, descrições, schemas e anotações como parte do comportamento do plugin que o usuário percebe.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49// Local example data; replace this with your application data.
const projects = [
  { id: "project-1", name: "Website", status: "active" },
  { id: "project-2", name: "Launch", status: "archived" },
];
async function listProjects({ status }: { status?: string }) {
  return projects.filter((project) => !status || project.status === status);
}

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 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 que ficam ocultos para o 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 em seguida possam fazer referência aos mesmos registros.

Não inclua segredos, tokens de acesso nem dados pessoais desnecessários nos resultados das ferramentas. O campo _meta oculta dados do modelo, mas não substitui a autorização nem o armazenamento seguro.

Autentique e autorize as requisições

Adicione autenticação quando uma ferramenta ler dados privados ou executar uma ação em nome de um usuário. Exija autorização no servidor MCP a cada requisição. Nunca deixe que o modelo decida se o usuário tem acesso.

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

Para facilitar o uso de várias contas, disponibilize uma ferramenta de perfil somente leitura que exija autenticação 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 distingui-las. Identifique o perfil a partir das credenciais validadas da requisição e restrinja cada chamada de ferramenta ao escopo dessas credenciais. Os usuários podem conectar várias contas mesmo sem uma ferramenta de perfil. Consulte Ofereça suporte a várias contas para ver o schema e um exemplo de implementação.

Anotações de ferramentas e elicitação

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

• readOnlyHint: use true somente quando a ferramenta não puder alterar o estado.
• destructiveHint: use true quando a ferramenta puder causar efeitos irreversíveis ou difíceis de reverter.
• openWorldHint: use true quando a ferramenta acessar a internet pública ou entidades externas sem escopo delimitado, inclusive em ações somente leitura, como a pesquisa na Web. Uma ferramenta restrita a uma conta privada ou a um espaço de trabalho de escopo delimitado pode usar false, mesmo que o serviço seja hospedado externamente.

As anotações ajudam o ChatGPT e o Codex a decidir quando pedir confirmação e quais medidas de segurança adotar. Elas não substituem os controles de autorização, validação ou confirmação do servidor.

Use a elicitação do MCP quando o servidor precisar de informações estruturadas que não tenham sido fornecidas na chamada original da ferramenta. Solicite apenas informações que o usuário tenha condições de fornecer. Não use a elicitação para coletar segredos nem para contornar o processo normal de autenticação.

Compatibilidade com o conhecimento da empresa

O recurso de conhecimento da empresa pode usar ferramentas somente leitura do seu servidor MCP. Para que um plugin possa servir como fonte de conhecimento da empresa, implemente os schemas de entrada padrão das ferramentas search e fetch e marque as demais ferramentas somente leitura com readOnlyHint: true.

Para as fontes que o modelo deve citar, retorne URLs absolutas que o usuário possa abrir. Mantenha os identificadores internos dos documentos no campo id do resultado. Para consultar os schemas obrigatórios e os formatos dos resultados, veja Como criar servidores MCP para integrações com o ChatGPT e a API.

Execute e teste localmente

Disponibilize um endpoint HTTP com suporte a streaming, geralmente 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 Inspector para:

1. Confirmar que a inicialização foi concluída com sucesso.
2. Revisar as instruções do servidor e a lista de ferramentas que ele disponibiliza.
3. Chamar cada ferramenta tanto com entradas representativas quanto com entradas inválidas.
4. Verificar schemas, resultados, erros e anotações.
5. Confirmar que o servidor exige autorização para acessar dados privados e executar ações de escrita.

Em seguida, conecte o servidor MCP personalizado ao ChatGPT e execute as solicitações do seu inventário de casos de uso, incluindo as diretas, as indiretas, as que testam casos extremos e as que estão fora do escopo.

Implante o endpoint

Para enviar um plugin para publicação, implante o servidor MCP em um endpoint HTTPS estável e acessível publicamente. O Secure MCP Tunnel permite conectar um servidor MCP privado ao ChatGPT, mas não atende aos requisitos para publicação.

O endpoint de produção deve:

• Oferecer suporte ao transporte HTTP do MCP com streaming.
• Responder em uma URL estável, geralmente terminada em /mcp.
• Atender aos requisitos de latência e disponibilidade dos fluxos de trabalho do plugin.
• Ter acesso aos serviços e repositórios de dados necessários.
• Respeitar os limites de autenticação e autorização.
• Gerar logs e métricas para falhas na inicialização e nas chamadas de ferramentas.

Se o servidor MCP precisar permanecer privado, implante um proxy HTTPS público que encaminhe as requisições MCP ao servidor privado. Use mTLS gerenciado pela OpenAI para autenticar o ChatGPT como cliente MCP e use OAuth 2.1 quando o plugin exigir autenticação de usuários. Se a rede exigir uma lista de IPs permitidos, use as faixas de IP publicadas para os conectores do ChatGPT 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 análise do plugin e a verificação do domínio. Ao enviar o plugin para publicação, não dependa exclusivamente do Secure MCP Tunnel. Também não use um túnel temporário nem um endpoint local.

Escolha a infraestrutura

Você pode implantar o servidor MCP em uma infraestrutura sem servidor, em contêineres, na borda da rede ou em uma infraestrutura tradicional de aplicativos. Ao escolher a plataforma, considere:

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

Se o servidor também hospedar recursos opcionais da interface, implante-os 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 no sistema de gerenciamento de segredos do host.
2. Configure o servidor de autorização e defina quais redirecionamentos são permitidos.
3. Aplique limites de tempo e limites de taxa às ferramentas que consomem muitos recursos ou são 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 de ferramentas que incluam informações sensíveis.

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

Planeje as atualizações

Mantenha os nomes e os schemas das ferramentas publicadas compatíveis com versões anteriores. Adicione campos ou ferramentas sem quebrar os contratos existentes. Se os metadados mudarem, atualize a conexão com o servidor MCP personalizado e execute novamente o conjunto de avaliações antes de enviar o plugin para publicação.

Se houver uma interface opcional, versione os identificadores de recursos sempre que uma alteração no HTML, no JavaScript ou no CSS puder comprometer o funcionamento de um componente em cache.

Adicione extensões do MCP

As extensões do MCP da OpenAI conectam o plugin à barra lateral, ao campo de mensagem e aos visualizadores de arquivos do ChatGPT. Consulte Extensões de plugins para ver exemplos e instruções de configuração.

Lembretes de segurança

• Trate todas as entradas das ferramentas como não confiáveis.
• Valide os parâmetros e exija autorização no servidor.
• Exija confirmação para ações de escrita com impacto significativo.
• Não inclua segredos nem dados sensíveis nos metadados ou nos resultados das ferramentas.
• Registre contexto suficiente para investigar falhas sem incluir credenciais ou dados pessoais desnecessários nos logs.
• Aplique limites de taxa às ações que consomem muitos recursos ou são visíveis externamente.