Ensimmäinen lisäosasi
Tällä sivulla
Oppitunti kirjoitettu uudelleen 3. marraskuuta 2026 perustuen OpenAI:n lisäosadokumentaation sivuihin Quickstart, MCP server and UI quickstart ja Connect and test your plugin. Aiempi “sääsovellus 30 minuutissa” -esimerkki nojasi olemattomaan SDK:hon. Tarkistimme npm-pakettien versiot 3. marraskuuta 2026:
@modelcontextprotocol/ext-apps2.x rakentuu MCP SDK v2:n päälle, kun taas OpenAI:n esimerkit käyttävät versiota v1. Lähteet: Quickstart · MCP server and UI quickstart · Connect and test.
Kaksi vaihetta
Ensin yhdistät olemassa olevan MCP-palvelimen nähdäksesi koko ChatGPT-työnkulun kirjoittamatta riviäkään koodia. Seuraavaksi kirjoitat oman palvelimesi, testaat sitä paikallisesti ja yhdistät sen samalla tavalla.
Vaihe 1: Henkilökohtainen lisäosa viidessä minuutissa
OpenAI tarjoaa julkisen, todentamattoman esimerkki-MCP-palvelimen, joka paljastaa yhden vain luku -työkalun: roll_dice.
- Siirry osoitteeseen ChatGPT Plugins, valitse +-painike ja valitse sitten Add custom MCP server.
- Anna nimi ja aseta Server URL osoitteeksi
https://tinymcp.dev/api/moldy-aloof-zettabyte/mcp. Valitse No authentication. - Lue riskivaroitus, valitse I understand and want to continue ja napsauta Create as a plugin.
- Lisäosa ilmestyy henkilökohtaisten lisäosiesi luetteloon: avaa se ja asenna se käyttämällä +-painiketta.
- Palaa ChatGPT:n etusivulle, siirry välilehdeltä Chat välilehdelle Work, aloita uusi keskustelu, kirjoita
@ja valitse lisäosasi. - Pyydä sitä heittämään 20-tahkoista noppaa: sen tulisi kutsua
roll_dicetäsmälleen kerran asettaensidesarvoksi 20 ja palauttaa arvo väliltä 1–20.
Älä tyydy vain onnistuneeseen polkuun. Kokeile eri kokoisia noppia, virheellisiä arvoja ja pyyntöjä, jotka eivät saisi laukaista mitään työkalua. Tämä refleksi ohjaa koko kurssia: kun malli valitsee väärän työkalun tai vaihtelee sen argumentteja, sinun on hienosäädettävä työkalun kuvausta ja skeemaa. Huomaa myös, että tilisi tai työtilasi käytännöt säätelevät mukautettujen MCP-palvelimien lisäämistä: organisaatiossa tämä vaihtoehto voi olla rajoitettu.
Vaihe 2: Oma palvelimesi
Virallisten SDK:iden asentaminen
Protokollalle on olemassa viralliset SDK:t TypeScriptille (@modelcontextprotocol/sdk) ja Pythonille (mcp). Tämä kurssi seuraa OpenAI:n esimerkkejä, jotka on kirjoitettu TypeScriptillä käyttäen SDK:n versiota v1. Lukitse versiosi: syyskuuhun 2026 mennessä @modelcontextprotocol/ext-apps 2.x – rajapintapaketti, jonka lisäät oppitunnilla 6 – nojaa uusiin v2 SDK -paketteihin (@modelcontextprotocol/server…), jotka eivät ole yhteensopivia v1-tuontien kanssa.
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
npm pkg set type=module lisää "type": "module" tiedostoon package.json, mikä vaaditaan palvelimen import-lauseille.
Palvelimen kirjoittaminen
Tämä palvelin mahtuu yhteen tiedostoon, server.js. Se pitää muistiinpanot muistissa ja paljastaa kaksi työkalua: yhden lukemista ja yhden kirjoittamista varten, erotettuna kuten oppitunnilla 3 suositeltiin.
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 = []; // esimerkki muistissa pidettävästä datasta: korvaa omalla tallennusratkaisullasi
const schemaNotes = {
notes: z.array(z.object({ id: z.string(), text: z.string() })),
};
function creerServeur() {
const server = new McpServer({ name: "notes-demo", version: "0.1.0" });
server.registerTool(
"list_notes",
{
title: "List notes",
description: "Use when the user wants to review notes saved with this plugin.",
inputSchema: {},
outputSchema: schemaNotes,
annotations: { readOnlyHint: true, openWorldHint: false, destructiveHint: false },
},
async () => ({
structuredContent: { notes },
content: [{ type: "text", text: `${notes.length} note(s) saved.` }],
})
);
server.registerTool(
"add_note",
{
title: "Add a note",
description: "Use when the user asks to save a short note.",
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: "Note saved." }],
};
}
);
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;
}
// Tilaton tila: uusi palvelin ja kuljetuskerros jokaista pyyntöä kohti
const server = creerServeur();
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`));
Kolme yksityiskohtaa ovat tärkeitä. Jokainen työkalu määrittelee otsikon, aikomuskuvauksen, skeemat ja tarkat annotaatiot: tämä on sen “profiili” mallille. Jokainen tulos yhdistää structuredContent-kentän, jota malli voi käyttää uudelleen, ja content-kentän, joka on lyhyt tekstiviesti. Lopuksi mikä tahansa osoite muu kuin /mcp palauttaa 404-virheen: OpenAI:n esimerkki tekee näin OAuth-löytöreiteille, joita et vielä käytä, estäen ChatGPT:tä näyttämästä 502-virheitä todentamattomien testiesi aikana. Sama esimerkki lisää vastauksen alustavaan CORS-pyyntöön (OPTIONS) ja GET /-pyyntöön tilatarkistuksia varten; sisällytä nämä, jos isännöintiympäristösi odottaa niitä.
Paikallinen testaus MCP Inspectorilla
node server.js
npx @modelcontextprotocol/inspector@latest
Valitse Inspectorissa Streamable HTTP, syötä http://localhost:8787/mcp ja muodosta yhteys. Varmista, että alustus onnistuu, että molemmat työkalut näkyvät skeemoineen ja annotaatioineen, ja kutsu niitä kelvollisilla ja virheellisillä syötteillä – tyhjän merkkijonon tulee hylätä skeeman perusteella.
Palvelimen julkistaminen ja yhdistäminen
ChatGPT:n on pystyttävä tavoittamaan palvelimesi internetistä. Kehitysvaiheen aikana tunneli riittää – dokumentaatio mainitsee ngrok:n:
ngrok http 8787
Saat julkisen HTTPS-osoitteen. Yhdistä se kuten vaiheessa 1, mukaan lukien /mcp-polku (esimerkiksi https://<subdomain>.ngrok.app/mcp), asenna syntynyt lisäosa ja kutsu sitä käyttämällä @: “Tallenna muistiinpano: soita toimittajalle maanantaina.” ChatGPT näyttää työkalun kanssa vaihdetut tiedot, jolloin voit varmistaa syötteet ja tulosteet.
Kehitystunneli toimii vain kokeiluihin: julkaiseminen vaatii vakaan, julkisen HTTPS-päätepisteen (oppitunti 5).
Lataa uudelleen jokaisen muutoksen jälkeen
ChatGPT välimuististaa palvelimesi metatiedot. Nimen, kuvauksen, skeeman, annotaation, todennuksen tai rajapintaresurssin muutoksen jälkeen: ota käyttöön uusi versio tai käynnistä palvelin uudelleen, avaa yhteys osoitteessa chatgpt.com/plugins, valitse Refresh, varmista, että ilmoitetut metatiedot ovat muuttuneet, ja avaa sitten uusi keskustelu testien uudelleen suorittamiseksi. Tämän vaiheen ohittaminen tarkoittaa, että testaat vanhaa versiota huomaamatta sitä.
Keskeiset asiat
- Luo henkilökohtainen lisäosa valitsemalla Add custom MCP server ja kutsu sitä merkillä
@ChatGPT:ssä - Viralliset SDK:t:
@modelcontextprotocol/sdk(TypeScript) jamcp(Python); lukitse v1 käyttämälläext-apps1.x seurataksesi OpenAI:n esimerkkejä - Minimaalinen palvelin:
McpServer,registerTool, streamable HTTP -kuljetuskerros polussa/mcp - Käytä MCP Inspectoria paikalliseen testaukseen ja tunnelia ChatGPT-kokeiluihin
- Metatietojen muutosten jälkeen: Refresh ja aloita uusi keskustelu