# SingleFax — Agent Integration Guide

SingleFax is a pay-per-fax service. Sending starts at **$0.99** for the first
10 billable pages, then about **+$0.08/page** (cap 50). Destinations Telnyx
supports. HIPAA/PHI is **not** available on MCP, MPP, or the public API —
use the website HIPAA Secure path with an electronic BAA.

Human docs + one-click install buttons: https://singlefax.com/agents

Pick a surface:

| Client | Auth | Pay | Entry |
| --- | --- | --- | --- |
| Cursor, Claude, Codex, ChatGPT, VS Code | MCP OAuth | Hosted Checkout, or subscription page pool | `https://singlefax.com/mcp` |
| Backend / scripts | API key `sf_live_…` | Prepaid credits | `POST /api/v1/faxes` |
| Autonomous agents with a Stripe SPT | none | MPP HTTP 402 → retry | `POST /api/v1/machine/faxes` |

Cursor **cannot** mint a Shared Payment Token by itself. Chat MCP should use
`create_fax_draft`. To pay MPP from a Cursor/Claude Code/Codex terminal, use
Stripe Link CLI against the **REST** machine URL (not `/mcp`). See `/mpp.md`.

## 1. MCP server (chat apps)

```
https://singlefax.com/mcp
```

Streamable HTTP, OAuth 2.1 (PKCE + DCR). Discovery:

- `/.well-known/oauth-authorization-server`
- `/.well-known/oauth-protected-resource`

Unauthenticated `POST /mcp` returns `401` + `WWW-Authenticate`.

### One-click / copy-paste install

**Cursor** — click Add to Cursor on `/agents`, or `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "singlefax": {
      "url": "https://singlefax.com/mcp"
    }
  }
}
```

Deeplink shape: `cursor://anysphere.cursor-deeplink/mcp/install?name=singlefax&config=` + base64(`{"url":"https://singlefax.com/mcp"}`).

**Claude Code**

```bash
claude mcp add --transport http singlefax https://singlefax.com/mcp
```

Then `/mcp` in the session to finish OAuth. Claude.ai: Customize → Connectors →
custom connector with the same URL (no install deeplink).

**Codex** (CLI, IDE, ChatGPT desktop share `~/.codex/config.toml`)

```bash
codex mcp add singlefax --url https://singlefax.com/mcp
codex mcp login singlefax
```

```toml
[mcp_servers.singlefax]
url = "https://singlefax.com/mcp"
```

**ChatGPT** — Developer mode → Connectors / Plugins → custom connector,
OAuth, URL `https://singlefax.com/mcp`. Enable the connector in the chat.

**VS Code / Copilot** — `.vscode/mcp.json`:

```json
{
  "servers": {
    "singlefax": {
      "type": "http",
      "url": "https://singlefax.com/mcp"
    }
  }
}
```

### Tools

| Tool | Description |
| --- | --- |
| `create_upload` | Short-lived upload capability; PUT the PDF bytes |
| `create_fax_draft` | Quote + draft. Returns `checkoutUrl` unless the OAuth user has remaining subscription pages — then it queues the send |
| `get_fax_status` | Poll an order you own |
| `get_credits` | Prepaid credit balance |
| `create_machine_fax` | Returns MPP challenge **JSON** (not HTTP 402). Only useful if the client can pass `payment_authorization`. Link CLI should hit REST instead |

Example prompt: `Send this PDF as a fax to +1-415-555-2671 using SingleFax.`

## 2. REST API + prepaid credits

Create a scoped API key at `/dashboard/api-keys`, prepay credits, then:

```
POST /api/v1/uploads
POST /api/v1/faxes          # Bearer, scope fax:send, Idempotency-Key
GET  /api/v1/faxes
GET  /api/v1/faxes/{id}
GET  /api/v1/credits
POST /api/v1/credits/checkout
```

Spec: `/openapi.json`.

## 3. Machine Payment Protocol (MPP)

Fully autonomous, no API key. HTTP 402 + Stripe Shared Payment Token via `mppx`.

```
POST /api/v1/machine/faxes
```

Without `Authorization: Payment …` → `402` + `WWW-Authenticate`. Retry with the
credential. Requires `NUXT_STRIPE_PROFILE_ID` or the endpoint `503`s.

**Cursor / Claude Code / Codex:** install Link CLI (`npx skills add stripe/link-cli`
or `npx @stripe/link-cli --mcp`), `auth login`, then:

```bash
npx @stripe/link-cli mpp pay https://singlefax.com/api/v1/machine/faxes \
  -X POST \
  -d '{"to":"+14155552671","base64":"<pdf>","request_id":"mpp-1"}' \
  --context "Send a fax via SingleFax after the user asked this agent to pay."
```

Use a real E.164 destination (not `+1555…`) and real PDF base64. Approve the
spend in the Link app. Do **not** point `mpp pay` at `/mcp`.

Details: `/mpp.md`.

## 4. Agent Auth

Delegated capabilities after device approval. Discovery:
`/.well-known/agent-configuration`. Prefer MCP or API keys for most clients.

## Constraints

- PDF / common office formats only — see `/openapi.json` for MIME types.
- Fax numbers must be valid E.164.
- Credits reserve on submit and commit on Telnyx delivery; failed send releases.
- Do not log fax numbers, emails, filenames, or document contents.
- Do not invent HIPAA claims for these surfaces.