Read in English

mcp-bridge-template: aja omaa MCP-palvelinta pienen palvelun vieressä. Docker Compose, tokenit, terveystarkistukset.

Käytän Claude Coden ja Codexin kanssa omia MCP-palvelimia. Niiden kautta tekoälyasiakkaat kutsuvat työkaluja palvelimilla, joita hallitsen itse.

Minulta on kysytty, miten asetelma toimii. Koodia en voinut jakaa sellaisenaan, koska se on sidottu omiin palveluihini, koneisiini ja tietoihini.

Kirjoitin siksi mallipohjan alusta, eikä siinä ole mitään omasta asetelmastani: github.com/ollijunes/mcp-bridge-template.

Ongelma

Model Context Protocolille on hyviä esimerkkejä, mutta useimmissa palvelin on paikallinen prosessi, jonka asiakas käynnistää. Kannettavalla se riittää. Kotipalvelimella tai pienellä VPS:llä, jota useampi asiakas käyttää, palvelinta ei ajeta niin.

Kun palvelin pyörii palveluna, tarvitaan vastauksia tylsiin kysymyksiin. Kuka saa kutsua sitä? Missä token on? Mitä tapahtuu, kun taustapalvelu kaatuu? Mistä tiedät, että palvelin voi hyvin? Onko jotain vahingossa auki internetiin?

Mitä pohja tekee

Docker Composessa on kaksi konttia.

  • collect on pieni muistiinpanorajapinta, joka on kirjoitettu pelkällä Pythonin vakiokirjastolla. Se on esimerkki omasta palvelustasi.
  • bridge on MCP-palvelin virallisella MCP:n Python-kirjastolla. Se tekee collectin rajapinnasta kolme työkalua: lisää muistiinpano, listaa muistiinpanot ja tarkista tila.

Vaihdat collectin omaan palveluusi ja kirjoitat sille työkalut. Tokenit, terveystarkistukset, konttien asetukset ja testit jäävät.

Claude Code, Codex CLI ja MCP Inspector yhdistävät siltaan yhdellä komennolla, ja README näyttää jokaisen.

Miten se pysyy kiinni

  • Kaksi tokenia: yksi MCP-asiakkaille ja toinen sillan ja collectin välille. Ensimmäisen tunteva asiakas ei pääse collectiin suoraan.
  • Tokenit tulevat .env-tiedostosta, joka ei päädy Gitiin eikä konttikuvaan. Palvelut eivät käynnisty ilman niitä.
  • Collectilla ei ole julkaistua porttia lainkaan. Silta kuuntelee vain paikallista osoitetta.
  • Kontit ajetaan tavallisena käyttäjänä, tiedostojärjestelmä on vain luku -tilassa eikä niillä ole ylimääräisiä Linux-oikeuksia.
  • Collect vastaa virheisiin kiinteillä viesteillä, eikä silta välitä taustapalvelun virhetietoja asiakkaalle.

Mitä olen testannut

Molemmilla palveluilla on automaattiset testit, myös MCP-asiakas, joka puhuu sillalle HTTP:n yli. CI rakentaa lisäksi konttikuvat, käynnistää ne Composella ja ajaa savukokeen: terveystarkistus, hylätty pyyntö ilman tokenia ja oikeat työkalukutsut tokenin kanssa.

Mitä pohja ei tee

TLS:ää ei ole. Jos haluat yhdistää siltaan toiselta koneelta, laita eteen käänteinen välityspalvelin TLS:llä tai käytä yksityistä verkkoa. Käyttäjätilejä tai pyyntörajoja ei myöskään ole. Yksi token tarkoittaa yhtä ihmistä ja hänen omia asiakkaitaan.

Kokeile

Koodi on osoitteessa github.com/ollijunes/mcp-bridge-template. Kopioi .env.example, luo kaksi tokenia ja aja docker compose up.

Issuet ja pull requestit ovat tervetulleita. Älä liitä niihin oikeaa tokenia, konenimeä tai lokia omasta asennuksestasi.