Phone MCP Server

Standalone MCP adapter for lnvpn-web-app/app/api/v2/phone/*.

This service is additive only: it does not change existing phone API routes or behavior.

What It Exposes

Tools mapped 1:1 to your existing API:

• phone.purchase.start -> POST /api/v2/phone/purchase
• phone.purchase.complete -> POST /api/v2/phone/complete
• phone.renew.start -> POST /api/v2/phone/renew
• phone.renew.complete -> POST /api/v2/phone/renew/complete
• phone.numbers.list -> GET /api/v2/phone/numbers
• phone.messages.list -> GET /api/v2/phone/messages/{phoneNumber}

Security Model

By default, the server runs in hmac mode (MCP_AUTH_MODE=hmac).

Each request to /mcp must include:

• X-Client-Id
• X-Timestamp (unix ms)
• X-Nonce (UUID recommended)
• X-Body-SHA256 (sha256 hex of stable JSON body)
• X-Signature (v1=<hex_hmac>)

Canonical signing string:

{METHOD}\n{PATH}\n{X-Timestamp}\n{X-Nonce}\n{X-Body-SHA256}

Signature:

hex(HMAC_SHA256(canonical, client_secret))

Controls:

• timestamp skew protection (HMAC_ALLOWED_SKEW_MS)
• one-time nonce replay protection (Redis recommended)
• per-client rate limit
• per-client allowed tool list

If you want a fully open endpoint, set MCP_AUTH_MODE=open. In open mode, MCP client auth is disabled and requests are accepted without HMAC headers.

Configuration

Create a .env file in the project root and set real values. The server auto-loads .env at startup.

Important variables:

• MCP_AUTH_MODE: hmac or open
• MCP_CLIENTS_JSON: required in hmac mode

MCP_CLIENTS_JSON format:

{
  "agentA": {
    "secret": "replace-with-long-random-secret",
    "allowedTools": [
      "phone.purchase.start",
      "phone.purchase.complete",
      "phone.renew.start",
      "phone.renew.complete",
      "phone.numbers.list",
      "phone.messages.list"
    ],
    "rateLimitPerMinute": 120
  }
}

Run

npm install
npm run dev

Build + production:

npm run build
npm run start

Deploy

• PM2 config template: ecosystem.config.cjs
• Nginx template: nginx.phone-mcp.conf.example

Suggested edge:

Cloudflare -> Nginx -> phone-mcp (PM2) -> existing phone API