O Seu Primeiro Plugin
Nesta página
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-apps2.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.
- Aceda a ChatGPT Plugins, selecione o botão + e escolha Add custom MCP server.
- Introduza um nome e defina o Server URL como
https://tinymcp.dev/api/moldy-aloof-zettabyte/mcp. Selecione No authentication. - Leia o aviso de risco, selecione I understand and want to continue e clique em Create as a plugin.
- O plugin aparece na sua lista de plugins pessoais: abra-o e instale-o utilizando o botão +.
- Regresse ao ecrã inicial do ChatGPT, mude do separador Chat para Work, inicie uma nova conversa, escreva
@e selecione o seu plugin. - Peça-lhe para lançar um dado de vinte faces: deve chamar
roll_diceexatamente uma vez comsidesdefinido 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) emcp(Python); fixe a v1 comext-apps1.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