erebrus-mcp

MCP server so agents can onboard onto Erebrus: authenticate (wallet or email), create orgs, mint API keys and node registration tokens, run nodes (via install plan + registration token), provision VPN clients, and use Drop — against the public gateway API.

Transports

Transport	When to use
stdio (default)	Most agents/IDEs — Grok, Cursor, Claude Code spawn the process
HTTP (local)	Allowed — agent or tooling connects to a local MCP URL (/mcp)

Both share the same tools and session auth (wallet/email). You do not need a remote hosted MCP for agents; local stdio or local HTTP is enough. Dockerfile/compose ship the binary for packaging (stdio by default; pass --http if you want a local HTTP listener).

Not exposed: admin, leaderboard/rank/perks/social, deep firewall rule editing, billing webhooks.

Quick start (stdio — default)

# from npm (once published)
npx -y @netsepio/erebrus-mcp

# from clone
npm install && npm run build && node dist/index.js

Grok

# ~/.grok/config.toml
[mcp_servers.erebrus]
command = "npx"
args = ["-y", "@netsepio/erebrus-mcp"]
env = { EREBRUS_GATEWAY_URL = "https://gateway.erebrus.io" }

Or pin a local build:

[mcp_servers.erebrus]
command = "node"
args = ["/absolute/path/to/erebrus-mcp/dist/index.js"]
env = { EREBRUS_GATEWAY_URL = "https://gateway.erebrus.io" }

Cursor / Claude Code

{
  "mcpServers": {
    "erebrus": {
      "command": "npx",
      "args": ["-y", "@netsepio/erebrus-mcp"],
      "env": {
        "EREBRUS_GATEWAY_URL": "https://gateway.erebrus.io"
      }
    }
  }
}

Agents authenticate with tools (wallet or email). No env token required for interactive use.

Local HTTP (optional)

Agents may run the MCP as a local HTTP server and connect with a URL transport:

# from clone
npm run build
node dist/index.js --http
# or: MCP_TRANSPORT=http MCP_PORT=3100 node dist/index.js

# Docker image, HTTP mode
docker run --rm -p 3100:3100 \
  -e EREBRUS_GATEWAY_URL=https://gateway.erebrus.io \
  ghcr.io/netsepio/erebrus-mcp:latest \
  --http

• Endpoint: http://127.0.0.1:3100/mcp
• Health: http://127.0.0.1:3100/healthz
• Optional gate: MCP_AUTH_TOKEN → clients send Authorization: Bearer <token>

Example Grok remote-style config against localhost:

[mcp_servers.erebrus_http]
url = "http://127.0.0.1:3100/mcp"
# headers = { Authorization = "Bearer <MCP_AUTH_TOKEN>" }  # if set

Session auth to the Erebrus gateway is still via wallet/email tools (or optional EREBRUS_BEARER_TOKEN). MCP_AUTH_TOKEN only locks the local MCP HTTP door if you set it.

Optional env (see .env.example):

Env	Use
EREBRUS_GATEWAY_URL	Gateway base (default https://gateway.erebrus.io)
EREBRUS_BEARER_TOKEN	Optional pre-seeded user PASETO (CI/operators only)
EREBRUS_API_KEY	Org API key — today only /api/v2/org/* (VPN clients + usage)
EREBRUS_DEFAULT_ORG_ID	Default org_id when tools omit it

Auth model

Agents log in via tools, not a pre-shared MCP secret:

Flow	Tools
Wallet	auth_wallet_challenge → sign message → auth_wallet_complete
Email OTP	auth_email_login_start → read code → auth_email_login_verify
Import	auth_import_token (existing PASETO)
Status	auth_status, auth_methods, auth_logout

Successful login stores a user PASETO in the MCP session for that process.
EREBRUS_BEARER_TOKEN is an optional env fallback only.

Credential	Source	Use
Session PASETO	auth tools	Orgs, keys, node tokens, VPN, Drop
Env PASETO	EREBRUS_BEARER_TOKEN	Fallback if no session login
Org API key	EREBRUS_API_KEY	/api/v2/org/* only (VPN/usage) until gateway expands scopes

Agent responsibilities outside MCP: wallet signing or reading email OTP; choosing a VPS and running the install command from node_install_plan with the registration token.

Tool map

Session / health

gateway_health, whoami, auth_*

Orgs & keys

org_create, org_list, org_get, org_entitlements, apikey_create, apikey_list, apikey_revoke

Nodes

node_registration_token_create, org_nodes_list, org_node_get, operator_nodes_list, nodes_directory, node_install_plan

VPN

vpn_client_list, vpn_client_create, vpn_client_get_config, vpn_client_delete, org_vpn_client_create, org_vpn_client_list, org_usage

Drop

drop_nodes_list, drop_upload_reserve, drop_upload_content, drop_upload_status, drop_files_list, drop_file_get, drop_file_delete, drop_usage, org_drop_files, org_drop_usage

Suggested agent flow

1. auth_methods → wallet or email login tools
2. whoami → org_create / org_list
3. Optional apikey_create (store secret offline)
4. node_registration_token_create → node_install_plan → run installer on the agent’s chosen VPS
5. vpn_client_create + vpn_client_get_config
6. Drop: drop_nodes_list → reserve → upload content

Develop

npm install
npm run typecheck
npm run build
npm run dev              # stdio
node dist/index.js --http  # local HTTP on :3100

Requirements: Node.js ≥ 20.

Docker image

CI publishes ghcr.io/netsepio/erebrus-mcp (GHCR). Default entrypoint is stdio; pass --http for a local HTTP listener.

docker pull ghcr.io/netsepio/erebrus-mcp:latest

# stdio (attach stdin/stdout)
docker run --rm -i \
  -e EREBRUS_GATEWAY_URL=https://gateway.erebrus.io \
  ghcr.io/netsepio/erebrus-mcp:latest

# local HTTP
docker run --rm -p 3100:3100 \
  -e EREBRUS_GATEWAY_URL=https://gateway.erebrus.io \
  ghcr.io/netsepio/erebrus-mcp:latest \
  --http

Security

• HTTP client path allowlist blocks admin/rank/social/firewall-rules/referrals.
• One-time secrets (api_key, ere_reg_*, PASETO) — store offline; avoid chat logs.
• Drop upload via MCP is capped at ~15MB base64 payload.
• Do not commit .env or long-lived tokens.

CI

• CI — typecheck + build on push/PR to main
• Docker — build/push ghcr.io/netsepio/erebrus-mcp on main and version tags
• npm — publish @netsepio/erebrus-mcp on v* tags when NPM_TOKEN is set

License

MIT (see LICENSE).