GotFreeFax.com REST API & Fax MCP Server

Version 2.0 — REST API & MCP Server for developers and AI agents

1. Overview

The GotFreeFax.com API allows external applications and AI agents to send faxes to the United States and Canada. Two interfaces are available:

• REST API v2 — Standard JSON-based HTTP API for any programming language
• MCP Server — Model Context Protocol endpoint for AI agents (Claude, etc.)

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

API access is available to GotFreeFax.com prepaid account holders.

2. Authentication

Both the REST API and MCP Server use 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 request:

Authorization: Bearer MTIzNDU2Nzg5MDo1Njc4

Code Examples

# Python
import base64
token = base64.b64encode(b"1234567890:5678").decode()
headers = {"Authorization": f"Bearer {token}"}

# JavaScript
const token = btoa("1234567890:5678");
headers: { "Authorization": `Bearer ${token}` }

# C#
var token = Convert.ToBase64String(Encoding.UTF8.GetBytes("1234567890:5678"));
request.Headers.Add("Authorization", "Bearer " + token);

# cURL
curl -H "Authorization: Bearer $(echo -n '1234567890:5678' | base64)"

3. REST API v2

All endpoints return JSON with this envelope:

// Success
{
  "success": true,
  "data": { ... },
  "error": null
}

// Error
{
  "success": false,
  "data": null,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description"
  }
}

3a. Send a Fax

Send a fax with one or more file attachments.

Request Body

Field	Type	Required	Description
fax_number	string	Yes	10-digit US or Canada fax number
notify_url	string	No	URL to POST fax status notification
files	array	Yes	Array of file objects
files[].filename	string	Yes	Filename with extension (e.g. letter.pdf)
files[].content	string	Yes	Base64-encoded file content

Example Request

curl -X POST https://www.gotfreefax.com/api/v2/fax \
  -H "Authorization: Bearer MTIzNDU2Nzg5MDo1Njc4" \
  -H "Content-Type: application/json" \
  -d '{
    "fax_number": "8885551234",
    "notify_url": "https://example.com/fax-callback",
    "files": [
      {
        "filename": "document.pdf",
        "content": "JVBERi0xLjQK..."
      }
    ]
  }'

Example Response

{
  "success": true,
  "data": {
    "job_id": "ABCDEFGHIJ"
  },
  "error": null
}

3b. Check Fax Status

Check the delivery status of a sent fax.

Path Parameters

Parameter	Description
job_id	The job ID returned by the Send Fax endpoint

Example Request

curl https://www.gotfreefax.com/api/v2/fax/ABCDEFGHIJ \
  -H "Authorization: Bearer MTIzNDU2Nzg5MDo1Njc4"

Example Response

{
  "success": true,
  "data": {
    "job_id": "ABCDEFGHIJ",
    "fax_number": "8885551234",
    "status": "success",
    "page_count": 2,
    "completed_at": "2025-01-15T10:30:00Z",
    "detail": ""
  },
  "error": null
}

Status Values

Status	Description
pending	Fax is queued or in progress
success	Fax delivered successfully
failure	Fax failed or was cancelled

3c. Account Balance

Example Request

curl https://www.gotfreefax.com/api/v2/account/balance \
  -H "Authorization: Bearer MTIzNDU2Nzg5MDo1Njc4"

Example Response

{
  "success": true,
  "data": {
    "page_balance": 50,
    "amount_balance": 12.50
  },
  "error": null
}

3d. Supported Formats

Example Request

curl https://www.gotfreefax.com/api/v2/formats

Example Response

{
  "success": true,
  "data": {
    "formats": [
      { "description": "Adobe PDF", "extensions": ["pdf"] },
      { "description": "Microsoft Word", "extensions": ["doc", "dot"] },
      { "description": "Microsoft Word 2007+", "extensions": ["docx"] },
      ...
    ]
  },
  "error": null
}

4. MCP Server (AI Agents)

The Model Context Protocol (MCP) endpoint allows AI agents to discover and use GotFreeFax tools directly.

Connection Details

Endpoint	https://www.gotfreefax.com/mcp
Transport	Streamable HTTP (JSON-RPC 2.0 over POST)
Content-Type	application/json
Authentication	Authorization: Bearer <token>

Available Tools

Tool	Description	Auth
send_fax	Send a fax with file attachments	Yes
check_fax_status	Check delivery status of a fax	Yes
get_account_balance	Get page and dollar balance	Yes
list_supported_formats	List accepted file types	No

Example: 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" }
  }
}

Example: List Tools

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

Example: Send a Fax via MCP

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
  }
}

Claude Desktop Configuration

To use GotFreeFax with Claude Desktop, add this to your claude_desktop_config.json:

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

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

5. Error Codes

REST API Error Codes

HTTP Status	Code	Description
401	UNAUTHORIZED	Missing or invalid authentication token
400	INVALID_FAX_NUMBER	Fax number is not a valid 10-digit US/Canada number
400	INVALID_FILES	Missing files or invalid file data
400	INVALID_BASE64	File content is not valid base64
400	INVALID_JSON	Request body is not valid JSON
400	INVALID_JOB_ID	Job ID is missing or empty
400	UNSUPPORTED_FORMAT	File type is not supported (allowed: PDF, DOC, DOCX, JPG, JPEG, TXT)
400	TOO_MANY_FILES	Exceeded maximum of 10 files per fax
402	INSUFFICIENT_BALANCE	Account has no page credits remaining
404	NOT_FOUND	Fax job not found
500	SYSTEM_ERROR	Internal server error

MCP JSON-RPC Error Codes

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

6. Supported File Formats & Limits

Maximum 10 files per fax request.

Format	Extensions
Adobe PDF	pdf
Microsoft Word	doc, docx
JPEG Image	jpg, jpeg
Plain Text	txt

---

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