Model Context Protocol (MCP) on Anthropicin loppuvuodesta 2024 julkaisema avoin protokolla, joka standardoi tavan tarjota Claudelle pääsy ulkoisiin työkaluihin ja dataan. Aiemmin jokainen integraatio piti rakentaa erikseen ja yhtä mallia varten — MCP:n myötä sama serveri toimii sekä Claude Codessa, Cursorissa että useissa muissa työkaluissa.
Tässä oppaassa rakennamme oman MCP-serverin alusta loppuun TypeScriptillä. Opas on suunniteltu kehittäjälle, jolla on perustiedot Node.js:stä, mutta ei aiempaa kokemusta MCP:stä. Esimerkki on yksinkertainen mutta tuotantokelpoinen pohja, jota voi laajentaa omiin tarpeisiin.
Mihin MCP-serveriä tarvitaan
Tyypillisimmät käyttötapaukset ovat yrityksen sisäisen datan tuominen mukaan AI-keskusteluun. Käytännössä tämä tarkoittaa esimerkiksi tietokantojen kyselyä, sisäisten API:en kutsuja tai toistuvien työnkulkujen paketoimista yhden komennon taakse.
| Käyttötapaus | Hyöty | Tyypillinen toteutusaika |
|---|---|---|
| Tietokantakyselyt | Claude voi hakea omat datat | 1–2 päivää |
| Sisäiset API-kutsut | REST-rajapintojen orkestrointi | 2–3 päivää |
| Komentopaketit | Toistuvat työnkulut yhdellä komennolla | 0,5 päivää |
| Yhteinen tool useassa AI:ssa | Sama serveri Claudelle ja Cursorille | Sisäänrakennettu |
| Audit-loki AI-käytöstä | Sääntelyn täyttäminen | 1 päivä |
Tarvittavat työkalut ja kirjastot
MCP-serverin rakentamiseen tarvitset Node.js 22:n tai uudemman, TypeScriptin sekä @modelcontextprotocol/sdk-paketin. Lisäksi Claude Code on hyvä asentaa testikäyttöön, vaikka serveri toimii myös ilman sitä.
Vaihe 1: projektin alustus
Luo uusi projektikansio, aja npm init -y ja asenna SDK komennolla npm install @modelcontextprotocol/sdk. Lisää tsconfig.json-tiedostoon target ES2022 ja moduuli NodeNext. Tämä antaa oikean konfiguraation modernille TypeScript-koodille.
Vaihe 2: ensimmäinen tool
Luo src/index.ts ja rekisteröi yksi työkalu, esimerkiksi hae_aurinkokoki, joka palauttaa Suomen auringon nousu- ja laskuajat. Käytä server.tool()-metodia, jossa määrittelet nimen, kuvauksen ja syöteskeeman Zodilla. Schemavalidointi on tärkeää — se estää Claudea kutsumasta toolia virheellisillä syötteillä.
Vaihe 3: kytke Claude Codeen
Lisää MCP-serveri Claude Coden konfiguraatioon settings.json-tiedostossa. Mukana on kaksi tasoa: globaali asetus (käytettävissä kaikissa projekteissa) ja projektikohtainen (versionhallinnassa). Tiimin yhteisille servereille suositellaan projektikohtaista, jotta uudet jäsenet saavat ne käyttöönsä automaattisesti.
Jos haluat ymmärtää MCP:n laajempaa kontekstia, lue lisää siitä miten Claude Code skillit toimivat oman MCP-serverisi rinnalla. Yhdistelmä antaa parhaan automaation: MCP tuo työkalut, skillit ohjaavat työnkulkua niiden ympärillä.
Vaihe 4: testaus
Käynnistä Claude Code uudelleen, jotta uusi konfiguraatio latautuu. Pyydä Claudea käyttämään uutta toolia: "Käytä hae_aurinkokoki-toolia ja kerro, mihin aikaan tänään aurinko nousee Helsingissä." Jos serveri vastaa odotetusti, integraatio toimii. Jos ei, virheviesti löytyy yleensä Claude Coden lokeista.
Vaihe 5: tuotantokäyttö
Paketoi serveri Docker-konttiin tai julkaise se npm:ssä yrityksen sisäiseen rekisteriin. Suosittelemme ottamaan käyttöön myös autentikoinnin ja rate limitingin ennen tuotantokäyttöä. Claude Opus 4.7:n Computer Use 2.0 hyödyntää MCP-protokollaa sisäisesti, joten sama serveri toimii nyt sekä Claude Codessa että agentti-ympäristössä. Tämä on iso etu, sillä se mahdollistaa työkalujen jakamisen kehitysympäristön ja tuotantoagentin välillä.
Yleisimmät virheet
Listamme yleisimmät virheet, joihin kehittäjät ovat törmänneet kymmenissä asennuksissa, joita olemme avustaneet.
Unohdettu npx tsc -käännös ennen ajoa, jolloin lähdetään ajamaan vanhaa versiota
Väärä polku settings.json-tiedostossa, erityisesti Windowsissa backslash-erottimet
Liian löyhä Zod-skeema, joka päästää virheelliset syötteet läpi ja saa toolin kaatumaan
Liian tiukka skeema, joka estää Claudea käyttämästä toolia oikein, vaikka semantiikka olisi kunnossa
Unohdettu rate limiting, joka voi johtaa kustannusten räjähdykseen jos malli kutsuu toolia silmukassa
Jos rakennat suurempia AI-järjestelmiä, kannattaa lukea myös RAG-järjestelmän rakentamisen opas pgvectorilla ja Claudella. Kun olet asentanut MCP-serverisi, viritä Claude Code -asetuksesi: 12 asetusta jotka teen aina ensimmäisenä parantavat työnkulun merkittävästi ja vähentävät keskeytysten määrää.
Mistä jatkaa
Kun perusrakenne on pystyssä, luonnolliset seuraavat askeleet ovat: useamman toolin lisääminen samaan serveriin, autentikoinnin viilaaminen (API-avaimet tai OAuth) ja serverin julkaisu joko yrityksen sisäiseen rekisteriin tai julkiseen npm:ään. Avoimen lähdekoodin MCP-servereitä on jo kymmeniä eri kategorioissa, joista voi ottaa inspiraatiota.
MCP on yksi viime vuosien tärkeimmistä standardiloikista AI-puolella. Se mahdollistaa työkalujen jakamisen mallin ja työkalun välillä — sama tool toimii Claudessa, ChatGPT:ssä ja itse hostatuissa malleissa. Yhdellä standardilla saatiin tehtyä se, mitä on yritetty erikseen viisi vuotta.
