Host a remote MCP server

Create the VM#

On your computer (pick another name if my-mcp-server is taken):

ssh exe.dev new --name=my-mcp-server
ssh my-mcp-server.exe.xyz

Everything else runs on the VM, as exedev.

Prepare the VM#

Install Python 3.14 with the preinstalled uv, make the directories, create ~/mcp-server.env for settings and secrets, and fetch the client from Connect your agents as ~/bin/mcp-check (uv installs its one dependency on first run):

uv python install 3.14
mkdir -p ~/data ~/backups ~/bin
if [ ! -e ~/mcp-server.env ]; then
  install -m 600 /dev/null ~/mcp-server.env
  cat >> ~/mcp-server.env <<EOF
# Settings and secrets for mcp-server.service.
# One KEY=value per line, no quotes. Back this file up.
PORT=8000
NOTES_DB=$HOME/data/notes.db
EOF
fi
curl -fsSL -o ~/bin/mcp-check https://exe-staging.dev/deploy/mcp-server/check.py
chmod +x ~/bin/mcp-check

Then install one of three: the starter, a repository, or stdio servers.

The starter#

server.py is a 150-line notes server on the official MCP Python SDK: four tools over SQLite, Streamable HTTP at /mcp, stateless so restarts drop nothing. It answers only requests addressed to $(hostname).exe.xyz or localhost (421 otherwise) and from no other web page (403), so sites you visit can't call your tools through your browser.

mkdir -p ~/mcp-server && cd ~/mcp-server
curl -fsSLO https://exe-staging.dev/deploy/mcp-server/server.py
uv init --bare --python 3.14
uv add 'mcp>=2.3,<3'

The service runs it with the project's Python:

sudo tee /etc/systemd/system/mcp-server.service >/dev/null <<'EOF'
[Unit]
Description=MCP server (~/mcp-server)
After=network-online.target
Wants=network-online.target

[Service]
User=exedev
WorkingDirectory=/home/exedev/mcp-server
EnvironmentFile=/home/exedev/mcp-server.env
Environment=PATH=/home/exedev/.local/bin:/usr/local/bin:/usr/bin:/bin
ExecStart=/home/exedev/mcp-server/.venv/bin/python server.py
Restart=always
RestartSec=2

[Install]
WantedBy=multi-user.target
EOF
sudo systemctl daemon-reload
sudo systemctl enable --now mcp-server

Now check it.

Or: a server from a repository#

Clone it into ~/mcp-server (your repository for OWNER/NAME) and install it as its README says:

git clone https://github.com/OWNER/NAME.git ~/mcp-server

If that asks for a password, the repository is private. On your computer, connect it with the GitHub integration, then clone through it, with no token on the VM:

ssh exe.dev integrations add github --name NAME --repository OWNER/NAME --attach vm:my-mcp-server

git clone https://github.int.exe.xyz/OWNER/NAME.git ~/mcp-server

It must speak Streamable HTTP on port 8000, on all interfaces, at a known path (usually /mcp). Most SDK-based servers can:

• Python SDK (MCPServer, formerly FastMCP): mcp.run("streamable-http", host="0.0.0.0", port=int(os.environ["PORT"])).
• TypeScript SDK: a StreamableHTTPServerTransport in an HTTP server on process.env.PORT.
• Otherwise: look for a --transport http (or streamable-http) flag, or wrap it as a stdio server.

If it checks the Host header (both SDKs can, and do when bound to localhost), allow $(hostname).exe.xyz. Put its secrets in ~/mcp-server.env. Write mcp-server.service as for the starter, with the server's command (full paths) as ExecStart, and start it.

Or: stdio servers#

A stdio server talks to one client over stdin and stdout. mcp-proxy starts each one you list and serves it over HTTP. Install it, plus Node.js 24 from NodeSource for npx servers:

uv tool install 'mcp-proxy>=0.13,<0.14'
curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt-get install -y nodejs

List the servers in ~/mcp-server/servers.json, in Claude Desktop's format. This one serves a directory of files and a web page fetcher:

mkdir -p ~/mcp-server ~/shared
cat > ~/mcp-server/servers.json <<'EOF'
{
  "mcpServers": {
    "files": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem@2", "/home/exedev/shared"]
    },
    "fetch": {
      "command": "uvx",
      "args": ["mcp-server-fetch"]
    }
  }
}
EOF

Put API keys and other secrets in ~/mcp-server.env, not this file; mcp-proxy passes that environment to every server.

The service runs mcp-proxy on port 8000:

sudo tee /etc/systemd/system/mcp-server.service >/dev/null <<'EOF'
[Unit]
Description=MCP servers (~/mcp-server/servers.json) behind mcp-proxy
After=network-online.target
Wants=network-online.target

[Service]
User=exedev
WorkingDirectory=/home/exedev/mcp-server
EnvironmentFile=/home/exedev/mcp-server.env
Environment=PATH=/home/exedev/.local/bin:/usr/local/bin:/usr/bin:/bin
ExecStart=/home/exedev/.local/bin/mcp-proxy --host 0.0.0.0 --port ${PORT} --stateless --pass-environment --named-server-config servers.json
Restart=always
RestartSec=2

[Install]
WantedBy=multi-user.target
EOF
sudo systemctl daemon-reload
sudo systemctl enable --now mcp-server

Each server is at https://my-mcp-server.exe.xyz/servers/<name>/mcp (here /servers/files/mcp and /servers/fetch/mcp). To add one, edit servers.json and restart mcp-server.

Check it#

List the tools the way exe.dev's proxy reaches the server: port 8000, addressed to $(hostname).exe.xyz. Use your server's path (with mcp-proxy, each /servers/<name>/mcp):

sleep 3
~/bin/mcp-check http://localhost:8000/mcp -H "Host: $(hostname).exe.xyz"

Expect connected: and the tools. For the starter, save a note and find it:

~/bin/mcp-check http://localhost:8000/mcp --call save_note '{"text": "set up by hand"}'
~/bin/mcp-check http://localhost:8000/mcp --call search_notes '{"query": "hand"}'

A request from another web page gets 403:

curl -s -o /dev/null -w '%{http_code}\n' -X POST http://localhost:8000/mcp \
  -H "Host: $(hostname).exe.xyz" -H 'Origin: https://example.com' \
  -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'

Back up nightly#

This script copies each SQLite database in ~/data with sqlite3 .backup (safe while the server writes) and checks the copy. It adds the rest of ~/data, the server's code and config (without .venv), and the settings files, and keeps the 14 newest backups:

cat > ~/bin/mcp-backup <<'EOF'
#!/bin/bash
# Back up ~/data, ~/mcp-server, ~/mcp-gate and their settings to
# ~/backups/mcp-<time>.tar.gz. SQLite databases are copied with .backup,
# safe while the server runs. Keeps the 14 newest.
set -euo pipefail
umask 077
work=$(mktemp -d)
trap 'rm -rf "$work"' EXIT
mkdir -p "$HOME/backups" "$work/data"
rsync -a --exclude='*.db' --exclude='*.db-wal' --exclude='*.db-shm' "$HOME/data/" "$work/data/"
for db in "$HOME"/data/*.db; do
  [ -e "$db" ] || continue
  copy="$work/data/$(basename "$db")"
  sqlite3 "$db" ".backup '$copy'"
  [ "$(sqlite3 "$copy" 'PRAGMA integrity_check')" = ok ]
done
for dir in mcp-server mcp-gate; do
  [ -d "$HOME/$dir" ] && rsync -a --exclude=.venv --exclude=node_modules --exclude=__pycache__ "$HOME/$dir" "$work/"
done
cp "$HOME"/mcp-*.env "$work/"
out="$HOME/backups/mcp-$(date -u +%Y%m%d-%H%M%S).tar.gz"
tar -czf "$out.part" -C "$work" .
mv "$out.part" "$out"
ls -1t "$HOME"/backups/mcp-*.tar.gz | tail -n +15 | xargs -r rm --
echo "$out"
EOF
chmod +x ~/bin/mcp-backup

Run it nightly, around 03:30 UTC:

sudo tee /etc/systemd/system/mcp-backup.service >/dev/null <<'EOF'
[Unit]
Description=Back up the MCP server's data, code, and settings to ~/backups

[Service]
Type=oneshot
User=exedev
ExecStart=/home/exedev/bin/mcp-backup
EOF
sudo tee /etc/systemd/system/mcp-backup.timer >/dev/null <<'EOF'
[Unit]
Description=Back up the MCP server nightly

[Timer]
OnCalendar=*-*-* 03:30:00 UTC
RandomizedDelaySec=15m
Persistent=true

[Install]
WantedBy=timers.target
EOF
sudo systemctl daemon-reload
sudo systemctl enable --now mcp-backup.timer

Make one now and check it restores, in a scratch directory:

backup=$(~/bin/mcp-backup)
rm -rf /tmp/restore-check && mkdir /tmp/restore-check
tar -xzf "$backup" -C /tmp/restore-check
ls /tmp/restore-check
for db in /tmp/restore-check/data/*.db; do [ -e "$db" ] && sqlite3 "$db" 'PRAGMA integrity_check'; done
rm -rf /tmp/restore-check

Expect data, mcp-server, and mcp-server.env, and ok for each database. Copy ~/backups off the VM now and then; otherwise the VM's disk holds the only copy.

On the VM, ~/bin/mcp-backup backs up now and prints the archive's path. Each holds data/ (SQLite as consistent copies), mcp-server/ without .venv or node_modules, mcp-gate/ if you use it, and the .env files. To copy them to your computer:

scp 'my-mcp-server.exe.xyz:backups/mcp-*.tar.gz' .

Restore#

On a new VM, first follow Set up by hand through "Check it" for the same kind of server, then copy the archive over from your computer:

scp mcp-20261023-033012.tar.gz my-mcp-server.exe.xyz:backups/

On the VM, stop the services, set the current files aside, and unpack:

backup=~/backups/mcp-20261023-033012.tar.gz
sudo systemctl stop mcp-gate 2>/dev/null; sudo systemctl stop mcp-server
stamp=$(date +%s)
mv ~/data ~/data.before-restore-$stamp
rm -rf /tmp/restore && mkdir /tmp/restore && tar -xzf "$backup" -C /tmp/restore
mv /tmp/restore/data ~/data
rsync -a /tmp/restore/mcp-server/ ~/mcp-server/
[ -d /tmp/restore/mcp-gate ] && mkdir -p ~/mcp-gate && rsync -a /tmp/restore/mcp-gate/ ~/mcp-gate/
for f in /tmp/restore/mcp-*.env; do install -m 600 "$f" ~/; done
(cd ~/mcp-server && [ -f uv.lock ] && uv sync --frozen)
(cd ~/mcp-gate 2>/dev/null && uv sync --frozen)
sudo systemctl start mcp-server
systemctl -q is-enabled mcp-gate 2>/dev/null && sudo systemctl start mcp-gate
rm -rf /tmp/restore

If the backup has mcp-gate/ but this VM never did, follow Connect claude.ai and ChatGPT from "Run it under systemd". Then check it, and delete ~/data.before-restore-* once you're happy.

On the VM:

• The starter and mcp-gate: cd ~/mcp-server && uv lock --upgrade && uv sync, likewise in ~/mcp-gate, then sudo systemctl restart mcp-server mcp-gate and check. mcp>=2.3,<3 holds you on version 2; read the release notes before raising it.
• mcp-proxy: uv tool upgrade mcp-proxy stays in the installed range; for a newer one, uv tool install --force 'mcp-proxy>=0.14,<0.15'.
• Wrapped servers: npx and uvx fetch the newest matching version each time the service starts. Pin exact versions in servers.json (server-filesystem@2.0.0, mcp-server-fetch==2026.10.19) to update only when you choose.
• Node.js: updates with apt. For a new major line, run NodeSource's setup script for it (setup_26.x), then sudo apt-get install -y nodejs.
• Ubuntu: sudo apt-get update && sudo apt-get upgrade -y.

On the VM, the logs and status of the server and mcp-gate:

journalctl -u mcp-server -n 100 --no-pager
systemctl status mcp-server --no-pager
journalctl -u mcp-gate -n 50 --no-pager

401, or an HTML login page. No valid token reached exe.dev. Check the header name (X-Exedev-Authorization), the Bearer before the token, and that the token is for this VM and unexpired. To rule out the client, run check.py on your computer with the same token.

421 Misdirected Request or "Invalid Host header". The server answers only host names it knows. The starter allows $(hostname).exe.xyz and localhost; add others (a custom domain) to ALLOWED_HOSTS in ~/mcp-server.env. For a repository's server, find its allowed-hosts setting (allowed_hosts in the Python SDK's TransportSecuritySettings, allowedHosts in TypeScript).

403 Invalid Origin header. A browser-based client sent an Origin the server doesn't trust. Desktop and command-line clients send none.

502 Bad Gateway. Nothing answers on port 8000: the service is stopped, crashed at start (see the log), or listens on 127.0.0.1 or another port. ss -ltnp | grep 800 shows what listens where.

A wrapped server's tools are missing. mcp-proxy logs each server it starts, with any error. Run the command by hand (npx -y @modelcontextprotocol/server-filesystem@2 ~/shared) to see it; curl -s localhost:8000/status lists the servers mcp-proxy knows.

claude.ai can't connect, or sign-in fails. Check that the VM is public (ssh exe.dev share show my-mcp-server) and that curl -s https://my-mcp-server.exe.xyz/.well-known/oauth-authorization-server works from your computer. "Not allowed" on the approval page means your exe.dev address isn't in ALLOWED_EMAILS. mcp-gate logs each request and its status.

Long tool calls time out. Clients give up on their own schedule (Codex at 60 seconds unless you raise tool_timeout_sec). For minutes-long work, have one tool start a job and return an id, and another report on it.