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=`)

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`