Fax MCP Server

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

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: Send Your First Free Fax

No GotFreeFax account is required. Connect your AI app using this server URL:

https://www.gotfreefax.com/mcp
  1. Choose your app. Follow its setup instructions below for the free tools.
  2. Ask to send a fax. For example: “Send a free fax to [recipient’s fax number] with the text ‘Hello!’.” Provide your name and email when asked.
  3. Confirm by email. Open the confirmation link we send you. Your fax sends after you click it.

Free faxes can contain up to 3 pages and go to US or Canadian numbers.

Already have a prepaid account? Sign in to My Account, choose your app, and copy its setup instructions.

3. Client Setup

Choose your app below. For free faxing, follow its instructions without an account token. To use a prepaid balance, sign in to My Account and copy the setup for your app, or replace YOUR_TOKEN below with your token.

Anyone with the token can spend your balance, so keep it out of config files you commit or share; the Codex, Cursor and VS Code sections show how. Already connected for the free tools? Follow your app’s instructions to update the existing GotFreeFax connection.

AppFree toolsAccount tools
Claude (claude.ai, Claude Desktop, mobile)Yes, paste the URLWith request headers (beta), or Claude Desktop with Node.js
ChatGPTYes, paste the URLNot yet (OAuth only)
Claude CodeYesYes, add the header
CodexYesYes, add the header
CursorYesYes, add the header
VS CodeYesYes, add the header

Claude (claude.ai, Claude Desktop, mobile)

  1. Go to Customize → Connectors, click + Add, then Add custom connector. Team and Enterprise admins add it under Organization settings → Connectors.
  2. Enter a name (for example GotFreeFax) and the URL https://www.gotfreefax.com/mcp.
  3. For the free tools, choose No sign-in and continue. Claude’s Free plan allows one custom connector.

Account tools: if the dialog offers Request headers (a beta Anthropic is rolling out to some accounts), choose No sign-in and add a header named Authorization with the value Bearer YOUR_TOKEN. Include the word Bearer and the space. Authentication can’t be changed on an existing connector, so remove it and add it again to add the token. Without request headers, use the Node.js setup in Claude Desktop.

ChatGPT

Add a custom MCP server (at the time of writing: Plugins → + → Add custom MCP server), enter https://www.gotfreefax.com/mcp and choose No authentication. Whether the option appears depends on your plan and workspace settings; see OpenAI’s guide for the current steps.

ChatGPT’s custom MCP servers support only OAuth or no authentication, so the account tools aren’t available in ChatGPT yet. The free tools and purchase_credits work.

Claude Code

# Free tools
claude mcp add --transport http gotfreefax https://www.gotfreefax.com/mcp

# With your account (already added? run: claude mcp remove gotfreefax)
claude mcp add --transport http gotfreefax https://www.gotfreefax.com/mcp \
  --header "Authorization: Bearer YOUR_TOKEN"

Codex (CLI and IDE extension)

For a new connection, add this entry to ~/.codex/config.toml. If [mcp_servers.gotfreefax] already exists, update that entry instead. Start a new Codex session after saving.

[mcp_servers.gotfreefax]
url = "https://www.gotfreefax.com/mcp"

# With your account, uncomment one of these:
# http_headers = { "Authorization" = "Bearer YOUR_TOKEN" }
# bearer_token_env_var = "GOTFREEFAX_TOKEN"   # the variable holds YOUR_TOKEN, without "Bearer "

To add your account to an existing setup, put the line inside the [mcp_servers.gotfreefax] entry you already have. A second [mcp_servers.gotfreefax] makes the whole file invalid. Use bearer_token_env_var if the config file is shared or checked into a repository, so the token stays out of it.

Cursor

Add this to your user configuration at ~/.cursor/mcp.json. If it already contains servers, add or replace only the gotfreefax entry inside mcpServers. Leave out headers for the free tools. For a shared project configuration at .cursor/mcp.json, use "Bearer ${env:GOTFREEFAX_TOKEN}" as the value and set GOTFREEFAX_TOKEN to your token in your environment.

{
  "mcpServers": {
    "gotfreefax": {
      "url": "https://www.gotfreefax.com/mcp",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}

VS Code

Run MCP: Open User Configuration and add this configuration. If the file already contains servers, add or replace the gotfreefax entry inside servers and merge the token prompt into inputs. Leave out inputs and headers for the free tools.

VS Code asks for your token the first time the server starts and stores it securely. This example can also go in a project’s .vscode/mcp.json because it contains a prompt, not your token.

{
  "inputs": [
    { "type": "promptString", "id": "gotfreefax-token", "description": "GotFreeFax token", "password": true }
  ],
  "servers": {
    "gotfreefax": {
      "type": "http",
      "url": "https://www.gotfreefax.com/mcp",
      "headers": { "Authorization": "Bearer ${input:gotfreefax-token}" }
    }
  }
}

Claude Desktop with Node.js (mcp-remote)

For the account tools in Claude Desktop when request headers aren’t offered, or for any client that only runs local (stdio) servers. Needs Node.js; the mcp-remote package bridges the app to the remote endpoint. Open claude_desktop_config.json (Settings → Developer → Edit Config), add or replace the gotfreefax entry inside mcpServers, and restart Claude Desktop. Keep any other server entries. Leave out the --header pair and env for the free tools.

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

Other clients and agents

Any client that speaks MCP over Streamable HTTP can connect to https://www.gotfreefax.com/mcp, adding Authorization: Bearer YOUR_TOKEN for the account tools. Agents that call the endpoint with plain HTTP can follow the Examples: every call is a POST /mcp with a JSON-RPC envelope.

4. 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>

5. Authentication

Free tools need no authentication. To use your prepaid account, your app sends a Bearer token with its requests.

Sign in to My Account, choose your app, and copy its setup instructions. Your token is already filled in; you don’t need to create it yourself.

Advanced: create your token manually

The token is your account number and PIN encoded in Base64. Combine them with a colon separator, then encode the result:

Token = base64("ACCOUNT_NUMBER:PIN")

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

Include the token in the Authorization header of each request that uses your prepaid account:

Authorization: Bearer MTIzNDU2Nzg5MDo1Njc4

6. 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

7. 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": 24.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": 12.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, $12.95), prepaid20 (250 pages, $24.95), prepaid50 (800 pages, $59.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.

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

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