Jinsi ya kuendesha MCP servers kwenye VPS kwa AI agents

Unachojenga

Usanidi mbili za MCP zinazofanya kazi kwenye VPS moja. Ya kwanza ni seva ya stdio, zana ya mfumo wa faili au database ambayo Claude Code huianzisha kama mchakato msaidizi (child process) na kuwasiliana nayo kupitia pipe. Ya pili ni seva ya remote HTTP inayofanya kazi kama huduma ya mtandao ya muda mrefu nyuma ya systemd na nginx reverse proxy yenye TLS, inayoweza kufikiwa na mteja yeyote wa MCP utakayemwelekeza huko. Ufungaji wa yoyote kati ya hizi ni mdogo. Sehemu kubwa ya mwongozo huu inahusu mambo mawili yanayoweza kuleta changamoto: kuweka mtiririko wa JSON-RPC ukiwa safi, na kutoweka kamwe endpoint ya zana isiyo na uthibitisho kwenye mtandao wa umma.

MCP ni nini hasa

Model Context Protocol ni njia sanifu inayotumiwa na mteja wa AI, kama vile Claude Code, Claude Desktop, Gemini CLI kwenye VPS, au hati yako mwenyewe, ili kuita zana za nje na kusoma rasilimali za nje. Model yenyewe haiendeshi kitu chochote. Inamuuliza mteja, mteja anawasiliana kwa JSON-RPC 2.0 na server ya MCP, server hiyo inaendesha zana na kurudisha matokeo. Mteja huyo ndiye sehemu ambayo watu huirejelea wanaposema agent harness: kitanzi kinachozunguka model ambacho kinamiliki orodha ya zana, ukaguzi wa ruhusa, na hali ya session, na MCP ndiyo njia rahisi ya kupanua sehemu ya zana. Itifaki moja, kwa hivyo server unayoandika mara moja inafanya kazi na kila mteja anayezungumza MCP. Ikiwa mgawanyo huo ni mpya kwako, na hasa swali la jinsi model inavyoamua kutumia zana, njia ya hatua kwa hatua kupitia misingi ya wakala inafaa kutumia saa moja kabla ya kuipa server yoyote kati ya hizi vitambulisho halisi.

Kuna njia mbili za usafirishaji (transports), na sehemu iliyobaki ya mwongozo huu imegawanywa kulingana nazo:

• stdio. Mteja anazindua server kama mchakato msaidizi (child process) na kubadilishana ujumbe wa JSON-RPC uliotenganishwa na mstari mpya kupitia standard input na standard output yake. Hakuna mtandao, hakuna port, hakuna uthibitishaji, mpaka wa uaminifu ni mchakato wenyewe. Karibu kila zana ya ndani hutumia njia hii.
• Streamable HTTP (pamoja na toleo lake la zamani, HTTP+SSE). Server ni huduma ya wavuti inayofanya kazi kwa muda mrefu. Mteja huunganisha kupitia HTTP na server inaweza kutiririsha majibu kama Server-Sent Events. Hivi ndivyo unavyoshiriki server moja na wateja wengi, au kuendesha zana inayopaswa kuwepo kwenye mashine hiyo kudumu.

Chagua stdio wakati zana ni ya mashine moja na mtumiaji mmoja. Chagua HTTP wakati ni huduma iliyoshirikiwa.

Mahitaji ya awali na changamoto za kweli

Dhani una VPS ya Ubuntu 24.04 KVM mpya yenye ufikiaji wa root au sudo. Zaidi ya hayo:

• Runtime ambayo seva imeandikwa kwayo. Seva nyingi za marejeo ni za Node au Python. Ubuntu 24.04 inakuja na Node 18, na vifurushi vingi vya sasa vya MCP vinahitaji Node 20 au mpya zaidi, kwa hivyo sakinisha toleo la sasa la LTS kutoka NodeSource au nvm badala ya kutegemea apt. Python 3.12 tayari ipo.
• Domain na DNS A record, lakini kwa seva ya HTTP ya mbali pekee; TLS inahitaji jina linaloelekeza kwenye VPS hii. Mfano wa stdio hauhitaji DNS yoyote.
• 512 MB RAM inatosha. Seva za MCP ni michakato midogo ya JSON-RPC; gharama ya kumbukumbu inategemea kile ambacho zana yako inakigusa (dereva wa database, cache ya faili), si itifaki yenyewe.
• Uainishaji (spec) ni mpya na unabadilika. Marekebisho ya 2025-03-26 yalichukua nafasi ya HTTP+SSE na kuweka Streamable HTTP, huku yakitangaza kuwa SSE imepitwa na wakati. SSE bado inafanya kazi na seva nyingi bado zinaitumia, kwa hivyo chukulia kila chaguo la usafirishaji (transport) kama kitu cha kukihakiki upya dhidi ya maelezo ya toleo la seva badala ya kukichukulia kama ukweli usiopingika.

Hatua ya 1: unganisha stdio server kwenye Claude Code

Anza na filesystem server; ni rasmi, inatunzwa kikamilifu, na inahitaji Node pekee. Amri moja hapa chini inaisajili na Claude Code na kuifungia kwenye mradi wa sasa ili ihifadhiwe kwenye faili inayoweza kufanyiwa commit:

cd /home/matt/projects/api
claude mcp add --scope project --transport stdio filesystem \
  -- npx -y @modelcontextprotocol/server-filesystem /home/matt/projects/api

Kitenganishi -- ni muhimu: kila kitu baada yake ni amri ambayo Claude Code itaiendesha, si flag ya Claude Code. Hii inaandika .mcp.json kwenye mzizi wa mradi:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/home/matt/projects/api"
      ]
    }
  }
}

Hakuna kinachoendelea bado. Unapoanzisha Claude Code kwenye saraka hii, wakala husoma .mcp.json, huzaa npx -y @modelcontextprotocol/server-filesystem ... kama mchakato msaidizi (child process), na kufanya MCP handshake kupitia stdin/stdout ya mchakato huo. Thibitisha kuwa imekubali:

claude mcp list

Server iliyo sawa huchapisha amri yake na alama ya kijani, filesystem: npx -y @modelcontextprotocol/server-filesystem ... - ✓ Connected. Ndani ya kikao, amri ya slash ya /mcp huorodhesha zana ambazo server inatoa (read_file, write_file, list_directory), na wakala sasa anaweza kuzitumia kwenye njia ulizoruhusu. Zana ya database ina muundo uleule; badilisha kifurushi na uweke connection string kama hoja ya mwisho, lakini kagua hazina (repository) ya server hiyo kwa jina la sasa la kifurushi, kwa sababu server ya marejeo ya Postgres imebadilisha wamiliki mara kadhaa.

Hii ndiyo maana nzima ya kuendesha wakala kwenye mashine: kikao cha Claude Code huishi kwenye VPS ndani ya tmux, na stdio servers zake huendeshwa kando yake zikiwa na ufikiaji wa moja kwa moja kwenye faili za mradi na huduma za ndani, bila hitaji la network round-trip. Wakala anapokuwa na write_file pamoja na read_file, ni vyema kuoanisha uwezo huo na ujuzi unaomwelekeza kwenye mabadiliko madogo zaidi yanayofanya kazi, kwa sababu zana ya filesystem hufanya uandishi upya mkubwa kuwa rahisi kama marekebisho ya mistari miwili. Wiring hiyo hiyo inaenea zaidi ya faili za ndani: ikiwa tayari unaendesha search engine kwenye VPS, unaweza kumpa wakala instance yako ya SearXNG kama zana ya utafutaji, jambo linaloweka queries kwenye mashine yako lakini likivuta maandishi ya kurasa zisizoaminika moja kwa moja kwenye muktadha ambao wakala anautumia.

Hatua ya 2: jenga seva ya HTTP ya mbali

Seva ya stdio hufa pamoja na mzazi wake, na huzinduliwa mara moja kwa kila mteja, kwa hivyo ukiendesha vipindi viwili vya Claude Code kwenye mashine inayopitishiana kazi, kila kimoja hupata nakala yake binafsi ya zana hiyo. Unapotaka zana inayobaki ikiwa imewashwa kwa kila mteja, zana ya pamoja ya ops, gateway ya database, kitu ambacho laptop yako na CI yako zote zinakiita, unahitaji usafirishaji wa HTTP na huduma halisi. Hii hapa ni seva ndogo ya Python inayotumia SDK rasmi, ikionyesha zana moja:

# /opt/mcp-ops/server.py
from mcp.server.fastmcp import FastMCP
import subprocess

mcp = FastMCP("ops-tools", host="127.0.0.1", port=8000)

@mcp.tool()
def disk_free() -> str:
    """Return `df -h` for the server."""
    out = subprocess.run(["df", "-h"], capture_output=True, text=True)
    return out.stdout

if __name__ == "__main__":
    # Serves Streamable HTTP at /mcp on 127.0.0.1:8000
    mcp.run(transport="streamable-http")

Zingatia host="127.0.0.1". Seva inajifunga kwenye localhost pekee, hakuna kitu nje ya mashine kinachoweza kuifikia moja kwa moja, jambo ambalo ndilo unalotaka kabla ya uthibitishaji (auth) kuwepo. Iweke kwenye virtualenv yake ili systemd iwe na njia thabiti ya interpreter:

sudo useradd --system --home /opt/mcp-ops --shell /usr/sbin/nologin mcp
sudo install -d -o mcp -g mcp /opt/mcp-ops
sudo -H -u mcp python3 -m venv /opt/mcp-ops/.venv
sudo -H -u mcp /opt/mcp-ops/.venv/bin/pip install "mcp[cli]"

Hatua ya 3: iweke hai kwa kutumia systemd

Zana ambayo haifanyi kazi wakati wakala anapoiitaji ni mbaya zaidi kuliko kutokuwa na zana hiyo kabisa. Hili ni muhimu zaidi wakati mteja mwenyewe ni mchakato wa muda mrefu: wakala anayewaka kila wakati anayehifadhi kumbukumbu na ratiba zake baada ya kuwasha upya seva ataita zana hizi kwa ratiba bila mtu yeyote anayezitazama, kwa hivyo seva lazima ijiwashe yenyewe pia. Andika /etc/systemd/system/mcp-ops.service:

[Unit]
Description=MCP ops-tools server
After=network.target

[Service]
Type=simple
User=mcp
WorkingDirectory=/opt/mcp-ops
ExecStart=/opt/mcp-ops/.venv/bin/python /opt/mcp-ops/server.py
Restart=on-failure
RestartSec=2
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=true

[Install]
WantedBy=multi-user.target

Njia kamili (absolute path) ya venv Python katika ExecStart si ya hiari, ielekeze kwenye /usr/bin/python3 na mchakato utaanza na ModuleNotFoundError: No module named 'mcp', kwa sababu mkalimani wa mfumo (system interpreter) hakuwahi kuona pip install yako. Iwezeshe na uikague:

sudo systemctl daemon-reload
sudo systemctl enable --now mcp-ops
sudo systemctl status mcp-ops
curl -si -H 'Accept: application/json, text/event-stream' \
  -H 'Content-Type: application/json' \
  -X POST http://127.0.0.1:8000/mcp

status inapaswa kusomeka active (running). curl inarudi HTTP/1.1 400 Bad Request ikiwa na hitilafu ya JSON-RPC kwenye mwili wa ujumbe, ombi halikuwa na kikao (session) wala payload halali ya JSON, na hilo ndilo hasa unalotaka: linathibitisha kuwa port inajibu na inazungumza itifaki hiyo. Connection refused au jibu tupu inamaanisha mchakato haujafungwa mahali unapofikiri; soma journalctl -u mcp-ops -n 50.

Hatua ya 4: weka TLS na reverse proxy mbele

Seva inasikiliza kwenye localhost. Ili kuifikia kutoka popote, unapaswa kumalizia TLS kwenye nginx na kufanya proxy kuelekea ndani. Sakinisha nginx, pata cheti kupitia Certbot na Let's Encrypt kwenye nginx, kisha andika block ya location. Sehemu muhimu ni kuzima buffering, kwa sababu tabia ya kawaida ya nginx ni kushikilia majibu hadi yakamilike, jambo ambalo husimamisha mtiririko wa SSE milele:

server {
    listen 443 ssl;
    server_name mcp.example.com;

    # ssl_certificate lines managed by Certbot

    location /mcp {
        proxy_pass http://127.0.0.1:8000;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        proxy_set_header Host $host;

        # The four lines that make SSE work through nginx:
        proxy_buffering off;
        proxy_cache off;
        proxy_read_timeout 3600s;
        chunked_transfer_encoding off;
    }
}

Pakia upya kwa kutumia sudo nginx -t && sudo systemctl reload nginx. Ikiwa tayari unaendesha kundi la containers, kazi hiyo hiyo inafanywa kwa ajili yako na Traefik reverse proxy yenye TLS ya kiotomatiki, inatoa cheti na kuelekeza trafiki kulingana na hostname, na wewe unaongeza tu labels kwenye container ya MCP. Vyovyote vile, reverse proxy sasa ndiyo kitu pekee kilicho kwenye port ya umma, na inaelekeza kwenye huduma ambayo bado hujailinda. Rekebisha hilo kabla ya kusajili URL popote.

Hatua ya 5: kanuni ya usalama inayotawala mada hii

Usiwahi kuweka wazi MCP endpoint isiyo na uthibitisho. Seva ya MCP si API ya kusoma pekee. Inatoa uwezo wa kufikia zana, faili zako, database yako, na wakati mwingine shell. /mcp iliyo wazi kwenye mtandao wa umma ni mgeni mwenye uwezo sawa na AI agent wako: wanaweza kuorodhesha zana zako, kisha kuzitumia. Ichukulie kama socket ya admin isiyo na uthibitisho, kwa sababu ndivyo ilivyo. Kiasi ambacho token iliyoibiwa inaweza kukugharimu kinategemea seva iliyo nyuma yake: seva ya MCP ya kusoma pekee inayokuja na openGym workout tracker inaweza tu kutoa data ya mazoezi, wakati zana ya filesystem au shell inatoa uwezo wa kudhibiti seva nzima.

Kinga tatu, kwa mpangilio wa ubora:

1. Usiichapishe. Iweke seva kwenye 127.0.0.1 na uifikie kutoka kwenye laptop yako kwa kutumia SSH tunnel: ssh -L 8000:127.0.0.1:8000 matt@vps, kisha uelekeze client kwenye http://127.0.0.1:8000/mcp. Hakuna kitu kitakachokuwa wazi.
2. Iweke kwenye mtandao wa ndani (private network). Bind anwani ya tunnel ya WireGuard VPN inayojiendesha na uwaruhusu tu watumiaji wa VPN kuifikia. Mtandao wa umma utaona port iliyofungwa.
3. Ikiwa lazima iwe ya umma, hitaji token. Jibu sahihi ni MCP OAuth flow ambayo HTTP transport inaiunga mkono kiasili. Kiwango cha chini cha kiutendaji ni shared bearer token inayokaguliwa kwenye proxy; ni rahisi, na inazuia mashambulizi ya moja kwa moja kabisa:

location /mcp {
    if ($http_authorization != "Bearer REPLACE_WITH_LONG_RANDOM") {
        return 401;
    }
    proxy_pass http://127.0.0.1:8000;
    # ...buffering-off block from above...
}

Tengeneza token kwa kutumia openssl rand -hex 32, na usiwahi ku-bind seva yenyewe kwenye 0.0.0.0 bila mojawapo ya kinga hizi mbele yake. Client kisha hutuma token kama header. Katika Claude Code:

claude mcp add --scope project --transport http ops-tools https://mcp.example.com/mcp \
  --header 'Authorization: Bearer ${MCP_TOKEN}'

Weka MCP_TOKEN kwenye shell yako ili siri hiyo isiwahi kuingia kwenye .mcp.json kwa maandishi ya kawaida (plaintext), Claude Code hupanua ${MCP_TOKEN} kutoka kwenye mazingira (environment) wakati wa kusoma.

Kila kinga hapo juu hulinda endpoint badala ya agent ambaye tayari anashikilia token, ambayo ndiyo nusu nyingine ya tatizo: ikiwa client yako ni DeepSeek Harness, plugins zinazodhibiti ni zana zipi agent anaweza kutumia na kuchanganua matokeo ya zana kwa maelekezo yaliyodungwa hufunika upande huo.

Hatua ya 6: fanya debugging kwa kutumia MCP Inspector

Seva inapofanya kazi vibaya, usikisie kutoka ndani ya agent, iendeshe moja kwa moja kwa kutumia Inspector, mteja rasmi wa majaribio wa mtandaoni. Kwa seva ya stdio, ipe amri ile ile ambayo agent huiendesha:

npx @modelcontextprotocol/inspector \
  npx -y @modelcontextprotocol/server-filesystem /tmp

Inazindua UI kwenye http://localhost:6274 (matoleo mapya huchapisha URL yenye MCP_PROXY_AUTH_TOKEN query string, tumia link hiyo kamili au UI itakataa kukuunganisha) na proxy kwenye 6277. Bofya Connect, kisha List Tools, kisha Call Tool ukitumia arguments halisi. Ikiwa inafanya kazi kwenye Inspector lakini inafeli kwenye agent, hitilafu iko kwenye usanidi wa mteja wako, si kwenye seva. Kwa seva ya mbali ya HTTP, chagua transport ya Streamable HTTP, ingiza https://mcp.example.com/mcp, ongeza header ya Authorization, na uunganishe; hii ndiyo njia ya haraka zaidi ya kuthibitisha kuwa auth na proxy ni sahihi kabla ya agent yeyote kuhusika.

Kuweka seva katika hali ya kisasa

MCP inabadilika haraka, kwa hivyo fanya patching kwa ratiba. Seva za Node zinazozinduliwa kwa npx -y huchota toleo la hivi karibuni kila zinapozaliwa, jambo ambalo ni rahisi lakini halirudishiki; funga toleo kamili ulilolijaribu, lisome kutoka npm view @modelcontextprotocol/server-filesystem version na uliambatanishe kwenye jina la kifurushi katika .mcp.json (@modelcontextprotocol/server-filesystem@<version>), mara tu seva inapokuwa muhimu, na uliweke toleo jipya kwa makusudi. Seva za Python zilizo chini ya systemd husasishwa kwa sudo -H -u mcp /opt/mcp-ops/.venv/bin/pip install -U "mcp[cli]" ikifuatiwa na sudo systemctl restart mcp-ops. Fuatilia marekebisho ya spec ambayo SDK yako inalenga unapopandisha toleo, kwani kuruka mpaka kutoka SSE kwenda Streamable-HTTP kunaweza kubadilisha mfumo wa usafirishaji (transport) ambao wateja wako lazima wauombe.

Njia za kufeli, pamoja na ujumbe utakaouona

Wakala (agent) anaonyesha seva imefeli. claude mcp list huchapisha ✗ Failed to connect, na TUI huripoti MCP server 'filesystem' failed to start. Tekeleza claude --debug na kwa kawaida utaona Error: spawn npx ENOENT, amri hiyo haipo kwenye PATH ya wakala. Runtime haipo au haipo mahali ambapo wakala anatafuta: Node haijasakinishwa, npx haipo, au Python ya virtualenv inatajwa kwa jina lake pekee. Rekebisha amri hiyo iwe na njia kamili (absolute path) au sakinisha runtime, kisha unganisha tena.

Seva ya stdio inaunganisha, kisha inakata mara moja. Mteja (client) anaripoti hitilafu ya JSON parse, kitu kama Unexpected token 'S', "Server sta"... is not valid JSON au Failed to parse message. Sababu ni ileile kila wakati: seva iliandika mstari wa logi kwenye stdout. Kwenye stdio, stdout ndio chaneli ya JSON-RPC, kwa hivyo maandishi yoyote yasiyotakiwa huharibu mtiririko na handshake inafeli. Katika Node, console.log huenda kwenye stdout, tumia console.error. Katika Python, print() ya kawaida huenda kwenye stdout, andika logi ukitumia logging iliyosanidiwa kwenda sys.stderr, au pitisha file=sys.stderr. Kanuni ni ya lazima: kwenye stdio, JSON-RPC pekee ndiyo inaruhusiwa kwenye stdout, kila kitu kingine cha kibinadamu kiende kwenye stderr.

Seva ya mbali (remote server) inamaliza muda (timeout) au inakata wakati wa handshake. Mteja anafeli na MCP error -32000: Connection closed, au Inspector inakwama kwenye Connect na haiorodheshwi zana zozote. Nyuma ya nginx hii ni buffering: proxy inashikilia mtiririko wa SSE badala ya kuutoa (flush), kwa hivyo mteja anasubiri jibu ambalo halifiki. Ongeza proxy_buffering off; (na sehemu iliyobaki ya block katika Hatua ya 4) kwenye location. Thibitisha na curl -N dhidi ya URL ya umma, unapaswa kuona data ya tukio ikifika kidogo kidogo, si yote kwa pamoja mwishoni.

Uthibitishaji (Auth) unakataliwa. Mteja anaripoti Error POSTing to endpoint (HTTP 401) au moja kwa moja 401 Unauthorized. Aidha header haipo, token si sahihi, au variable ya shell ilikuwa tupu wakati mteja aliposoma usanidi, mtego wa kawaida, kwa sababu ${MCP_TOKEN} inapanuka na kuwa kitu kisicho na thamani ikiwa variable haijawekwa na nginx kisha huona Bearer bila thamani. Echo variable hiyo, ongeza tena header, na thibitisha kama baiti kamili zinalingana na token iliyo kwenye if ya nginx.

Huduma haitaki kuanza chini ya systemd. journalctl -u mcp-ops inaonyesha ModuleNotFoundError: No module named 'mcp', ExecStart inaelekeza kwenye Python ya mfumo badala ya mkalimani wa venv. Au Address already in use, mchakato mwingine unashikilia 8000; itafute kwa sudo ss -ltnp | grep 8000.

FAQ

MCP server ni nini hasa?

Ni programu inayotoa zana na rasilimali kwa mteja wa AI kupitia Model Context Protocol, ikitumia JSON-RPC 2.0. Model ya AI haiendeshi zana yenyewe; inamuuliza mteja wake, mteja anaita MCP server, na server hiyo inatekeleza na kurudisha matokeo. Kwa sababu itifaki hii ni ya kawaida, server moja hufanya kazi na mteja yeyote anayekubaliana na viwango hivyo, iwe ni Claude Code, Claude Desktop, au Gemini CLI.

Kuna tofauti gani kati ya usafirishaji wa stdio na HTTP?

Server ya stdio huzinduliwa na mteja kama mchakato msaidizi (child process) na huwasiliana kupitia stdin/stdout, kwa hivyo huishi na kufa pamoja na mteja mmoja kwenye mashine moja na haihitaji mtandao au uthibitishaji. Server ya HTTP ni huduma ya mtandao inayodumu kwa muda mrefu ambayo wateja wengi wanaweza kuifikia kwa wakati mmoja, ndiyo maana inahitaji TLS na uthibitishaji. Tumia stdio kwa zana za ndani za mtumiaji mmoja; tumia HTTP (Streamable HTTP kwenye server za sasa) kwa chochote kinachoshirikiwa au kinachodumu.

Ninawezaje kulinda MCP server ya mbali?

Chukulia kuwa inatoa ufikiaji wa zana kwenye faili, database, au shell yako, na usiiweke wazi bila uthibitishaji. Njia bora ni kuiweka ikiwa imefungwa kwenye localhost na kuifikia kupitia SSH tunnel au VPN ya kibinafsi; ikiwa lazima iwe ya umma, iweke nyuma ya reverse proxy inayotekeleza bearer token au mtiririko wa MCP OAuth. Tengeneza token hiyo kwa openssl rand -hex 32 na usiwahi kuifunga server kwenye 0.0.0.0 bila mojawapo ya hatua hizi mbele yake.

Ninawezaje kutatua hitilafu ya server inayokataa kuanza?

Kwanza angalia claude mcp list, ✗ Failed to connect na spawn ... ENOENT inamaanisha kuwa amri au runtime haipo, kwa hivyo rekebisha path au isakinishe. Ikiwa inaunganisha kisha inakata na hitilafu ya JSON parse, server inatuma log kwenye stdout na kuharibu mtiririko wa JSON-RPC; hamisha log zote kwenye stderr. Kwa jambo lingine lolote, endesha amri kamili chini ya MCP Inspector, ambayo huendesha server hiyo kwa kutengwa ili uweze kutofautisha hitilafu ya server na hitilafu ya usanidi wa mteja.