Do I need an API key to use the hosted MCP server?

No. Point Claude or Cursor at https://directmailamerica.com/api/mcp with no Authorization header. get_pricing and start_account_login work unauthenticated. send_letter and create_credit_checkout work as a guest: pay with x402 (USDC) or open a Square checkout. A key is required for job status, credit balance, and most follow-up tools.

Will a staging key actually mail?

No. lbl_test_ keys never purchase postage. Guest environment=staging mints a test key and dry-runs fulfillment. Production keys (lbl_live_) mail on this live deployment.

Can the MCP server take a credit card number?

No. create_credit_checkout returns a Square Payment Link. The human pays on Square. Then get_payment_status adds credits. Never send PAN or CVV to MCP.

MCP

Hosted MCP

Production path: JSON-RPC POST to https://directmailamerica.com/api/mcp. A lbl_ key is optional. Staging keys (lbl_test_) never purchase postage.

Discovery: /.well-known/mcp.json. Same prices as the pricing guide.

Quick start

01
Add the hosted server
In Claude or Cursor, set the MCP URL to https://directmailamerica.com/api/mcp. A Bearer lbl_ key is optional. Leave headers empty to try guest x402.
02
Quote a piece
Call get_pricing with mailClass and pageCount. No API key required. Optional couponCode applies a server-validated discount to the quoted cents.
03
Send
Call send_letter with from, recipients, and body or pdfBase64. Without a key, settle the x402 PAYMENT-REQUIRED challenge in USDC (Base or Solana) and retry. With a key, spend credits or pay per send the same way.

Tools

MCP tools, authentication, and payment rails
Tool	Auth	Payment
send_letter	Optional	Guest x402, org credits, or pay-per-send
get_letter_status	Bearer key	—
list_jobs	Bearer key	—
get_pricing	None	—
get_credits	Bearer key	—
purchase_credits	Bearer key	x402 USDC top-up
create_credit_checkout	Optional	Square Payment Link (no PAN)
get_payment_status	Bearer key	Completes Square checkout
start_account_login	None	—

Full tool descriptions live in llms-full.txt and the discovery manifest.

Payment rails

MCP is not credits-only. Agents can mail with any of:

01
Guest checkout + x402
No prior account or API key. Pay per send with USDC on Base or Solana. An ephemeral org is created on settle. No credit card required.
02
Account auth
start_account_login returns the web sign-in URL (email / Google / X). Mint a lbl_ key, then use credits and/or pay-per-send.
03
Credits
Prepaid org balance on send_letter. Top up with purchase_credits (x402) or a Square card checkout.
04
Credit cards
create_credit_checkout returns a Square Payment Link. Never send PAN/CVV to MCP. After the human pays, get_payment_status adds credits.

Live stables (same accepts[] as REST POST /api/v1/letters): USDC on Base (eip155:8453) and USDC on Solana. Other stables are not advertised until they are live on that list.

Guest x402 end-to-end

Guest send_letter

1. tools/call send_letter  { from, recipients, body }   // no Authorization
2. HTTP 402 + header PAYMENT-REQUIRED
   Tool result: error=payment_required, accepts[], paymentRequiredHeader
   Live stables: USDC on Base (eip155:8453), USDC on Solana
3. Sign EIP-3009 transferWithAuthorization (or Solana exact payload)
4. tools/call send_letter  same args + paymentSignature
   (or retry with HTTP PAYMENT-SIGNATURE — same rail as POST /api/v1/letters)
5. Job created. guestApiKey shown once — use it for get_letter_status.

Coupons

Optional couponCode on send_letter and get_pricing (same field on REST POST /api/v1/letters and GET /api/v1/pricing). Codes are normalized like PhotoMatchFun: trim, strip interior whitespace, case-insensitive. The catalog is server-validated; it changes the charged or quoted cents and the x402 PAYMENT-REQUIRED amount. It does not change LetterStream postage behavior.

couponCode

send_letter / get_pricing accept optional couponCode (case-insensitive).
Server catalog only — clients never send a percent.

COUPONFORRIGEL → 99% off list. First-Class page 1 ($1.49) quotes ~$0.01.
Unknown codes → invalid_coupon (MCP tool error / REST HTTP 400), not a full-price 402.
Omit couponCode → unchanged full-list guest x402.
Staging / lbl_test_ still never buy postage; coupon only changes charged cents.

Hosted HTTP (recommended)

JSON-RPC POST to https://directmailamerica.com/api/mcp. Bearer key is optional for get_pricing, start_account_login, and guest send_letter / create_credit_checkout.

Guest · no API key

{
  "mcpServers": {
    "directmailamerica": {
      "url": "https://directmailamerica.com/api/mcp"
    }
  }
}

Cursor / Claude · production key

{
  "mcpServers": {
    "directmailamerica": {
      "url": "https://directmailamerica.com/api/mcp",
      "headers": {
        "Authorization": "Bearer lbl_live_your_key"
      }
    }
  }
}

Same host · staging sandbox key

{
  "mcpServers": {
    "directmailamerica": {
      "url": "https://directmailamerica.com/api/mcp",
      "headers": {
        "Authorization": "Bearer lbl_test_your_key"
      }
    }
  }
}

Questions

Do I need an API key to use the hosted MCP server?: No. Point Claude or Cursor at https://directmailamerica.com/api/mcp with no Authorization header. get_pricing and start_account_login work unauthenticated. send_letter and create_credit_checkout work as a guest: pay with x402 (USDC) or open a Square checkout. A key is required for job status, credit balance, and most follow-up tools.
Will a staging key actually mail?: No. lbl_test_ keys never purchase postage. Guest environment=staging mints a test key and dry-runs fulfillment. Production keys (lbl_live_) mail on this live deployment.
Can the MCP server take a credit card number?: No. create_credit_checkout returns a Square Payment Link. The human pays on Square. Then get_payment_status adds credits. Never send PAN or CVV to MCP.

Local development only

stdio helper

scripts/mcp-server.mjs is a local stdio bridge for developing against a checkout on 127.0.0.1. It is not the production integration path. Leave DIRECTMAILAMERICA_API_KEY unset to exercise guest x402. Keys you do set still start with lbl_.

Clone github.com/blockrushusa/lettersbyletter
Run npm install and npm run dev (listens on port 43127)
Create a lbl_test_ key in the local Developers page — or omit the key for guest x402
Optionally run npm run mcp, or point your client at the script as below

Cursor · local stdio

{
  "mcpServers": {
    "directmailamerica": {
      "command": "node",
      "args": ["./scripts/mcp-server.mjs"],
      "env": {
        "DIRECTMAILAMERICA_API_URL": "http://127.0.0.1:43127",
        "DIRECTMAILAMERICA_API_KEY": "lbl_test_your_key"
      }
    }
  }
}

Claude Desktop: place this in claude_desktop_config.json.

claude_desktop_config.json · local

{
  "mcpServers": {
    "directmailamerica": {
      "command": "node",
      "args": ["/absolute/path/to/directmailamerica/scripts/mcp-server.mjs"],
      "env": {
        "DIRECTMAILAMERICA_API_URL": "http://127.0.0.1:43127",
        "DIRECTMAILAMERICA_API_KEY": "lbl_test_your_key"
      }
    }
  }
}

Hosted MCP

Quick start

Add the hosted server

Quote a piece

Send