Fax MCP Server

Send faxes from Claude, ChatGPT, and other AI agents over the Model Context Protocol

Not using AI agents? See our Fax REST API for traditional HTTP/JSON integration.
Contents
  1. Overview
  2. Quick Start
  3. Connection Details
  4. Authentication
  5. Available Tools
  6. Examples
  7. Client Setup
  8. Error Codes
  9. Supported File Formats

1. Overview

The GotFreeFax MCP Server implements the Model Context Protocol so AI agents like Claude and ChatGPT can discover and use fax-sending tools directly. Once configured, simply ask your AI to “send a fax” — it handles the rest.

Base URL: https://www.gotfreefax.com

No account is required to try the free tools (send_free_fax, check_fax_status, list_supported_formats, purchase_credits). Authenticated tools (send_fax, list_sent_faxes, get_account_balance) require a GotFreeFax prepaid account — you can buy one through purchase_credits without leaving your AI client.

2. Quick Start (Claude Desktop, free, no account)

Add this to your claude_desktop_config.json and restart Claude Desktop:

{
  "mcpServers": {
    "gotfreefax": {
      "command": "npx",
      "args": ["mcp-remote", "https://www.gotfreefax.com/mcp"]
    }
  }
}

Then ask Claude something like: “Send a free fax to 555-123-4567 with the text ‘Hello from Claude’.”

Claude will call send_free_fax, you’ll receive a confirmation link by email, and the fax sends once you click it. To unlock authenticated tools or use a different AI client, see Client Setup below.

Requires Node.js installed locally — the mcp-remote package bridges Claude Desktop to the remote MCP endpoint.

3. Connection Details

POST /mcp Auth Required (for most tools)
Endpointhttps://www.gotfreefax.com/mcp
TransportStreamable HTTP (JSON-RPC 2.0 over POST)
Protocol Version2024-11-05
Content-Typeapplication/json
AuthenticationAuthorization: Bearer <token>

4. Authentication

The MCP Server uses Bearer token authentication. The token is your account number and PIN encoded in Base64.

Creating Your Token

Combine your account number and PIN with a colon separator, then Base64-encode the result:

Token = base64("ACCOUNT_NUMBER:PIN")

Example:
  Account Number: 1234567890
  PIN: 5678
  Combined: 1234567890:5678
  Base64 Token: MTIzNDU2Nzg5MDo1Njc4

Using the Token

Include the token in the Authorization header of every JSON-RPC request:

Authorization: Bearer MTIzNDU2Nzg5MDo1Njc4

5. Available Tools

ToolDescriptionAuth
send_faxSend a fax with file attachments (up to 10 files)Yes
check_fax_statusCheck delivery status of a fax by job_idNo
list_sent_faxesList faxes previously sent by the authenticated account (paginated, most recent first)Yes
get_account_balanceGet page and dollar balance for the authenticated accountYes
purchase_creditsStart a prepaid credit purchase. Returns a PayPal payment URL. Authenticated → credits land on your account; unauthenticated → creates a new prepaid account (or loads an existing one matched by email).Optional
send_free_faxSend a free fax (max 3 pages, 2 per email/IP per day). The sender must click a confirmation link emailed to sender_email before the fax actually sends. If the document exceeds the page limit, the response suggests using purchase_credits.No
list_supported_formatsList accepted file typesNo

6. Examples

Initialize Session

curl -X POST https://www.gotfreefax.com/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer MTIzNDU2Nzg5MDo1Njc4" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": { "name": "my-agent", "version": "1.0" }
    }
  }'

// Response:
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": { "tools": {} },
    "serverInfo": { "name": "GotFreeFax", "version": "1.0.0" }
  }
}

List Tools

curl -X POST https://www.gotfreefax.com/mcp \
  -H "Content-Type: application/json" \
  -d '{ "jsonrpc": "2.0", "id": 2, "method": "tools/list" }'

Send a Fax

curl -X POST https://www.gotfreefax.com/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer MTIzNDU2Nzg5MDo1Njc4" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "send_fax",
      "arguments": {
        "fax_number": "8885551234",
        "files": [
          {
            "filename": "letter.pdf",
            "content": "JVBERi0xLjQK..."
          }
        ]
      }
    }
  }'

// Response:
{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\n  \"status\": \"success\",\n  \"job_id\": \"ABCDEFGHIJ\",\n  \"message\": \"Fax queued successfully to 8885551234\"\n}"
      }
    ],
    "isError": false
  }
}

List Sent Faxes

curl -X POST https://www.gotfreefax.com/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer MTIzNDU2Nzg5MDo1Njc4" \
  -d '{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "tools/call",
    "params": {
      "name": "list_sent_faxes",
      "arguments": { "limit": 20, "offset": 0 }
    }
  }'

// Result content text (JSON):
{
  "total_count": 42,
  "limit": 20,
  "offset": 0,
  "faxes": [
    {
      "job_id": "ABCDEFGHIJ",
      "fax_number": "8885551234",
      "status": "success",
      "page_count": 2,
      "service_type": "PrepaidAccount",
      "created_at": "2025-01-15T10:00:00Z",
      "completed_at": "2025-01-15T10:30:00Z",
      "detail": ""
    }
  ]
}

Includes all paid faxes (prepaid + pay-per-fax + international) tied to the account, ordered most recent first. Free anonymous sends are not included. Default limit is 20, max 100.

Purchase Credits (authenticated)

curl -X POST https://www.gotfreefax.com/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer MTIzNDU2Nzg5MDo1Njc4" \
  -d '{
    "jsonrpc": "2.0",
    "id": 5,
    "method": "tools/call",
    "params": {
      "name": "purchase_credits",
      "arguments": { "service_type": "prepaid20" }
    }
  }'

// Result content text (JSON):
{
  "status": "success",
  "order_number": "ABCDEFGHIJ",
  "payment_url": "https://www.gotfreefax.com/paypal/payment.aspx/ABCDEFGHIJ",
  "service_type": "prepaid20",
  "amount": 19.95,
  "page_credit": 250,
  "currency": "USD",
  "new_account": false,
  "message": "Visit the payment URL to complete your purchase. Credits will be added to your authenticated account after payment."
}

Purchase Credits (new account)

curl -X POST https://www.gotfreefax.com/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 6,
    "method": "tools/call",
    "params": {
      "name": "purchase_credits",
      "arguments": {
        "service_type": "prepaid10",
        "email": "alice@example.com",
        "name": "Alice"
      }
    }
  }'

// Result content text (JSON):
{
  "status": "success",
  "order_number": "KLMNOPQRST",
  "payment_url": "https://www.gotfreefax.com/paypal/payment.aspx/KLMNOPQRST",
  "service_type": "prepaid10",
  "amount": 9.95,
  "page_credit": 100,
  "currency": "USD",
  "new_account": true,
  "message": "Visit the payment URL to complete your purchase. Your account number and PIN will be emailed to alice@example.com after payment."
}

Available service_type values: prepaid10 (100 pages, $9.95), prepaid20 (250 pages, $19.95), prepaid50 (800 pages, $49.95), intprepaid50 ($49.95 international balance), intprepaid100 ($99.95), intprepaid200 ($199.95). The payment URL is shareable — the user opens it in any browser to complete payment via PayPal. For unauthenticated purchases, the account email is the unique key: if the email already exists, credits are loaded onto that account; if not, a new account is created and the credentials are emailed after payment.

Send Free Fax

curl -X POST https://www.gotfreefax.com/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 7,
    "method": "tools/call",
    "params": {
      "name": "send_free_fax",
      "arguments": {
        "fax_number": "8885551234",
        "sender_name": "Alice",
        "sender_email": "alice@example.com",
        "receiver_name": "Bob",
        "text": "Hello Bob, this is a free fax."
      }
    }
  }'

// Happy-path result content text (JSON):
{
  "status": "confirmation_required",
  "job_id": "ABCDEFGHIJ",
  "sender_email": "alice@example.com",
  "page_count": 1,
  "message": "An email was sent to alice@example.com with a confirmation link. The fax will not actually send until the user clicks that link. Use check_fax_status with the returned job_id to track progress."
}

// Page-limit-exceeded result (isError: true):
{
  "status": "page_limit_exceeded",
  "page_count": 7,
  "free_limit": 3,
  "suggestion": "Free faxes are limited to 3 pages... To send a fax this size, call purchase_credits with service_type \"prepaid10\"...",
  "next_tool": "purchase_credits"
}

Free fax requires no authentication, but the sender must complete an email click-confirmation step before the fax is actually queued. Limits: 3 pages total across text and files, 3 files max, and 2 sends per email and 2 per IP per day. The daily limit is enforced at confirmation-click time (matching the web flow) — submission always succeeds, but a fax may still be rejected when the user clicks the email link if the daily quota has been reached by then. The agent can detect that by calling check_fax_status with the returned job_id after the user reports clicking. If the user needs to send a larger fax or beyond the daily limit, suggest purchase_credits to set up a prepaid account.

7. Client Setup

The Quick Start above gets you running in Claude Desktop without an account. This section covers the full credentialed setup for Claude, integrations with other MCP-aware clients, and notes for any client that can speak JSON-RPC over HTTP.

Claude Desktop

Two configurations depending on what you need.

Option A — No credentials (free tools only)

You can send a free fax, check fax status, list supported formats, and start a prepaid purchase. The authenticated tools (send_fax, list_sent_faxes, get_account_balance) will return an authentication error, but everything else works. Same config as the Quick Start above:

{
  "mcpServers": {
    "gotfreefax": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://www.gotfreefax.com/mcp"
      ]
    }
  }
}

Option B — With credentials (full access)

Use this once you have a prepaid account (account number + PIN). Compute the bearer token as "Bearer " + base64(account_number + ":" + pin) and put it in the env block:

{
  "mcpServers": {
    "gotfreefax": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://www.gotfreefax.com/mcp",
        "--header",
        "Authorization:${GOTFREEFAX_AUTH}"
      ],
      "env": {
        "GOTFREEFAX_AUTH": "Bearer YOUR_BASE64_TOKEN"
      }
    }
  }
}

Both configurations require Node.js installed. The mcp-remote package bridges Claude Desktop to the remote MCP endpoint. To upgrade from Option A to Option B after purchase, edit the JSON, restart Claude Desktop, and the authenticated tools become available — no other changes needed.

Codex CLI (OpenAI)

Add to ~/.codex/config.toml:

[mcp_servers.gotfreefax]
command = "npx"
args = ["mcp-remote", "https://www.gotfreefax.com/mcp"]

# To unlock authenticated tools, add the env block and a --header arg:
# args = [
#   "mcp-remote",
#   "https://www.gotfreefax.com/mcp",
#   "--header", "Authorization:${GOTFREEFAX_AUTH}"
# ]
# [mcp_servers.gotfreefax.env]
# GOTFREEFAX_AUTH = "Bearer YOUR_BASE64_TOKEN"

Same Node.js + mcp-remote bridge as Claude Desktop. After editing the TOML, restart your Codex session.

ChatGPT

ChatGPT’s MCP support is being rolled out across surfaces and the exact setup path is changing month to month. As of June 2026 the most reliable integration is through the ChatGPT desktop app’s connector / MCP settings (the chatgpt.com web UI uses an OAuth-based Connectors mechanism configured in your account settings, not via JSON files).

Use OpenAI’s current documentation for the exact UI steps. The values you’ll need are:

  • Endpoint: https://www.gotfreefax.com/mcp
  • Authentication (for paid tools): Bearer token, format "Bearer " + base64(account_number + ":" + pin)
  • Transport: Streamable HTTP (JSON-RPC 2.0 over POST)

Other MCP clients (Cursor, Windsurf, custom)

Any client that speaks MCP over HTTP can connect to https://www.gotfreefax.com/mcp. Editor integrations (Cursor, Windsurf) typically have an MCP server entry in settings; use the same JSON shape as Claude Desktop. For custom clients writing raw JSON-RPC, see Examples — every transport is just POST /mcp with a JSON-RPC envelope, optionally an Authorization: Bearer ... header for the authenticated tools.

8. Error Codes

The MCP Server uses standard JSON-RPC 2.0 error codes:

CodeDescription
-32700Parse error (malformed JSON)
-32600Invalid request (missing method)
-32601Method or tool not found
-32602Invalid parameters

Tool-specific errors (authentication failure, invalid fax number, insufficient balance, etc.) are returned as a successful JSON-RPC response with isError: true in the result content.

9. Supported File Formats & Limits

Maximum 10 files per fax request.

FormatExtensions
Adobe PDFpdf
Microsoft Worddoc, docx
JPEG Imagejpg, jpeg
Plain Texttxt
Prefer a traditional REST API? Our Fax REST API v2 exposes the same capabilities over JSON-over-HTTPS.

Need help? Contact us at gotfreefax.com/contact.

Free Fax Number - Free Fax Cover Sheet - Online Fax Tips - Free Fax Review - International Fax - Resume Builder
©2026 GotFreeFax.com - Terms of Service - Privacy Policy - Testimonials - FAQ - Contact Us