Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

MCP-palvelin: Työkalut, tulokset ja käyttöönotto

Oppitunti 5 / 14 Päivitetty 3. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. Palvelin, sen identiteetti ja ohjeistukset
  2. Yksi työkalu per toiminto
  3. Hyödyllisiä tuloksia ilman käyttöliittymää
  4. Annotaatiot ja tiedustelu
  5. Useat tilit ja yritystieto
  6. Päätepisteen käyttöönotto
  7. Kehittäminen rikkomatta toimivuutta
  8. Muistutukset turvallisuudesta
  9. Keskeiset asiat

Oppitunti kirjoitettu uudelleen 3. marraskuuta 2026 perustuen OpenAI Plugins -dokumentaation Build an MCP server -sivuun ja MCP TypeScript SDK:n koodiin (1.32.2). Edellinen oppitunti kuvasi olemattomasta SDK:sta peräisin olevia “toimintoja” (defineAction, ActionError); tämä rooli kuuluu nyt MCP-työkaluille. Lähteet: Build an MCP server · MCP TypeScript SDK.

Palvelin, sen identiteetti ja ohjeistukset

Luo MCP-palvelin vakaalla nimellä ja versiolla. Alustuksen aikana se voi palauttaa myös instructions-kentän, jonka ChatGPT ja Codex lukevat työkalujen metatietojen rinnalla. Varaa tämä kenttä ohjeille, jotka koskevat kaikkia työkaluja – kuten pakollinen kutsujärjestys tai yhteinen nopeusrajoitus – ja pidä ydin sisältö ensimmäisten 512 merkin sisällä. Älä kopioi ja liitä työkalujen kuvauksia tähän, äläkä yritä muuttaa mallin persoonallisuutta.

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

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

Yksi työkalu per toiminto

Luo yksi työkalu kutakin erillistä toimintoa varten: list_projects, get_project, update_project, äläkä yhtä yleistä työkalua, jossa on lukuisia tiloja. Jokainen työkalu yhdistää toimintoon viittaavan nimen, luettavan otsikon, kuvauksen siitä, milloin sitä käytetään, eksplisiittisen syöteskeeman, tulosteskeeman (jos se palauttaa jäsenneltyä dataa), tarkat annotaatiot ja käsittelijän, joka valtuuttaa pyynnön ennen toimintaa. Malli luottaa näihin metatietoihin päättäessään, kutsutaanko työkalua ja miten – kohtele sitä osana käyttäjäkokemusta.

import { z } from "zod";

const project = z.object({ id: z.string(), name: z.string(), status: z.enum(["active", "archived"]) });

server.registerTool(
  "get_project",
  {
    title: "View a project",
    description:
      "Use when the user wants details about a specific project in their Acme workspace. " +
      "Requires the ID returned by list_projects.",
    inputSchema: { id: z.string().min(1) },
    outputSchema: { project: project },
    annotations: { readOnlyHint: true, openWorldHint: false, destructiveHint: false },
  },
  async ({ id }, extra) => {
    const user = await authenticate(extra); // Your access control (Lesson 8)
    const found = await loadProject(user, id); // Your data access
    if (!found) {
      return {
        isError: true,
        content: [{ type: "text", text: `No project ${id} is accessible with this account.` }],
      };
    }
    return {
      structuredContent: { project: found },
      content: [{ type: "text", text: `Project "${found.name}" (${found.status}).` }],
    };
  }
);

authenticate ja loadProject ovat omia funktioitasi. Kriittinen kohta on niiden sijoittelu: valtuutus tapahtuu palvelimella jokaisen pyynnön yhteydessä. Älä koskaan luota malliin päättämään, onko käyttäjällä lupaa käyttää dataa.

Hyödyllisiä tuloksia ilman käyttöliittymää

Työkalun tulos voi sisältää kolme asiaa:

  • structuredContent: tiivistä dataa, jota malli voi tarkastella ja käyttää uudelleen myöhemmissä kutsuissa;
  • content: tekstiä tai muuta MCP-sisältöä, joka auttaa sitä vastaamaan;
  • _meta: dataa, joka on tarkoitettu asiakkaalle ja piilotettu mallilta.

Palauta tarpeeksi tietoa, jotta malli voi suorittaa tehtävän loppuun ilman visuaalista komponenttia, käyttämällä vakaita tunnisteita, joita myöhemmät työkalut voivat käyttää uudelleen. Kaksi SDK:n käyttäytymismallia on syytä huomata. Työkalun, joka määrittelee outputSchema, on palautettava vaatimusten mukainen structuredContent kaikissa onnistuneissa tuloksissa; muuten SDK heittää validointivirheen. Liiketoimintavirhe – kuten puuttuva projekti tai evätty toiminto – signaloidaan tuloksella, jossa on isError: true sekä selittävä teksti, jonka malli voi välittää käyttäjälle; tämäntyyppinen tulos ohittaa tulosteskeeman validoinnin.

Älä koskaan sisällytä salaisuuksia, pääsytunnuksia tai tarpeetonta henkilökohtaista dataa tulokseen, äläkä kohtele _meta:ta turvallisena piilopaikkana: tämä kenttä on piilotettu mallilta, mutta sitä ei ole suojattu.

Annotaatiot ja tiedustelu

Annotaatioiden on vastattava työkalun todellista käyttäytymistä: aseta readOnlyHint arvoksi true vain, jos se ei voi muuttaa mitään, destructiveHint arvoksi true, jos se voi aiheuttaa peruuttamattoman tai vaikeasti peruttavan vaikutuksen, ja openWorldHint arvoksi true, jos se koskettaa julkista internetiä tai avoimia ulkoisia entiteettejä. Ne auttavat ChatGPT:tä ja Codexia valitsemaan oikean vahvistuskäyttäytymisen; ne eivät korvaa valtuutusta, validointia tai vahvistuslogiikkaa palvelimellasi.

Kun palvelin tarvitsee jäsenneltyä tietoa, joka puuttuu kutsusta – kuten päivämäärän tai valinnan kahden vaihtoehdon välillä – se voi pyytää sitä tiedustelun (elicitation) kautta, joka on MCP-protokollan mekanismi. Rajoita tämä siihen, mitä käyttäjä kohtuudella voi antaa; älä koskaan käytä sitä salaisuuksien keräämiseen tai normaalin tunnistautumisen ohittamiseen.

Useat tilit ja yritystieto

Kaksi valinnaista yhteensopivuutta parantaa integraatiota. Auttaaksesi käyttäjiä, jotka yhdistävät useita tilejä, tarjoa profiilityökalu, joka on valtuutettu, vain luku -tilassa ja merkitty _meta["openai/profile"]: true. OpenAI käyttää tätä tunnistamaan yhdistetyt tilit ja auttamaan käyttäjiä erottamaan ne toisistaan. Profiili johdetaan pyynnön validoiduista tunnistetiedoista, ja jokainen kutsu rajoittuu näihin tunnistetietoihin.

ChatGPT:n company knowledge -ominaisuus voi käyttää palvelimesi vain luku -työkaluja. Tehdäksesi liitännästä kelvollisen lähteen, toteuta standardit syöteskeemat search- ja fetch-työkaluille, merkitse muut vain luku -työkalut arvolla readOnlyHint: true ja palauta absoluuttiset, käyttäjän avattavat URL-osoitteet lähteille, jotka mallin on mainittava.

Päätepisteen käyttöönotto

Julkinen julkaisu vaatii palvelimen vakaassa, julkisesti saavutettavassa HTTPS-osoitteessa. Tämän päätepisteen on tuettava streamable HTTP -kuljetusta, vastattava vakaassa URL-osoitteessa (tyypillisesti päättyen /mcp), täytettävä työnkulkujesi viive- ja saatavuusvaatimukset, ylettyvä palveluihisi ja dataasi, säilytettävä tunnistautumis- ja valtuutusrajat sekä tuotettava lokeja ja mittareita alustuksen ja työkalukutsujen epäonnistumisten varalta.

OpenAI:n Secure MCP Tunnel mahdollistaa yksityisen palvelimen yhdistämisen ChatGPT:hen, mutta se ei täytä julkisen julkaisun vaatimuksia, eikä väliaikainen tunneli tai paikallinen osoite tee niin. Jos palvelimen on pysyttävä yksityisenä, sijoita sen eteen julkinen HTTPS-välityspalvelin: OpenAI:n hallinnoima mTLS tunnistaa ChatGPT:n asiakkaana, OAuth 2.1 tunnistaa käyttäjäsi, ja IP-sallituslista – mukaan lukien OpenAI:n ChatGPT-liittimiä varten julkaisemat alueet, jotka päivittyvät automaattisesti – voidaan lisätä, mutta se ei koskaan korvaa tunnistautumista.

Ennen käyttöönottoa: injektoida tunnistetiedot isäntäsi salaisuuksien hallinnan kautta, määritä valtuutuspalvelin ja uudelleenohjaukset, aseta aikakatkaisut ja nopeusrajoitukset kalliille tai ulospäin näkyville työkaluille, poista virheenkorjausvastaukset ja tarpeeton henkilökohtainen data, ja varmista, etteivät lokit sisällä tunnuksia tai arkaluonteisia tuloksia. Käyttöönoton jälkeen toista MCP Inspector tuotanto-osoitteelle.

Kehittäminen rikkomatta toimivuutta

Pidä julkaistut työkalujen nimet ja skeemat taaksepäin yhteensopivina: lisää kenttiä tai työkaluja, mutta älä riko olemassa olevia sopimuksia. Jos metadata muuttuu, päivitä yhteys ja toista arviointipakettisi ennen julkaisua. Käyttöliittymää varten vaihda resurssitunniste, kun HTML, JavaScript tai CSS muuttuu tavalla, joka voisi rikkoa välimuistissa olevan komponentin.

Muistutukset turvallisuudesta

  • Kaikki työkalujen syöte on epäluotettavaa: valido se ja pakota valtuutus palvelimella
  • Vaadi vahvistus suurvaikutteisille kirjoituksille
  • Pidä salaisuudet ja arkaluonteinen data poissa metadatoista ja tuloksista
  • Lokita tarpeeksi tutkintaa varten, mutta sulje pois tunnistetiedot ja tarpeeton henkilökohtainen data
  • Aseta nopeusrajoituksia kalliille tai ulospäin näkyville toiminnoille

Keskeiset asiat

  • Nimetty, versioitu palvelin, jossa on lyhyet, poikkileikkaavat instructions
  • Yksi työkalu per toiminto, otsikko, aikomuksen kuvaus, skeemat, annotaatiot ja valtuutus käsittelijässä
  • structuredContent yhteensopiva tulosteskeeman kanssa, isError: true liiketoimintavirheille, ei salaisuuksia _meta:ssa
  • Julkaisu: vakaa, julkinen HTTPS streamable HTTP:n kautta; Secure MCP Tunnel ei riitä
  • Taaksepäin yhteensopivat sopimukset ja versioitut resurssitunnisteet