MCP-palvelimen rakentaminen: Vaiheittainen opas Pythonilla ja TypeScriptillä (2026)

Voit rakentaa MCP-palvelimen, jota Claude todella kutsuu, noin 15 minuutissa. Mittasimme sen Node 20:ssä ja Python 3.11:ssä: toimiva add-työkalu, joka pyörii stdio-yhteyden yli ja jonka Claude Desktop poimi, vei ensimmäisellä kerralla 14 minuuttia ja alle 5 minuuttia, kunhan tietää rakenteen. Tässä oppaassa rakennamme saman palvelimen kahdesti, kerran Pythonilla FastMCP 2.x:n avulla ja kerran TypeScriptillä @modelcontextprotocol/sdk 1.x:n avulla – jotta voit valita oman teknologiapinosi ja kopioida aitoa koodia. Jos haluat ensin arkkitehtuurin ja protokollateorian, Model Context Protocol -konseptiopas sisältää ne; tässä keskitymme vain rakentamiseen.

MCP-palvelimen pika-aloitus: Mitä olet rakentamassa

MCP-palvelin on pieni ohjelma, joka tarjoaa työkaluja, dataa ja kehysmalleja tekoälyasiakkaille, kuten Claudelle, Cursorille tai VS Codelle Model Context Protocol -protokollan kautta. Kirjoitat palvelimen kerran, ja mikä tahansa MCP-yhteensopiva asiakas voi kutsua sitä. Tässä oppaassa rakennat palvelimen, jossa on kaksi työkalua (add-laskin ja fetch_url-apuohjelma), ajat sen paikallisesti stdio-yhteyden yli, testaat sen ja yhdistät sen oikeaan asiakkaaseen.

Tässä on kaikki, mitä tarvitset ennen aloittamista.

Molemmat polut tuottavat palvelimen, joka käyttäytyy identtisesti. Valitse kieli, jota tiimisi jo käyttää. Jos sinulla ei ole preferenssiä, aloita Pythonilla, sillä FastMCP tekee ensimmäisestä palvelimesta lyhyemmän.

Mitä MCP-palvelin itse asiassa tarjoaa?

Ennen kuin kirjoitat koodia, on hyödyllistä tietää kolme asiaa, jotka palvelin voi tarjota. MCP-palvelin paljastaa työkalut (funktiot, joita malli voi kutsua, kuten "etsi tietokannasta"), resurssit (vain luku -data, jonka malli voi ladata, kuten tiedosto tai tietue) ja kehykset (uudelleenkäytettävät kehysmallit). Useimmat rakentamasi palvelimet ovat työkalukeskeisiä; resurssit ja kehykset ovat valinnaisia.

MCP-palvelin määriteltynä: prosessi, joka puhuu Model Context Protocolia ja mainostaa luetteloa työkaluista, resursseista ja kehyksistä, jotka tekoälyasiakas voi löytää ja kutsua ajon aikana.

Asiakas (esimerkiksi Claude Desktop) toimii isäntänä. Se käynnistää palvelimesi tai yhdistyy siihen, kysyy "mitkä työkalut sinulla on?" ja kutsuu niitä, kun malli päättää työkalun olevan hyödyllinen. Et koskaan kutsu mallia palvelimen sisäpuolelta. Virta kulkee toiseen suuntaan.

Tuo suunta on tärkeä. Palvelimesi on passiivinen tarjoaja. Se odottaa asiakkaan yhdistämistä, vastaa etsintäkutsuun ja suorittaa kutsutun työkalun. Pidä tämä mielikuva mielessä, ja loput tästä oppaasta loksahtavat paikalleen.

MCP-palvelimen rakentaminen Pythonilla (vaiheittain)

Python on nopein reitti toimivaan palvelimeen, koska FastMCP hoitaa protokollan putkistoinnin ja muuntaa tavalliset funktiot työkaluiksi dekoratorin avulla. Kaikki alla oleva käyttää virallista Python SDK:ta. Tässä ovat neljä vaihetta.

Vaihe 1: Projektin alustus. Käytä uv:tä, joka on nykyään standardi MCP Python -projekteille:

uv init mcp-demo
cd mcp-demo
uv add "mcp[cli]"

Jos suosikit pipiä: python -m venv .venv && source .venv/bin/activate && pip install "mcp[cli]".

Vaihe 2: Kirjoita palvelin. Luo server.py:

from mcp.server.fastmcp import FastMCP
import httpx

# Name shows up in the client's tool list
mcp = FastMCP("demo-server")

@mcp.tool()
def add(a: int, b: int) -> int:
    """Add two numbers and return the sum."""
    return a + b

@mcp.tool()
async def fetch_url(url: str) -> str:
    """Fetch a URL and return the first 2000 characters of the body."""
    async with httpx.AsyncClient(timeout=10) as client:
        resp = await client.get(url)
        return resp.text[:2000]

if __name__ == "__main__":
    mcp.run()  # defaults to stdio transport

Huomaa kaksi asiaa. Docstringistä tulee työkalun kuvaus, jonka malli lukee, joten kirjoita se ohjeena. Ja tyyppivihjeet (a: int) muodostavat syötteen skeeman automaattisesti, joten FastMCP generoi JSON-skeeman puolestasi.

Vaihe 3: Aja se. mcp.run() käynnistää palvelimen stdio-yhteydelle, jota asiakkaat käyttävät paikallisesti käynnistyksessä. Et aja tätä suoraan kehityksen aikana; asiakas käynnistää sen. Nopeaan savutestiin käytä dev-runneria:

uv run mcp dev server.py

Vaihe 4: Palauta siisti tuloste. Nyt kannattaa huomioida yksi sudenkuoppa: palauta merkkijono tai tyypitetty arvo, ei paljasta sisäkkäistä dictiä, jonka toivot renderöityvän. Palaamme tähän tuotanto-osiossa, mutta lyhyesti sanottuna epäselvät palautustyypit voivat katketa hiljaa joissakin asiakkaissa.

Siinä on valmis Python-MCP-palvelin. Kaksi työkalua, aidot verkkokutsut, automaattinen skeema. Seuraavaksi sama asia TypeScriptillä.

MCP-palvelimen rakentaminen TypeScriptillä (vaiheittain)

TypeScript-polku käyttää suoraan virallista TypeScript SDK:ta ja zod:ia syötteen validointiin. Se on hieman verbosempi kuin FastMCP, mutta tyypit ovat erinomaiset ja se deployautuu siististi Node-isäntiin.

Vaihe 1: Projektin alustus.

mkdir mcp-demo && cd mcp-demo
npm init -y
npm install @modelcontextprotocol/sdk zod
npm install -D typescript @types/node tsx

Vaihe 2: Kirjoita palvelin. Luo server.ts:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({ name: "demo-server", version: "1.0.0" });

server.tool(
  "add",
  "Add two numbers and return the sum.",
  { a: z.number(), b: z.number() },
  async ({ a, b }) => ({
    content: [{ type: "text", text: String(a + b) }],
  }),
);

server.tool(
  "fetch_url",
  "Fetch a URL and return the first 2000 characters.",
  { url: z.string().url() },
  async ({ url }) => {
    const resp = await fetch(url);
    const body = await resp.text();
    return { content: [{ type: "text", text: body.slice(0, 2000) }] };
  },
);

const transport = new StdioServerTransport();
await server.connect(transport);

Vaihe 3: Aja se. Kehityksen aikana: npx tsx server.ts. Tuotannossa käännä tsc:llä ja aja käännetty .js Nodella. Huomaa palautteen muoto: jokainen työkalu palauttaa { content: [{ type: "text", text: ... }] }. Tämä eksplisiittinen content-taulukko on TypeScript-vastine Pythonin "palauta siisti merkkijono" -säännölle. SDK haluaa tyypitettyjä sisältölohkoja, ei raakoja objekteja.

Vaihe 4: Validoi syötteet zodilla. z.string().url()-skeema hylkää virheellisen syötteen ennen käsittelijän ajoa, mikä on juuri sitä, mitä haluat, kun malli generoi argumentteja.

Samat kaksi työkalua, sama käyttäytyminen, idioomaattinen TypeScript. Päätetään nyt, kuinka asiakkaiden pitäisi tavoittaa palvelimesi.

stdio vs Streamable HTTP: Kumpi kuljetustapa kannattaa valita?

MCP-palvelimet kommunikoivat yhden kahdesta kuljetustavasta. stdio ajaa palvelimen paikallisena aliprosessina, jonka asiakas käynnistää ja jonka kanssa se kommunikoi standardin sisään- ja ulostulon kautta. Streamable HTTP ajaa palvelimen verkkopalveluna, johon asiakkaat yhdistyvät HTTP:n yli. Valinta riippuu siitä, missä palvelimen pitää sijaita.

Nyrkkisääntö: rakenna ja testaa stdiolla, vaihtaen Streamable HTTP:hen vasta, kun useampi kuin yksi henkilö tai kone tarvitsee palvelinta. Useimmat palvelimet eivät koskaan tarvitse poistua stdiosta. Yllä olevat mcp.run()- ja StdioServerTransport()-kutsut ovat jo stdioa, joten olet valmis kehitykseen.

MCP-palvelimen testaaminen Inspectorilla

Ennen kuin kytket palvelimesi Claudeen, testaa se eristettynä MCP Inspectorilla. Se on selainkäyttöliittymä, joka yhdistyy palvelimeesi, listaa sen työkalut ja antaa kutsua niitä manuaalisesti. Aja se palvelintasi vastaan:

# Python
npx @modelcontextprotocol/inspector uv run server.py
# TypeScript
npx @modelcontextprotocol/inspector npx tsx server.ts

Inspector avaa paikallisen sivun, jossa näet add- ja fetch_url-työkalusi, voit tehdä testikutsun ja lukea raakavastauksen. Tämä on paras tapa MCP-kehitykseen. Jos työkalun skeema on virheellinen tai palautearvo väärä, näet sen sekunneissa etkä tuijota hiljaista virhettä Clauen sisällä. Tällä tavalla löysimme virheellisen syöteskeeman, joka muuten olisi maksanut koko debuggauskierroksen asiakkaan kautta. Testaa aina ensin Inspectorilla.

MCP-palvelimen yhdistäminen Claude Desktopiin, Claude Codeen ja Cursoriin

Kun Inspector on tyytyväinen, osoita oikea asiakas palvelimeesi. Jokainen asiakas lukee konfigurointitiedoston, joka kertoo sille, kuinka palvelimesi käynnistetään stdio-yhteyden yli.

Claude Desktop. Muokkaa claude_desktop_config.json-tiedostoa (macOS:lla: ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "demo-server": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/mcp-demo", "run", "server.py"]
    }
  }
}

Käynnistä Claude Desktop uudelleen, ja työkalusi ilmestyvät liittimien kuvakkeen alle.

Claude Code. Lisää palvelin yhdellä komennolla projektistasi: claude mcp add demo-server -- uv run server.py. Claude Code tallentaa sen projektikonfiguraatioosi ja lataa sen käynnistyksessä. Jos käytät myös hookkeja Claude Coden skriptaukseen, Claude Code hooks -oppaamme sopii hyvin yhteen custom-MCP-työkalujen kanssa.

Cursor. Lisää sama mcpServers-lohko projektisi juurikansion .cursor/mcp.json-tiedostoon. Muoto vastaa Claude Desktopin muotoa. Esimerkki MCP-palvelimesta, joka ajetaan Clauen sisällä, löytyy artikkelista Higgsfield Clauen koodiin.

Käytä absoluuttisia polkuja kaikissa konfiguraatioissa. Suhteelliset polut ovat yleisin syy palvelimen käynnistymisvirheisiin.

MCP-palvelimen julkaiseminen tuotantoon (todennus ja hostaus)

Kun palvelimesi täytyy jakaa, siirrä se stdiosta Streamable HTTP:hen ja lisää kolme asiaa: todennus, virheenkäsittely ja isäntäympäristö.

• Todennus. Etä-MCP-palvelinten on käytettävä OAuth 2.1 MCP-valtuutusspesifikaation mukaisesti. Sisäisille työkaluille bearer-token-tarkistus HTTP-endpointissa on pragmatinen minimi. Älä koskaan julkaise julkista, todentamatonta työkalupalvelinta, koska SQL:ää suorittava tai sisäisiä API:eja osuva työkalu on live-hyökkäyspinta.
• Virheenkäsittely. Kiedo työkalujen rungot try/except- (tai try/catch) lohkoihin ja palauta tyypitetty virheviesti heittämisen sijaan. Malli käsittelee "kysely epäonnistui, tässä syy" paljon paremmin kuin katkennut yhteys.
• Hostaus. Mikä tahansa alusta, joka ajaa pitkäikäistä Node- tai Python-prosessia, käy: pieni VPS, Fly.io, Railway tai kontti omassa infrastruktuurissasi. Pidä prosessi lämpimänä, sillä kylmä käynnistys lisää viivettä ensimmäiseen työkalukutsuun.
• Konkurrenssi ja kustannukset. Jos työkalusi kutsuvat LLM:ää tai maksullista API:a downstreamissa, laita niiden eteen gateway. Katsauksemme LLM-gateway-työkaluista kattaa nopeusrajoituksen ja fallback-mekanismit, ja kontekstisuunnittelutyökalut auttavat pitämään työkalutulosteet kurissa, ettei mallin konteksti-ikkuna turhaan paisu.

Pythonissa vaihda ajokutsu muotoon mcp.run(transport="streamable-http"); TypeScriptissä vaihda StdioServerTransport SDK:n StreamableHTTPServerTransport-luokkaan. Työkalumääritykset eivät muutu lainkaan – siinä kuljetusabstraktion pointti.

Mitä opimme MCP-palvelinten julkaisemisesta tuotantoon

Olemme rakentaneet MCP-palvelimia Techsyn sisäiseen käyttöön, ja jotkut oppitunnit tulevat esiin vasta, kun todellinen liikenne osuu niihin. Tässä mitatut tulokset ja kohdat, joissa jouduimme pulaan.

Ensimmäinen julkaisemamme palvelin oli read-only Postgres-kyselytyökalu, rakennettu FastMCP 2.x:llä Pythonin mcp 1.x SDK:n päälle, myöhemmin uudelleenkirjoitettu @modelcontextprotocol/sdk 1.x:llä vertailua varten. Vuoden 2026 pinossa (Node 20, Python 3.11) paikalliset stdio-työkalukutsut lisäsivät noin 8–12 ms kuljetusylikuormaa per kutsu. Kun siirsimme saman palvelimen Streamable HTTP:hen VPS:llä, hinta per kutsu nousi 40–70 ms:ään, lähes kokonaan verkon round-tripin eikä protokollakustannusten vuoksi. FastMCP:n kylmäkäynnistys oli noin 300 ms prosessille, minkä vuoksi pidämme tuotantoprosessin lämpimänä.

Sudenkuoppa, joka maksoi meille noin kaksi tuntia: työkalu, joka palautti raakan Python-dictin, renderöityi hienosti Inspectorissa, mutta palautui typistettynä Claude Desktopissa. Palautearvon kietominen tyypitetyksi tekstimerkkijonoksi korjasi asian välittömästi. Siksi tämä opas palauttaa merkkijonoja ja content-tekstilohkoja kaikkialla sisäkkäisten objektien sijaan. Toinen tapa, joka tuotti heti tulosta, oli jokaisen palvelimen ajo npx @modelcontextprotocol/inspector-työkalulla ennen asiakaskonfiguraation koskemista, mikä paljasti virheellisen syöteskeeman TypeScript-uudelleenkirjoituksessa, joka muuten olisi epäonnistunut hiljaa Cursorissa.

Jos pohdit, millaisia työkaluja palvelimiin kannattaa ensisijaisesti rakentaa, listamme parhaista MCP-palvelimista vuonna 2026 on hyvä ideapankki.

Miten Techsy lähestyy MCP-kehitystä

Techsyssä rakennamme MCP-palvelimia osana asiakkaille toimitettavia tekoälyagenttijärjestelmiä, yhdistäen agentit sisäisiin tietokantoihin, CRM-järjestelmiin ja API:eihin tyypitetyn työkalukerroksen kautta. Lähestymistapamme on aloittaa kapeasti (yksi hyvin testattu työkalu stdion yli), validoida se Inspectorissa ja nostaa se todennetuksi HTTP-palveluksi vasta, kun useampi kuin yksi agentti tarvitsee sitä. Yhdistämme custom-palvelimet Claude Agent SDK:hon, kun agenttilogiikka monimutkaistuu.

Tämä on rehellinen versio: useimmat tiimit ylierittelevät ensimmäisen palvelimensa. Harvoin tarvitset HTTP:tä, OAuthia ja tusinaa työkalua ensimmäisenä päivänä. Jos haluat toiset silmät tarkastamaan MCP-integraatiota, varaa ilmainen konsultaatio, ja kerromme, onko kyseessä yhden työkalun stdio-homma vai jotain, joka todella vaatii infrastruktuuria.

Usein kysytyt kysymykset

Kannattaako MCP-palvelin rakentaa Pythonilla vai TypeScriptillä?

Käytä sitä, jota tiimisi jo käyttää. Python FastMCP:n kanssa on lyhyin reitti ensimmäiseen toimivaan palvelimeen, koska dekoratori muuntaa funktion työkaluksi. TypeScript virallisella SDK:lla on hieman verbosimpi, mutta tarjoaa erinomaiset tyypit ja deployautuu siististi Node-isäntiin. Molemmat tuottavat asiakkalle identtisesti käyttäytyviä palvelimia.

Tarvitsenko frameworkin kuten FastMCP:n MCP-palvelimen rakentamiseen?

Et, mutta se auttaa. FastMCP sisältyy viralliseen Python mcp SDK:hun ja poistaa suurimman osan protokollan boilerplate-koodista. Voit käyttää matalamman tason Server-API:a hienojakoiseen kontrolliin, mutta lähes jokaiseen palvelimeen FastMCP (Python) tai McpServer (TypeScript) on oikea työkalu ja vaatii huomattavasti vähemmän koodia.

Kuinka debuggaan MCP-palvelinta, joka ei toimi?

Aja se ensin MCP Inspectorin kautta: npx @modelcontextprotocol/inspector followed by your run command. Inspector listaa työkalusi ja antaa kutsua niitä suoraan, joten voit varmistaa palvelimen toiminnan ennen kuin syytät asiakasta. Jos Inspector on kunnossa mutta asiakas ei, tarkista, että konfiguraatiossi käytetään absoluuttisia polkuja ja että käynnistit asiakkaan uudelleen.

Onko FastMCP virallinen osa MCP:tä?

Kyllä. FastMCP on bundleattu virallisen Model Context Protocol Python SDK:n kanssa korkean tason palvelinrajapintana. @mcp.tool()-dekoratoria, jota käytät, suositellaan Python-palvelinten rakentamiseen, se ei ole kolmannen osapuolen lisäosa.

Mikä on ero paikallisen ja etä-MCP-palvelimen välillä?

Paikallinen palvelin ajaa koneellasi stdion yli, asiakkaan aliprosessina käynnistettynä, parhaiten henkilökohtaisiin työkaluihin ja kehitykseen. Etäpalvelin ajaa verkkopalveluna Streamable HTTP:n yli ja on saavutettavissa useille asiakkaille, mikä vaatii OAuth 2.1 -todennuksen. Rakenna ensin paikallisesti, mene etäyhteyteen vain jakamisen tarpeessa.

Millä kielillä voin rakentaa MCP-palvelimen?

Model Context Protocolilla on viralliset SDK:t Pythonille, TypeScriptille, Javalle, Kotlinille ja C#:lle, sekä yhteisön SDK:ita muilla kielillä. Koska MCP on wire-protokolla, mikä tahansa kieli, joka osaa lukea ja kirjoittaa JSON-RPC:tä stdion tai HTTP:n yli, voi implementoida palvelimen, mutta viralliset SDK:t säästävät sinut siltä työltä.

Toimiiako MCP-palvelin ChatGPT:n ja Geminin kanssa, vai vain Clauen?

MCP on avoin standardi, joka on omaksuttu laajasti agentic AI -ekosysteemissä, mukaan lukien ChatGPT, Gemini, Cursor ja VS Code Copilot. Yksi rakentamasi palvelin toimii minkä tahansa yhteensopivan asiakkaan kanssa. Et kirjoita erillistä integraatiota per malli, mikä on koko protokollan pointti.

Kuinka kauan kestää rakentaa toimiva MCP-palvelin?

Ensimmäinen palvelin yhdellä tai kahdella työkalulla stdion yli vie noin 15 minuuttia, kun ajonaikainen ympäristö on asennettu. Mittasimme 14 minuuttia ensikertalaiselle Node 20:ssä ja alle 5 minuuttia toistorakennukselle. Todennuksen, HTTP-kuljetuksen ja tuotantohostauksen lisääminen on se, mikä vie aikaa, ei palvelin itsessään.

Kirjoittajasta

Mert Batur Gurbuz on Techsy.io:n co-founder, jossa tiimi toimittaa tekoälyagentteja, automaatiojärjestelmiä ja voice/SDR-pipelineja B2B-asiakkaille. Hän opiskelee Birminghamin yliopistossa ja kirjoittaa LLM-työkalupinosta, jota Techsyn tiimi todella käyttää tuotannossa. Yhdistä LinkedInissä.

Mert Batur Gurbuz, Co-Founder, Techsy.io, Birminghamin yliopisto