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

O Seu Primeiro Plugin

Aula 4 de 14 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. Dois Passos
  2. Passo 1: Um Plugin Pessoal em Cinco Minutos
  3. Passo 2: O Seu Próprio Servidor
  4. Recarregar Após Cada Alteração
  5. Pontos-chave

Lição reescrita a 3 de novembro de 2026 com base nas páginas Quickstart, MCP server and UI quickstart e Connect and test your plugin da documentação de Plugins da OpenAI. O exemplo anterior de “aplicação meteorológica em 30 minutos” baseava-se num SDK inexistente. Verificámos as versões dos pacotes npm a 3 de novembro de 2026: o @modelcontextprotocol/ext-apps 2.x constrói sobre o MCP SDK v2, enquanto os exemplos da OpenAI utilizam a v1. Fontes: Quickstart · MCP server and UI quickstart · Connect and test.

Dois Passos

Primeiro, vai ligar um servidor MCP existente para observar o fluxo de trabalho completo do ChatGPT sem escrever uma única linha de código. De seguida, vai escrever o seu próprio servidor, testá-lo localmente e ligá-lo da mesma forma.

Passo 1: Um Plugin Pessoal em Cinco Minutos

A OpenAI disponibiliza um servidor MCP de exemplo público e não autenticado que expõe uma única ferramenta de leitura: roll_dice.

  1. Aceda a ChatGPT Plugins, selecione o botão + e escolha Add custom MCP server.
  2. Introduza um nome e defina o Server URL como https://tinymcp.dev/api/moldy-aloof-zettabyte/mcp. Selecione No authentication.
  3. Leia o aviso de risco, selecione I understand and want to continue e clique em Create as a plugin.
  4. O plugin aparece na sua lista de plugins pessoais: abra-o e instale-o utilizando o botão +.
  5. Regresse ao ecrã inicial do ChatGPT, mude do separador Chat para Work, inicie uma nova conversa, escreva @ e selecione o seu plugin.
  6. Peça-lhe para lançar um dado de vinte faces: deve chamar roll_dice exatamente uma vez com sides definido como 20 e devolver um valor entre 1 e 20.

Não se limite ao cenário ideal. Experimente diferentes tamanhos de dados, valores inválidos e pedidos que não devem acionar qualquer ferramenta. Este reflexo impulsiona o resto do curso: quando o modelo escolhe a ferramenta errada ou varia os seus argumentos, precisa de refinar a descrição e o esquema da ferramenta. Note também que as políticas da sua conta ou espaço de trabalho regem a adição de servidores MCP personalizados: numa organização, esta opção pode estar restrita.

Passo 2: O Seu Próprio Servidor

Instalar os SDKs Oficiais

Existem SDKs oficiais do protocolo para TypeScript (@modelcontextprotocol/sdk) e Python (mcp). Este curso segue os exemplos da OpenAI, escritos em TypeScript utilizando o SDK v1. Fixe as suas versões: em setembro de 2026, o @modelcontextprotocol/ext-apps 2.x — o pacote de interface que adicionará na Lição 6 — depende dos novos pacotes SDK v2 (@modelcontextprotocol/server…), que são incompatíveis com as importações v1.

mkdir notes-plugin && cd notes-plugin
npm init -y
npm pkg set type=module
npm install @modelcontextprotocol/sdk@^1.29 @modelcontextprotocol/ext-apps@^1.7 zod

O comando npm pkg set type=module adiciona "type": "module" ao package.json, obrigatório para as instruções import do servidor.

Escrever o Servidor

Este servidor cabe num único ficheiro, server.js. Mantém notas na memória e expõe duas ferramentas: uma para leitura e outra para escrita, separadas conforme recomendado na Lição 3.

import { createServer } from "node:http";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
import { z } from "zod";

const notes = []; // exemplo de dados em memória: substitua pelo seu próprio armazenamento
const schemaNotes = {
  notes: z.array(z.object({ id: z.string(), text: z.string() })),
};

function criarServidor() {
  const server = new McpServer({ name: "notes-demo", version: "0.1.0" });

  server.registerTool(
    "list_notes",
    {
      title: "Listar notas",
      description: "Utilize quando o utilizador quiser rever as notas guardadas com este plugin.",
      inputSchema: {},
      outputSchema: schemaNotes,
      annotations: { readOnlyHint: true, openWorldHint: false, destructiveHint: false },
    },
    async () => ({
      structuredContent: { notes },
      content: [{ type: "text", text: `${notes.length} nota(s) guardada(s).` }],
    })
  );

  server.registerTool(
    "add_note",
    {
      title: "Adicionar uma nota",
      description: "Utilize quando o utilizador pedir para guardar uma nota curta.",
      inputSchema: { text: z.string().min(1).max(500) },
      outputSchema: schemaNotes,
      annotations: { readOnlyHint: false, openWorldHint: false, destructiveHint: false },
    },
    async ({ text }) => {
      notes.push({ id: `note-${notes.length + 1}`, text });
      return {
        structuredContent: { notes },
        content: [{ type: "text", text: "Nota guardada." }],
      };
    }
  );

  return server;
}

const PORT = Number(process.env.PORT ?? 8787);

createServer(async (req, res) => {
  const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
  if (url.pathname !== "/mcp") {
    res.writeHead(404).end("Not Found");
    return;
  }

  // Modo sem estado: novo servidor e transporte por pedido
  const server = criarServidor();
  const transport = new StreamableHTTPServerTransport({
    sessionIdGenerator: undefined,
    enableJsonResponse: true,
  });
  res.on("close", () => {
    transport.close();
    server.close();
  });

  try {
    await server.connect(transport);
    await transport.handleRequest(req, res);
  } catch (error) {
    console.error("MCP Error:", error);
    if (!res.headersSent) res.writeHead(500).end("Internal server error");
  }
}).listen(PORT, () => console.log(`MCP server ready on http://localhost:${PORT}/mcp`));

Três detalhes são importantes. Cada ferramenta declara um título, uma descrição da intenção, esquemas e anotações exatas: este é o seu “perfil” para o modelo. Cada resultado combina structuredContent, reutilizável pelo modelo, e content, uma mensagem de texto curta. Finalmente, qualquer endereço que não seja /mcp devolve um 404: o exemplo da OpenAI faz isto para rotas de descoberta OAuth que ainda não está a utilizar, impedindo que o ChatGPT mostre erros 502 durante os seus testes não autenticados. Esse mesmo exemplo adiciona uma resposta para o pedido CORS preliminar (OPTIONS) e um GET / para sondas de saúde; inclua-os se a sua hospedagem os exigir.

Testar Localmente com o MCP Inspector

node server.js
npx @modelcontextprotocol/inspector@latest

No Inspector, escolha Streamable HTTP, introduza http://localhost:8787/mcp e ligue-se. Verifique se a inicialização é bem-sucedida, se ambas as ferramentas aparecem com os seus esquemas e anotações e, em seguida, chame-as com entradas válidas e inválidas — uma cadeia de texto vazia deve ser rejeitada pelo esquema.

Expor o Servidor e Ligá-lo

O ChatGPT deve conseguir aceder ao seu servidor a partir da Internet. Durante o desenvolvimento, um túnel é suficiente — a documentação cita o ngrok:

ngrok http 8787

Obtém um endereço HTTPS público. Ligue-o como no Passo 1, incluindo o caminho /mcp (por exemplo https://<subdomain>.ngrok.app/mcp), instale o plugin resultante e invoque-o com @: “Guarda uma nota: liga ao fornecedor segunda-feira.” O ChatGPT apresenta os dados trocados com a ferramenta, permitindo-lhe verificar as entradas e saídas.

Um túnel de desenvolvimento serve apenas para testes: a publicação requer um ponto final HTTPS público e estável (Lição 5).

Recarregar Após Cada Alteração

O ChatGPT coloca em cache os metadados do seu servidor. Após qualquer alteração ao nome, descrição, esquema, anotação, autenticação ou recurso de interface: reimplemente ou reinicie o servidor, abra a ligação em chatgpt.com/plugins, selecione Refresh, verifique se os metadados anunciados foram alterados e, em seguida, abra uma nova conversa para voltar a executar os seus testes. Ignorar este passo significa testar a versão antiga sem se aperceber.

Pontos-chave

  • Crie um plugin pessoal através de Add custom MCP server e invoque-o com @ no ChatGPT
  • SDKs oficiais: @modelcontextprotocol/sdk (TypeScript) e mcp (Python); fixe a v1 com ext-apps 1.x para seguir os exemplos da OpenAI
  • Servidor mínimo: McpServer, registerTool, transporte streamable HTTP em /mcp
  • Utilize o MCP Inspector para testes locais e um túnel para testes no ChatGPT
  • Após qualquer alteração de metadados: Refresh e, em seguida, inicie uma nova conversa