SSD Nodes Learn Hosting plans →
మార్గదర్శకాలు Matt Connorద్వారా Matt Connor · అప్‌డేట్ చేయబడింది 2026-08-30

VPSలో MCP సర్వర్లను రన్ చేయడం ఎలా?

AI కోడింగ్ ఏజెంట్ల కోసం మీ స్వంత VPSలో MCP సర్వర్లను సెటప్ చేయండి. stdio, remote HTTP, systemd, TLS మరియు అథెంటికేషన్ వంటి కీలక అంశాలతో పాటు సాధారణ లోపాలను ఎలా నివారించాలో తెలుసుకోండి.

మీరు ఏమి నిర్మిస్తున్నారు

ఒకే VPS పై రెండు పని చేసే MCP సెటప్‌లు. మొదటిది stdio సర్వర్, ఇది Claude Code ద్వారా child process గా ప్రారంభించబడి, pipe ద్వారా కమ్యూనికేట్ చేసే filesystem లేదా database టూల్. రెండవది remote HTTP సర్వర్, ఇది systemd మరియు TLS కలిగిన nginx reverse proxy వెనుక దీర్ఘకాలిక నెట్‌వర్క్ సర్వీస్‌గా నడుస్తుంది, దీనిని మీరు సూచించే ఏ MCP క్లయింట్ అయినా యాక్సెస్ చేయవచ్చు. వీటిలో దేని ఇన్‌స్టాలేషన్ అయినా చిన్నదే. ఈ గైడ్‌లో ఎక్కువ భాగం నిజంగా ఇబ్బంది కలిగించే రెండు విషయాల గురించి: JSON-RPC స్ట్రీమ్‌ను శుభ్రంగా ఉంచడం మరియు ప్రమాణీకరణ (authentication) లేని టూల్ ఎండ్‌పాయింట్‌ను ఎప్పుడూ పబ్లిక్ ఇంటర్నెట్‌లో ఉంచకపోవడం.

MCP అంటే ఏమిటి

Model Context Protocol అనేది AI క్లయింట్ (Claude Code, Claude Desktop, VPS పై Gemini CLI, లేదా మీ స్వంత స్క్రిప్ట్) బాహ్య సాధనాలను (tools) పిలవడానికి మరియు బాహ్య వనరులను చదవడానికి ఉపయోగించే ఒక ప్రామాణిక పద్ధతి. మోడల్ స్వయంగా ఏదీ రన్ చేయదు. ఇది క్లయింట్‌ను అడుగుతుంది, క్లయింట్ MCP server తో JSON-RPC 2.0 ద్వారా మాట్లాడుతుంది, సర్వర్ ఆ సాధనాన్ని రన్ చేసి ఫలితాన్ని తిరిగి ఇస్తుంది. ప్రజలు agent harness అని దేనిని అంటారో అదే ఈ క్లయింట్: ఇది మోడల్ చుట్టూ ఉండే లూప్, ఇది సాధనాల జాబితాను, అనుమతుల తనిఖీలను మరియు సెషన్ స్థితిని కలిగి ఉంటుంది. MCP అనేది కేవలం ఆ సాధనాల విభాగాన్ని విస్తరించే మార్గం. ఇది ఒకే ప్రోటోకాల్, కాబట్టి మీరు ఒకసారి రాసిన సర్వర్ MCPని సపోర్ట్ చేసే ప్రతి క్లయింట్‌తో పనిచేస్తుంది. ఈ విభజన మీకు కొత్తగా ఉంటే, ముఖ్యంగా ఒక మోడల్ సాధనాన్ని ఉపయోగించాలని ఎలా నిర్ణయించుకుంటుంది అనే ప్రశ్న ఉంటే, agent fundamentals లోని దశల వారీ మార్గం గురించి తెలుసుకోవడం మంచిది. ఈ సర్వర్లకు నిజమైన క్రెడెన్షియల్స్ ఇచ్చే ముందు దీనికి ఒక గంట సమయం కేటాయించడం ప్రయోజనకరం.

రెండు రవాణా పద్ధతులు (transports) ఉన్నాయి, ఈ గైడ్ మిగిలిన భాగం వీటి ఆధారంగానే విభజించబడింది:

  • stdio. క్లయింట్ సర్వర్‌ను ఒక చైల్డ్ ప్రాసెస్‌గా ప్రారంభిస్తుంది మరియు దాని standard input మరియు standard output ద్వారా newline-delimited JSON-RPC సందేశాలను మార్పిడి చేసుకుంటుంది. ఇందులో నెట్‌వర్క్, పోర్ట్ లేదా అథెంటికేషన్ ఉండవు; ప్రాసెస్ మాత్రమే ట్రస్ట్ బౌండరీగా ఉంటుంది. దాదాపు అన్ని లోకల్ టూల్స్ ఈ పద్ధతిలోనే పనిచేస్తాయి.
  • Streamable HTTP (మరియు దీని పాత వెర్షన్, HTTP+SSE). సర్వర్ అనేది నిరంతరం నడిచే వెబ్ సర్వీస్. క్లయింట్ HTTP ద్వారా కనెక్ట్ అవుతుంది మరియు సర్వర్ Server-Sent Events ద్వారా ప్రతిస్పందనలను స్ట్రీమ్ చేయగలదు. ఒకే సర్వర్‌ను అనేక క్లయింట్‌లతో పంచుకోవడానికి లేదా సర్వర్‌లో శాశ్వతంగా ఉండాల్సిన సాధనాన్ని రన్ చేయడానికి ఇది ఉపయోగపడుతుంది.

సాధనం ఒకే మెషీన్‌కు మరియు ఒకే యూజర్‌కు చెందినదైతే stdioని ఎంచుకోండి. అది ఒక షేర్డ్ సర్వీస్ అయితే HTTPని ఎంచుకోండి.

ముందస్తు అవసరాలు మరియు వాస్తవ సవాళ్లు

root లేదా sudo అనుమతులు కలిగిన తాజా Ubuntu 24.04 KVM VPS ఉందని భావించండి. వీటితో పాటు:

  • సర్వర్ ఏ runtime లో వ్రాయబడిందో అది ఉండాలి. చాలా రిఫరెన్స్ సర్వర్లు Node లేదా Python లో ఉంటాయి. Ubuntu 24.04 లో Node 18 ఉంటుంది, కానీ ప్రస్తుత అనేక MCP ప్యాకేజీలకు Node 20 లేదా అంతకంటే కొత్త వెర్షన్ అవసరం. కాబట్టి apt పై ఆధారపడకుండా, NodeSource లేదా nvm నుండి ప్రస్తుత LTS వెర్షన్‌ను ఇన్‌స్టాల్ చేయండి. Python 3.12 ఇప్పటికే అందుబాటులో ఉంది.
  • ఒక డొమైన్ మరియు DNS A record, ఇది రిమోట్ HTTP సర్వర్ కోసం మాత్రమే. TLS కోసం ఈ VPS కి రిజాల్వ్ అయ్యే పేరు అవసరం. stdio ఉదాహరణకు ఎటువంటి DNS అవసరం లేదు.
  • 512 MB RAM సరిపోతుంది. MCP సర్వర్లు తేలికపాటి JSON-RPC ప్రాసెస్‌లు; మెమరీ వినియోగం అనేది ప్రోటోకాల్‌పై కాకుండా, మీ టూల్ దేనిని ఉపయోగిస్తుందనే దానిపై (డేటాబేస్ డ్రైవర్, ఫైల్ క్యాచీ వంటివి) ఆధారపడి ఉంటుంది.
  • ఈ స్పెసిఫికేషన్ కొత్తది మరియు మారుతూ ఉంది. 2025-03-26 నాటి రివిజన్ HTTP+SSE స్థానంలో Streamable HTTPని ప్రవేశపెట్టింది మరియు SSEని deprecated గా ప్రకటించింది. SSE ఇప్పటికీ పనిచేస్తుంది మరియు చాలా సర్వర్లు దీనిని ఉపయోగిస్తున్నాయి. కాబట్టి ఏదైనా ట్రాన్స్‌పోర్ట్ పద్ధతిని ఖచ్చితమైనదిగా భావించకుండా, సర్వర్ యొక్క release notes ను బట్టి ఎప్పటికప్పుడు సరిచూసుకోండి.

దశ 1: Claude Code లో stdio సర్వర్‌ను అనుసంధానించడం

Filesystem సర్వర్‌తో ప్రారంభించండి. ఇది అధికారికమైనది, నిరంతరం అప్‌డేట్ చేయబడుతుంది మరియు దీనికి Node తప్ప మరేమీ అవసరం లేదు. కింది కమాండ్ దీనిని Claude Code తో రిజిస్టర్ చేస్తుంది మరియు ప్రస్తుత ప్రాజెక్ట్‌కు పరిమితం చేస్తుంది, తద్వారా ఇది commit చేయదగిన ఫైల్‌లో సేవ్ అవుతుంది:

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

-- సెపరేటర్ చాలా ముఖ్యం: దీని తర్వాత ఉన్నదంతా Claude Code రన్ చేసే కమాండ్, ఇది Claude Code కోసం ఫ్లాగ్ కాదు. ఇది ప్రాజెక్ట్ రూట్ డైరెక్టరీలో .mcp.json ను క్రియేట్ చేస్తుంది:

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

ప్రస్తుతానికి ఏదీ రన్ అవ్వడం లేదు. మీరు తదుపరిసారి ఈ డైరెక్టరీలో Claude Code ను ప్రారంభించినప్పుడు, ఏజెంట్ .mcp.json ను చదివి, npx -y @modelcontextprotocol/server-filesystem ... ను చైల్డ్ ప్రాసెస్‌గా స్పాన్ చేస్తుంది మరియు ఆ ప్రాసెస్ యొక్క stdin/stdout ద్వారా MCP హ్యాండ్‌షేక్‌ను పూర్తి చేస్తుంది. ఇది విజయవంతమైందో లేదో ఇలా నిర్ధారించుకోండి:

claude mcp list

సరిగ్గా పనిచేస్తున్న సర్వర్ తన కమాండ్‌ను మరియు ఆకుపచ్చ రంగు టిక్ మార్కును, filesystem: npx -y @modelcontextprotocol/server-filesystem ... - ✓ Connected ను చూపిస్తుంది. సెషన్ లోపల, /mcp స్లాష్ కమాండ్ సర్వర్ అందించే టూల్స్‌ను (read_file, write_file, list_directory) జాబితా చేస్తుంది. ఇప్పుడు ఏజెంట్ మీరు అనుమతించిన పాత్‌లలో వీటిని ఉపయోగించగలదు. డేటాబేస్ టూల్ కూడా ఇదే విధంగా పనిచేస్తుంది; ప్యాకేజీని మార్చి, కనెక్షన్ స్ట్రింగ్‌ను చివరి ఆర్గ్యుమెంట్‌గా ఇవ్వండి. అయితే, ప్రస్తుత ప్యాకేజీ పేరు కోసం సర్వర్ యొక్క సొంత రిపోజిటరీని తనిఖీ చేయండి, ఎందుకంటే రిఫరెన్స్ Postgres సర్వర్ నిర్వహణ పలుమార్లు మారింది.

ఏజెంట్‌ను సర్వర్‌పై రన్ చేయడం వల్ల కలిగే ప్రధాన ప్రయోజనం ఇదే: Claude Code సెషన్ VPS లో tmux లో రన్ అవుతుంది, మరియు దాని stdio సర్వర్లు ప్రాజెక్ట్ ఫైళ్లు మరియు లోకల్ సర్వీసులకు నేరుగా యాక్సెస్ కలిగి పక్కనే రన్ అవుతాయి, దీనివల్ల నెట్‌వర్క్ రౌండ్-ట్రిప్ అవసరం ఉండదు. ఏజెంట్ వద్ద write_file తో పాటు read_file కూడా ఉన్నప్పుడు, అతి తక్కువ మార్పుతో పనిచేసేలా చేసే నైపుణ్యాన్ని దీనికి జోడించడం మంచిది. ఎందుకంటే filesystem టూల్ అందుబాటులో ఉంటే, రెండు లైన్ల చిన్న మార్పుకు బదులుగా మొత్తం కోడ్‌ను మార్చేయడం కూడా ఏజెంట్‌కు చాలా సులభం అవుతుంది. ఈ అనుసంధానం లోకల్ ఫైళ్లకు మాత్రమే పరిమితం కాదు: మీరు ఇప్పటికే VPS లో సెర్చ్ ఇంజిన్‌ను రన్ చేస్తుంటే, మీ సొంత SearXNG ఇన్‌స్టన్స్‌ను సెర్చ్ టూల్‌గా ఏజెంట్‌కు ఇవ్వవచ్చు. దీనివల్ల క్వెరీలు మీ సర్వర్‌లోనే ఉంటాయి, కానీ నమ్మదగని వెబ్ పేజీల టెక్స్ట్ నేరుగా ఏజెంట్ కాంటెక్స్ట్‌లోకి వస్తుంది, దానిపై ఏజెంట్ తదుపరి చర్యలు తీసుకుంటుంది.

దశ 2: రిమోట్ HTTP సర్వర్‌ను నిర్మించడం

stdio సర్వర్ దాని పేరెంట్ ప్రాసెస్ ముగిసినప్పుడు ఆగిపోతుంది మరియు ప్రతి క్లయింట్‌కు ఒకసారి మాత్రమే ఇది ప్రారంభమవుతుంది. కాబట్టి, మీరు ఒకే బాక్స్‌పై రెండు Claude Code సెషన్‌లను నడుపుతూ, అవి ఒకదానికొకటి పనిని అప్పగించుకునేలా చేస్తే, ప్రతి సెషన్‌కు ఆ టూల్ యొక్క సొంత ప్రైవేట్ కాపీ లభిస్తుంది. ప్రతి క్లయింట్ కోసం నిరంతరం అందుబాటులో ఉండే టూల్, షేర్డ్ ఆప్స్ టూల్, డేటాబేస్ గేట్‌వే, లేదా మీ ల్యాప్‌టాప్ మరియు CI రెండూ కాల్ చేసే ఏదైనా సేవ మీకు కావాలంటే, మీకు HTTP ట్రాన్స్‌పోర్ట్ మరియు ఒక నిజమైన సర్వీస్ అవసరం. అధికారిక SDKని ఉపయోగించి ఒక టూల్‌ను ఎక్స్‌పోజ్ చేసే కనీస స్థాయి Python సర్వర్ ఇక్కడ ఉంది:

# /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")

గమనిక host="127.0.0.1". ఈ సర్వర్ localhost కు మాత్రమే బైండ్ అవుతుంది, కాబట్టి బయటి నుంచి ఏదీ నేరుగా దీనిని చేరుకోలేదు. అథెంటికేషన్ (auth) లేనప్పుడు మీకు కావలసింది ఇదే. దీనిని దాని స్వంత virtualenv లో ఇన్‌స్టాల్ చేయండి, తద్వారా systemd కి స్థిరమైన ఇంటర్‌ప్రెటర్ పాత్ ఉంటుంది:

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]"

Step 3: keep it alive with systemd

A tool that is down when the agent reaches for it is worse than no tool. That matters most when the client is itself a long-lived process: an always-on agent that keeps its memory and schedules across reboots will call these tools on a schedule with nobody watching, so the server has to come back on its own too. Write /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

The absolute path to the venv Python in ExecStart is not optional, point it at /usr/bin/python3 and the process starts with ModuleNotFoundError: No module named 'mcp', because the system interpreter never saw your pip install. Enable and check:

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 should read active (running). The curl comes back HTTP/1.1 400 Bad Request with a JSON-RPC error in the body, the request carried no session and no valid JSON payload, and that is exactly what you want: it proves the port answers and speaks the protocol. Connection refused or an empty reply means the process is not bound where you think; read journalctl -u mcp-ops -n 50.

దశ 4: TLS మరియు reverse proxyని ముందు ఉంచడం

సర్వర్ localhost పై వింటుంది. దీన్ని ఎక్కడి నుంచైనా చేరుకోవడానికి, మీరు nginx వద్ద TLS termination చేసి, లోపలికి proxy చేయాలి. nginx ని ఇన్‌స్టాల్ చేసి, Certbot మరియు Let's Encrypt on nginx ద్వారా certificate పొందండి, ఆపై location block ను రాయండి. ఇక్కడ ముఖ్యమైన విషయం buffering ను నిలిపివేయడం, ఎందుకంటే nginx డిఫాల్ట్ ప్రవర్తన ప్రతిస్పందన పూర్తయ్యే వరకు దాన్ని నిలిపి ఉంచుతుంది, ఇది SSE stream ను శాశ్వతంగా నిలిపివేస్తుంది:

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;
    }
}

sudo nginx -t && sudo systemctl reload nginx తో reload చేయండి. మీరు ఇప్పటికే అనేక containers నడుపుతుంటే, Traefik reverse proxy with automatic TLS ద్వారా అదే పని సులభంగా జరుగుతుంది, ఇది certificate ను జారీ చేసి hostname ఆధారంగా route చేస్తుంది, మీరు కేవలం MCP container కు labels జోడిస్తే సరిపోతుంది. ఏది ఏమైనా, ఇప్పుడు public port పై reverse proxy మాత్రమే ఉంటుంది, ఇది మీరు ఇంకా భద్రపరచని సేవను సూచిస్తుంది. మీరు URL ను ఎక్కడైనా నమోదు చేసే ముందు దీన్ని సరిచేయండి.

దశ 5: ఈ అంశంలో అత్యంత ముఖ్యమైన భద్రతా నియమం

అథెంటికేషన్ లేని MCP ఎండ్‌పాయింట్‌ను ఎప్పుడూ బహిర్గతం చేయకండి. MCP సర్వర్ అనేది కేవలం read-only API కాదు. ఇది మీ ఫైళ్లు, డేటాబేస్ మరియు కొన్నిసార్లు షెల్ (shell) కు కూడా టూల్ యాక్సెస్‌ను ఇస్తుంది. పబ్లిక్ ఇంటర్నెట్‌లో తెరిచి ఉంచిన /mcp అనేది మీ AI ఏజెంట్‌కు ఉన్నంత యాక్సెస్ ఉన్న ఒక అపరిచితుడితో సమానం: వారు మీ టూల్స్‌ను చూస్తారు, ఆపై వాటిని రన్ చేస్తారు. దీన్ని అథెంటికేషన్ లేని అడ్మిన్ సాకెట్‌గా పరిగణించండి, ఎందుకంటే అది అదే పని చేస్తుంది. దొంగిలించబడిన టోకెన్ ద్వారా ఎంత నష్టం జరుగుతుందనేది వెనుక ఉన్న సర్వర్‌పై ఆధారపడి ఉంటుంది: openGym వర్కవుట్ ట్రాకర్‌తో వచ్చే read-only MCP సర్వర్ కేవలం శిక్షణ డేటాను మాత్రమే ఇవ్వగలదు, కానీ ఫైల్‌సిస్టమ్ లేదా షెల్ టూల్ సర్వర్ మొత్తాన్ని అప్పగిస్తుంది.

ప్రాధాన్యత క్రమంలో మూడు రక్షణ మార్గాలు:

  1. దీన్ని పబ్లిష్ చేయకండి. సర్వర్‌ను 127.0.0.1 లోనే ఉంచండి మరియు SSH టన్నెల్ ద్వారా మీ ల్యాప్‌టాప్ నుండి యాక్సెస్ చేయండి: ssh -L 8000:127.0.0.1:8000 matt@vps, ఆపై క్లయింట్‌ను http://127.0.0.1:8000/mcp కి పాయింట్ చేయండి. ఏదీ బహిర్గతం కాదు.
  2. ప్రైవేట్ నెట్‌వర్క్‌లో ఉంచండి. self-hosted WireGuard VPN యొక్క టన్నెల్ అడ్రస్‌కు బైండ్ చేయండి మరియు VPN పీర్స్ మాత్రమే దీన్ని యాక్సెస్ చేసేలా చూడండి. పబ్లిక్ ఇంటర్నెట్‌కు పోర్ట్ క్లోజ్డ్‌గా కనిపిస్తుంది.
  3. పబ్లిక్‌గా ఉండాల్సి వస్తే, టోకెన్ తప్పనిసరి చేయండి. HTTP ట్రాన్స్‌పోర్ట్ నేరుగా సపోర్ట్ చేసే MCP OAuth ఫ్లో సరైన మార్గం. కనీస అవసరంగా ప్రాక్సీ వద్ద చెక్ చేసే షేర్డ్ బేరర్ టోకెన్ వాడండి; ఇది చౌకైనది మరియు అనధికారిక యాక్సెస్‌ను పూర్తిగా అడ్డుకుంటుంది:
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...
}

openssl rand -hex 32 తో టోకెన్‌ను జనరేట్ చేయండి, మరియు వీటిలో ఏదీ లేకుండా సర్వర్‌ను ఎప్పుడూ 0.0.0.0 కి బైండ్ చేయకండి. క్లయింట్ అప్పుడు టోకెన్‌ను హెడర్‌గా పంపుతుంది. Claude Code లో:

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

మీ షెల్‌లో MCP_TOKEN ని సెట్ చేయండి, తద్వారా సీక్రెట్ ఎప్పుడూ .mcp.json లో ప్లెయిన్ టెక్స్ట్‌గా ఉండదు. Claude Code రీడ్ చేసే సమయంలో ఎన్విరాన్‌మెంట్ నుండి ${MCP_TOKEN} ని ఎక్స్‌పాండ్ చేస్తుంది.

పైన పేర్కొన్న ప్రతి రక్షణ మార్గం ఎండ్‌పాయింట్‌ను కాపాడుతుంది, కానీ టోకెన్ ఇప్పటికే ఉన్న ఏజెంట్‌ను కాదు. ఇది సమస్యలో మరో భాగం: మీ క్లయింట్ DeepSeek Harness అయితే, ఏజెంట్ ఏ టూల్స్‌ను వాడవచ్చు మరియు టూల్ అవుట్‌పుట్‌లో ఇంజెక్ట్ చేసిన ఇన్‌స్ట్రక్షన్లను స్కాన్ చేసే ప్లగిన్‌లు ఆ వైపు రక్షణ కల్పిస్తాయి.

దశ 6: MCP Inspector తో డీబగ్ చేయడం

సర్వర్ సరిగ్గా పనిచేయనప్పుడు, ఏజెంట్ లోపల ఊహించడం కంటే, అధికారిక వెబ్-ఆధారిత టెస్ట్ క్లయింట్ అయిన Inspector తో నేరుగా పరీక్షించండి. stdio సర్వర్ కోసం, ఏజెంట్ రన్ చేసే అదే కమాండ్‌ను దీనికి ఇవ్వండి:

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

ఇది http://localhost:6274 వద్ద ఒక UIని ప్రారంభిస్తుంది (ఇటీవలి వెర్షన్లు MCP_PROXY_AUTH_TOKEN క్వెరీ స్ట్రింగ్‌తో కూడిన URLను ప్రింట్ చేస్తాయి, ఆ ఖచ్చితమైన లింక్‌ను ఉపయోగించండి, లేకపోతే UI మిమ్మల్ని అనుమతించదు) మరియు 6277 పోర్ట్ వద్ద ఒక ప్రాక్సీని ప్రారంభిస్తుంది. Connect పై క్లిక్ చేసి, ఆపై List Tools ఎంచుకుని, ఆ తర్వాత అసలైన ఆర్గ్యుమెంట్లతో Call Tool క్లిక్ చేయండి. ఇది Inspector లో పనిచేసి, ఏజెంట్‌లో విఫలమైతే, బగ్ మీ క్లయింట్ కాన్ఫిగరేషన్‌లో ఉంది, సర్వర్‌లో కాదు. రిమోట్ HTTP సర్వర్ కోసం, Streamable HTTP ట్రాన్స్‌పోర్ట్‌ను ఎంచుకుని, https://mcp.example.com/mcp ని ఎంటర్ చేసి, Authorization హెడర్‌ను జోడించి కనెక్ట్ అవ్వండి. ఏజెంట్‌తో సంబంధం లేకుండా, అథెంటికేషన్ మరియు ప్రాక్సీ సరిగ్గా ఉన్నాయని నిర్ధారించుకోవడానికి ఇది అత్యంత వేగవంతమైన మార్గం.

సర్వర్లను అప్‌డేట్‌గా ఉంచడం

MCP వేగంగా అభివృద్ధి చెందుతోంది, కాబట్టి నిర్ణీత షెడ్యూల్ ప్రకారం ప్యాచ్‌లను వర్తింపజేయండి. npx -y తో ప్రారంభించిన Node సర్వర్లు ప్రతిసారీ తాజా వెర్షన్‌ను పొందుతాయి, ఇది సౌకర్యవంతంగా ఉన్నప్పటికీ పునరుత్పత్తికి (reproducibility) అనుకూలం కాదు; మీరు పరీక్షించిన ఖచ్చితమైన వెర్షన్‌ను npm view @modelcontextprotocol/server-filesystem version నుండి చదివి, దానిని .mcp.json (@modelcontextprotocol/server-filesystem@<version>) లోని ప్యాకేజీ పేరుకు జోడించండి. సర్వర్ ముఖ్యమైనదిగా మారినప్పుడు, వెర్షన్‌ను ఉద్దేశపూర్వకంగా అప్‌డేట్ చేయండి. systemd కింద నడిచే Python సర్వర్లను sudo -H -u mcp /opt/mcp-ops/.venv/bin/pip install -U "mcp[cli]" మరియు దాని తర్వాత sudo systemctl restart mcp-ops ఉపయోగించి అప్‌డేట్ చేయండి. మీరు అప్‌గ్రేడ్ చేసేటప్పుడు మీ SDK లక్ష్యంగా చేసుకున్న spec revision ను గమనించండి; SSE నుండి Streamable-HTTP కి మారడం వల్ల మీ క్లయింట్లు అభ్యర్థించాల్సిన ట్రాన్స్‌పోర్ట్ పద్ధతి మారవచ్చు.

వైఫల్య రీతులు మరియు మీరు చూసే సందేశాలు

ఏజెంట్ సర్వర్ విఫలమైందని చూపిస్తుంది. claude mcp list అనేది ✗ Failed to connectని ప్రింట్ చేస్తుంది మరియు TUI లో MCP server 'filesystem' failed to start అని కనిపిస్తుంది. claude --debugని రన్ చేయండి, అప్పుడు సాధారణంగా Error: spawn npx ENOENT కనిపిస్తుంది, అంటే ఆ కమాండ్ ఏజెంట్ యొక్క PATH లో లేదు. రన్‌టైమ్ అందుబాటులో లేదు లేదా ఏజెంట్ వెతికే చోట లేదు: Node ఇన్‌స్టాల్ చేయబడలేదు, npx లేదు, లేదా వర్చువల్ ఎన్విరాన్‌మెంట్ (virtualenv) Python ను కేవలం పేరుతోనే పిలుస్తున్నారు. కమాండ్‌ను అబ్సల్యూట్ పాత్‌కు మార్చండి లేదా రన్‌టైమ్‌ను ఇన్‌స్టాల్ చేసి, ఆపై మళ్ళీ కనెక్ట్ అవ్వండి.

stdio సర్వర్ కనెక్ట్ అయ్యి, వెంటనే డిస్‌కనెక్ట్ అవుతుంది. క్లయింట్ లాగ్స్‌లో JSON పార్స్ ఎర్రర్, అంటే Unexpected token 'S', "Server sta"... is not valid JSON లేదా Failed to parse message వంటివి కనిపిస్తాయి. దీనికి కారణం ఎప్పుడూ ఒకటే: సర్వర్ stdout కు లాగ్ లైన్‌ను రాసింది. stdio లో, stdout అనేది JSON-RPC ఛానల్, కాబట్టి ఏ చిన్న అదనపు టెక్స్ట్ అయినా స్ట్రీమ్‌ను పాడు చేస్తుంది మరియు హ్యాండ్‌షేక్ విఫలమవుతుంది. Node లో, console.log అనేది stdout కు వెళ్తుంది, దానికి బదులుగా console.error ఉపయోగించండి. Python లో, సాధారణ print() అనేది stdout కు వెళ్తుంది, కాబట్టి లాగ్స్‌ను sys.stderr కి కాన్ఫిగర్ చేసిన logging తో రాయండి, లేదా file=sys.stderr ని పాస్ చేయండి. నియమం స్పష్టం: stdio లో, stdout పై కేవలం JSON-RPC మాత్రమే ఉండాలి, మనుషులు చదివే సమాచారం అంతా stderr పైనే ఉండాలి.

రిమోట్ సర్వర్ టైమ్ అవుట్ అవుతుంది లేదా హ్యాండ్‌షేక్ మధ్యలోనే ఆగిపోతుంది. క్లయింట్ MCP error -32000: Connection closed తో విఫలమవుతుంది, లేదా ఇన్‌స్పెక్టర్ Connect వద్ద ఆగిపోయి టూల్స్‌ను చూపించదు. nginx వెనుక ఇలా జరగడానికి కారణం బఫరింగ్: ప్రాక్సీ SSE స్ట్రీమ్‌ను ఫ్లష్ చేయకుండా తన వద్దే ఉంచుకుంటుంది, కాబట్టి క్లయింట్ ఎప్పటికీ రాని ప్రతిస్పందన కోసం వేచి ఉంటుంది. proxy_buffering off; ని (మరియు స్టెప్ 4 లోని మిగిలిన బ్లాక్‌ను) location కి జోడించండి. పబ్లిక్ URL పై curl -N తో దీన్ని నిర్ధారించండి, ఈవెంట్ డేటా అంతా ఒకేసారి కాకుండా, క్రమంగా రావడం మీరు గమనించాలి.

అథెంటికేషన్ తిరస్కరించబడింది. క్లయింట్ Error POSTing to endpoint (HTTP 401) అని లేదా నేరుగా 401 Unauthorized అని రిపోర్ట్ చేస్తుంది. హెడర్ లేకపోవడం, టోకెన్ తప్పుగా ఉండటం, లేదా క్లయింట్ కాన్ఫిగరేషన్‌ను చదివేటప్పుడు షెల్ వేరియబుల్ ఖాళీగా ఉండటం వంటివి కారణం కావచ్చు. ఇది సాధారణంగా జరిగే పొరపాటు, ఎందుకంటే వేరియబుల్ సెట్ చేయనప్పుడు ${MCP_TOKEN} ఏమీ చూపదు మరియు nginx అప్పుడు విలువ లేని Bearer ని చూస్తుంది. వేరియబుల్‌ను echo చేసి చూడండి, హెడర్‌ను మళ్ళీ జోడించండి మరియు nginx if లోని టోకెన్‌తో ఖచ్చితమైన బైట్లు సరిపోలుతున్నాయో లేదో సరిచూసుకోండి.

systemd కింద సర్వీస్ ప్రారంభం కావడం లేదు. journalctl -u mcp-ops లో ModuleNotFoundError: No module named 'mcp' కనిపిస్తుంది, ExecStart అనేది venv ఇంటర్‌ప్రెటర్‌కు బదులుగా సిస్టమ్ Python ను సూచిస్తుంది. లేదా Address already in use రావచ్చు, అంటే మరొక ప్రాసెస్ 8000 పోర్ట్‌ను ఆక్రమించి ఉంది; దాన్ని sudo ss -ltnp | grep 8000 తో కనుగొనండి.

FAQ

MCP సర్వర్ అంటే ఏమిటి?

ఇది Model Context Protocol ద్వారా AI క్లయింట్‌కు టూల్స్ మరియు రిసోర్స్‌లను అందించే ఒక ప్రోగ్రామ్. ఇది JSON-RPC 2.0 ను ఉపయోగిస్తుంది. AI మోడల్ స్వయంగా టూల్‌ను రన్ చేయదు; అది తన క్లయింట్‌ను అడుగుతుంది, క్లయింట్ MCP సర్వర్‌ను పిలుస్తుంది, సర్వర్ దానిని అమలు చేసి ఫలితాన్ని తిరిగి పంపుతుంది. ఈ ప్రోటోకాల్ ప్రామాణికమైనది కాబట్టి, Claude Code, Claude Desktop లేదా Gemini CLI వంటి ఏదైనా అనుకూల క్లయింట్‌తో ఒకే సర్వర్ పనిచేస్తుంది.

stdio మరియు HTTP ట్రాన్స్‌పోర్ట్ మధ్య తేడా ఏమిటి?

stdio సర్వర్‌ను క్లయింట్ ఒక చైల్డ్ ప్రాసెస్‌గా లాంచ్ చేస్తుంది మరియు ఇది stdin/stdout ద్వారా కమ్యూనికేట్ చేస్తుంది. కాబట్టి ఇది ఒక మెషీన్‌పై ఒక క్లయింట్‌తోనే ఉంటుంది మరియు దీనికి నెట్‌వర్క్ లేదా అథెంటికేషన్ అవసరం లేదు. HTTP సర్వర్ అనేది ఒకే సమయంలో అనేక క్లయింట్లు యాక్సెస్ చేయగల నెట్‌వర్క్ సర్వీస్, అందుకే దీనికి TLS మరియు అథెంటికేషన్ అవసరం. స్థానిక, సింగిల్-యూజర్ టూల్స్ కోసం stdioని ఉపయోగించండి; షేర్డ్ లేదా పర్సిస్టెంట్ అవసరాల కోసం HTTP (ప్రస్తుత సర్వర్లలో Streamable HTTP)ని ఉపయోగించండి.

రిమోట్ MCP సర్వర్‌ను ఎలా సురక్షితం చేయాలి?

ఇది మీ ఫైల్స్, డేటాబేస్ లేదా షెల్‌కు యాక్సెస్ ఇస్తుందని భావించండి మరియు అథెంటికేషన్ లేకుండా దీనిని ఎప్పుడూ ఎక్స్‌పోజ్ చేయవద్దు. దీనిని localhost కే పరిమితం చేసి, SSH టన్నెల్ లేదా ప్రైవేట్ VPN ద్వారా యాక్సెస్ చేయడం ఉత్తమం. ఒకవేళ ఇది పబ్లిక్‌గా ఉండాల్సి వస్తే, బేరర్ టోకెన్ లేదా MCP OAuth ఫ్లోను అమలు చేసే రివర్స్ ప్రాక్సీ వెనుక ఉంచండి. openssl rand -hex 32 తో టోకెన్‌ను జనరేట్ చేయండి మరియు వీటిలో ఏదీ లేకుండా 0.0.0.0 కి సర్వర్‌ను ఎప్పుడూ బైండ్ చేయవద్దు.

ప్రారంభం కాని సర్వర్‌ను ఎలా డీబగ్ చేయాలి?

ముందుగా claude mcp list, ✗ Failed to connect లను తనిఖీ చేయండి. spawn ... ENOENT అంటే కమాండ్ లేదా రన్‌టైమ్ అందుబాటులో లేదని అర్థం, కాబట్టి పాత్‌ను సరిచేయండి లేదా ఇన్‌స్టాల్ చేయండి. ఒకవేళ అది కనెక్ట్ అయ్యి, JSON పార్స్ ఎర్రర్‌తో ఆగిపోతే, సర్వర్ stdout కి లాగ్ చేస్తూ JSON-RPC స్ట్రీమ్‌ను పాడు చేస్తోందని అర్థం; అన్ని లాగ్‌లను stderr కి మార్చండి. ఇతర సమస్యల కోసం, MCP Inspector కింద అదే కమాండ్‌ను రన్ చేయండి. ఇది సర్వర్‌ను ఐసోలేషన్‌లో రన్ చేస్తుంది, తద్వారా సర్వర్ బగ్‌ను మరియు క్లయింట్-కాన్ఫిగరేషన్ బగ్‌ను మీరు వేరు చేసి చూడవచ్చు.

#mcp#claude-code#ai-agents#self-hosting#systemd