Työkalut, resurssit ja kehotteet MCP:ssä
Tällä sivulla
Päivitetty 2. marraskuuta 2026 — MCP Python SDK v2. Tämä kurssi noudattaa nyt
mcp-SDK:n versiota 2 (2.3.0 tilanteen mukaan 2. lokakuuta 2026):MCPServerkorvaaFastMCP:n, kuljetusasetukset siirtyvät metodiinrun()taistreamable_http_app(), ja todellisen isäntänimen alla julkaistun sovelluksen on ilmoitettava kyseinen isäntänimi (transport_security). Tämä on myös Mistral SDK:n vaatima versio:mistralai[agents]-lisäosa vaatii ehdottomastimcp>=2.2.0,<3.0. Lähteet: Mitä uutta versiossa v2 · Migraatio-opas · Käyttöönotto ja skaalaus.
Kolme kykyä, kolme tarkoitusta
MCP-palvelin voi tarjota asiakkailleen kolmen tyyppisiä kykyjä. Ne eivät ole keskenään vaihdettavissa: kukin vastaa erityiseen tarpeeseen, ja niiden sekoittaminen johtaa palvelimiin, joita mallin on vaikea käyttää. Tässä oppitunnissa tarkastelemme niitä yksi kerrallaan ennen kuin pureudumme palvelimen laatua määrittävään kysymykseen: kuinka monta työkalua ja millä tarkkuustasolla?
Työkalut: suoritettavat funktiot
Työkalut ovat protokollan käytetyin kyky. Työkalu on funktio, jonka malli voi päättää kutsua suorittaakseen toiminnon tai hakeakseen tietoa. Sen määritelmä perustuu neljään elementtiin: yksilöllinen ja kuvaava nimi (create_issue, get_weather), tekstikuvaus, joka kertoo mallille milloin työkalua tulee kutsua, syöteparametrien JSON-schema tyyppeineen ja rajoituksineen sekä palautusmuoto – useimmiten teksti tai JSON.
from mcp.server.mcpserver import MCPServer
app = MCPServer("My Server")
@app.tool()
def get_weather(latitude: float, longitude: float) -> str:
"""Retrieves current weather for the given coordinates.
Args:
latitude: Latitude in decimal degrees (-90 to 90)
longitude: Longitude in decimal degrees (-180 to 180)
Returns:
Text description of current weather
"""
# Weather API call logic
return f"Sunny, 22°C at ({latitude}, {longitude})"
Älä aliarvioi kuvausta ja tyyppimäärityksiä: malli ei näe mitään muuta. Sillä ei ole pääsyä koodiisi, se ei voi arvata aikomuksiasi eikä se voi testata kutsua nähdäkseen mitä tapahtuu. Epämääräiset kuvaukset tai huonosti tyypitetyt parametrit tuottavat mekaanisesti virheellisiä kutsuja.
Muutama tapa tekee työkaluistasi huomattavasti luotettavampia. Nimeä ne sen perusteella, mitä ne tekevät – book_restaurant kertoo kaiken, process_request ei kerro mitään – ja kuvaile sekä toiminto että palautettava sisältö, sillä mallin on ennakoitava mitä se saa. Annotoi aina parametrit Pythonissa ja kirjoita jäsennellyt docstringit kohdilla Args ja Returns: nämä syöttävät mallin näkemän skeeman. Lopuksi, palauta luettavia arvoja äläkä läpinäkymättömiä tunnisteita; työkalu, joka palauttaa "John Smith", antaa mallin muodostaa lauseen, kun taas UUID:n palauttava työkalu pakottaa sen arvailemaan.
Resurssit: luettava data
Resurssit tarjoavat dataa, jota asiakas voi lukea ilman sivuvaikutuksia. Ero työkaluihin tiivistyy yhteen verbiin: työkalu tekee jotakin, resurssi sisältää jotakin. Konfiguraatiotiedoston sisältö, tietokanta, API-dokumentaatio tai järjestelmän nykytila ovat kaikki luontaisia resursseja.
@app.resource("config://database")
def get_db_config() -> str:
"""Current database configuration."""
return json.dumps({
"host": "localhost",
"port": 5432,
"database": "production"
})
Jokainen resurssi tunnistetaan URI:lla – config://database, file:///path/to/doc – jonka asiakas voi luetella ja lukea tarvittaessa. Käytännössä niitä käytetään harvemmin kuin työkaluja, sillä yksinkertainen dataa palauttava työkalu kattaa useimmat tarpeet. Ne ovat kuitenkin hyödyllisiä, kun haluat julkaista staattista tai puolistaattista dataa ilman taustalla olevaa suorituslogiikkaa.
Kehotteet: uudelleenkäytettävät mallipohjat
MCP-kehotteet (Prompts) ovat parametroitavia mallipohjia, jotka palvelin asettaa saataville. Niiden tarkoitus on jakaa todennetuiksi havaittuja ohjeistuksia tiettyä tehtävää varten sen sijaan, että jokainen keksisi omat sanamuotonsa alusta alkaen.
@app.prompt()
def code_review(language: str, code: str) -> str:
"""Generates a code review prompt for the given language."""
return f"""You are an expert in {language}.
Analyze the following code and identify:
1. Potential bugs
2. Performance issues
3. Readability improvements
Code to analyze:
```{language}
{code}
```"""
Tämä käyttötapa on järkevintä tiimiympäristössä. Kokenut kehittäjä koodaa koodinkatselmointi-, vianetsintä- tai arkkitehtuurianalyysikehotteensa MCP-palvelimeen, ja koko tiimi pääsee niihin käsiksi omista asiakassovelluksistaan samalla ohjeistuksen laadulla.
Kykyjen neuvottelu
Kun asiakas yhdistää palvelimeen, käyttöä edeltää neuvotteluvaihe:
- Asiakas pyytää palvelimen kykyjä
- Palvelin vastaa luettelolla työkaluistaan, resursseistaan ja kehotteistaan
- Asiakas esittelee nämä kykyt kielimallille
- Malli käyttää kuvauksia päättääkseen mitä kutsua
Tämä neuvottelu on dynaamista, ja se on hyödynnettävissä oleva ominaisuus: sama palvelin voi ilmoittaa erilaisia kykyjä riippuen yhdistävästä käyttäjästä tai kutsukontekstista – esimerkiksi järjestelmänvalvojan tili näkee työkaluja, joita vain luku-oikeuksilla varustettu tili ei koskaan näe.
Kuinka monta työkalua palvelinta kohden?
Kysymys vaikuttaa triviaalilta, mutta se määrittää agenttisi virheprosentin. Pidä palvelimesi keskittyneinä: kolmesta kymmeneen hyvin määriteltyä työkalua toimii paremmin kuin viisikymmentä yleistä työkalua. Tietyn määrän ylittyessä malli hajauttaa valintansa ja päätyy kutsumaan väärää työkalua tai kasauttamaan tarpeettomia kutsuja.
Jos toiminnallinen laajuutesi on leveä, jaa se useampaan erikoistuneeseen palvelimeen – yksi Git-toiminnoille, yksi projektinhallinnalle, yksi valvonnalle. Asiakas osaa yhdistää useaan palvelimeen samanaikaisesti ja aktivoida vain ne, joita nykyinen tehtävä vaatii. Tämä vastaa hyödyllisen kontekstin lataamista eikä koko luettelon lataamista.
Yksi viimeinen kompromissi ansaitsee huomiosi: tarkkuustaso (granulaarisuus). Kolmen työkalun tarjoaminen ravintoloiden listaamiseen, vapaiden aikojen tarkistamiseen ja varaamiseen pakottaa mallin orkestroimaan sekvenssin, jolloin virheriski kasvaa jokaisessa vaiheessa. Yksi työnkulun työkalu – book_restaurant – kapseloi koko sekvenssin, vähentää edestakaisten viestien määrää ja siirtää liiketoimintalogiikan sinne, missä se on testattavissa: koodiisi.
Keskeiset asiat
- Työkalut = suoritettavat toiminnot (90 % käyttötapauksista), vaativat tarkan kuvauksen ja tyypityksen
- Resurssit = URI:n kautta luettava data, ei sivuvaikutuksia
- Kehotteet = uudelleenkäytettävät mallipohjat, hyödyllisiä tiimeille
- Pidä palvelimesi keskittyneinä (enintään 3–10 työkalua)
- Suosi työnkulun työkaluja liian hienojakoisten työkalujen sijaan
- Kuvauksen laatu määrittää mallin tehokkuuden