Remote MCP over HTTP, with a policy-aware Go sidecar on Morph Cloud.
This repository is a small, end-to-end reference: provision a VM, route three MCP backends through one sidecar, expose authenticated URLs, and ship ready-made client configs. The sidecar enforces YAML policy, writes redacted audit lines, and is covered by the same quality gates you would expect in a production service.
At a glance
Why this exists
Building remote MCP access is more than exposing a port: you need predictable auth boundaries, a single place to enforce rules, and logs you can trust. This demo keeps the provisioning story in Python (fast iteration) and the dataplane in Go (simple, explicit HTTP handling). Policy and config are validated at startup so the process does not run half-configured.
Documentation in this repo: this file is the main guide. Contributor expectations are in CONTRIBUTING.md.
Architecture
flowchart LR
mcpClient[MCPClient] --> supergateway[Supergateway]
supergateway --> morphEdge[MorphEdgeAuth]
morphEdge --> sidecar[GoSidecar]
sidecar --> policy[PolicyYAML]
sidecar --> audit[AuditJSONL]
sidecar --> metrics[MetricsEndpoint]
sidecar --> fsServer[MCPFilesystem]
sidecar --> gitServer[MCPGit]
sidecar --> httpServer[MCPHTTP]
setupPipeline[SetupPipeline] --> sidecar
Clients speak MCP over stdio; supergateway bridges to SSE URLs. Morph terminates API-key auth at the edge. The sidecar applies policy, proxies to the right local MCP port, and records decisions.
Repository map
After make setup, you will have instance_info.json (ignored by git) and refreshed files under clients/.
Quickstart
make install-deps
export MORPH_API_KEY="your-api-key"
make setup
make test
End-to-end shortcut (install deps, setup, then smoke test):
make demo
Outputs:
instance_info.json— instance id and Morph base URLsclients/cursor.jsonandclients/claude-desktop.json—supergatewaywiring for each route
HTTP surface (sidecar)
Inside the VM the sidecar listens on port 8080. Morph publishes each service at its own base URL; paths are appended to that base (see smoke_test.py).
Quick manual checks
After make setup, you can probe the first exposed base URL (see instance_info.json):
BASE="$(python -c "import json; print(json.load(open('instance_info.json'))['urls']['mcp1'])")"
curl -fsS -H "Authorization: Bearer $MORPH_API_KEY" "$BASE/health"
curl -fsS -H "Authorization: Bearer $MORPH_API_KEY" "$BASE/ready"
SSE endpoints may keep the connection open; interrupt with Ctrl+C when you are done.
Security and policy
- Edge: Morph
auth_mode="api_key"on exposed HTTP services. - Sidecar (optional): bearer checks via
auth.*in sidecar/config.yaml. - Authorization:
defaultrole, epochs, tools, andcallpermission in sidecar/policy.yaml. - Audit: JSONL on the VM at
/opt/sidecar/permits.jsonl; bearer material is never written verbatim.
Config path: set SIDECAR_CONFIG (for example /opt/sidecar/config.yaml on the VM), otherwise ./config.yaml from the process working directory.
Startup guarantees
The sidecar exits on invalid config or policy instead of running in an undefined state. Examples include missing policy.file, bad durations, bad upstream URLs, invalid RFC3339 epoch expiry, a missing default role, or epoch names that do not exist.
If policy.reload_interval is set, policy is reloaded on that schedule without restarting the process.
Develop and verify
make ci
Runs Ruff, mypy on selected modules, pytest, and go test under sidecar/. Optional race detection (toolchain-dependent):
make race
Day-two commands
make status
make logs
make epoch-rotate
make clean
make logs uses your saved instance id and Morph credentials to print recent sidecar and permit log tails.
Requirements
On Windows, use Git Bash, WSL, or another environment that provides make and a POSIX shell, or invoke the same Python entrypoints as in the Makefile.
Troubleshooting
Contributing
See CONTRIBUTING.md.
License
Released under the MIT License. See LICENSE.