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
- Choose your app. Follow its setup instructions below for the free tools.
- 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.
- 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.
| App | Free tools | Account tools |
|---|---|---|
| Claude (claude.ai, Claude Desktop, mobile) | Yes, paste the URL | With request headers (beta), or Claude Desktop with Node.js |
| ChatGPT | Yes, paste the URL | Not yet (OAuth only) |
| Claude Code | Yes | Yes, add the header |
| Codex | Yes | Yes, add the header |
| Cursor | Yes | Yes, add the header |
| VS Code | Yes | Yes, add the header |
Claude (claude.ai, Claude Desktop, mobile)
- Go to Customize → Connectors, click + Add, then Add custom connector. Team and Enterprise admins add it under Organization settings → Connectors.
- Enter a name (for example GotFreeFax) and the URL
https://www.gotfreefax.com/mcp. - 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
/mcp
Auth Required (for most tools)
| Endpoint | https://www.gotfreefax.com/mcp |
| Transport | Streamable HTTP (JSON-RPC 2.0 over POST) |
| Protocol Version | 2024-11-05 |
| Content-Type | application/json |
| Authentication | Authorization: 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
| Tool | Description | Auth |
|---|---|---|
send_fax | Send a fax with file attachments (up to 10 files) | Yes |
check_fax_status | Check delivery status of a fax by job_id | No |
list_sent_faxes | List faxes previously sent by the authenticated account (paginated, most recent first) | Yes |
get_account_balance | Get page and dollar balance for the authenticated account | Yes |
purchase_credits | Start 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_fax | Send 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_formats | List accepted file types | No |
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:
| Code | Description |
|---|---|
-32700 | Parse error (malformed JSON) |
-32600 | Invalid request (missing method) |
-32601 | Method or tool not found |
-32602 | Invalid 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.
| Format | Extensions |
|---|---|
| Adobe PDF | |
| Microsoft Word | doc, docx |
| JPEG Image | jpg, jpeg |
| Plain Text | txt |
Need help? Contact us at gotfreefax.com/contact.