MCP server

Connect an AI agent to Faxbeep over MCP: the endpoint, setup in common clients, the three read-only tools, polling rules, limits, and sample answers for testing a connection.

Faxbeep runs a remote MCP (Model Context Protocol) server, so an AI agent can give a person the test numbers and then find their test without a polling script. It returns the same data as the API and is read-only: it can’t send a fax or remove one. The Faxbeep MCP page on faxbeep.com has example prompts and longer setup steps.

Each test is public for 30 days. Anyone can open it on faxbeep.com. Use a test page with no personal or confidential information. To remove a test early, see Remove a fax.

​

Endpoint

https://faxbeep.com/mcp

Item	Value
Transport	Streamable HTTP, stateless. POST only; GET and DELETE return 405
Authentication	None. No account, token, or session
Server name	Faxbeep
Protocol version	2025-11-25, 2025-06-18, or 2025-03-26
Tools	get_test_numbers, list_test_faxes, get_test_fax, all read-only
Browsers	Allowed from any origin (CORS), without credentials

Each tool has the annotations readOnlyHint: true, destructiveHint: false, idempotentHint: true, and openWorldHint: false.

​

Add the server to a client

Menu names and commands change often. The steps below are as of November 2026; check the client’s own documentation if they don’t match.

​

Chat apps

• Claude: go to Customize > Connectors, select + Add > Add custom connector, enter a name and the URL https://faxbeep.com/mcp, and choose No sign in for authentication. On Team and Enterprise plans, an owner adds the connector under Organization settings > Connectors.
• ChatGPT: turn on developer mode in the Apps settings (under Advanced settings), then create an app with the URL https://faxbeep.com/mcp and no authentication. Developer mode is available on the web and only on some plans. In a conversation, choose Developer mode from the + menu and select the app.

​

Coding agents

Claude Code

claude mcp add --transport http faxbeep https://faxbeep.com/mcp

For Cursor, put the JSON in ~/.cursor/mcp.json, or in .cursor/mcp.json in a project. For Codex, the command writes this to ~/.codex/config.toml:

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

In Claude Code and Gemini CLI, run /mcp to check the connection and list the tools.

​

How an agent finds a test

1. Get the numbers

   get_test_numbers returns the test numbers, the test email addresses, the limits, and now, the server time.

2. Record the start time

   Just before the person sends the test, take now from the latest result: call get_test_numbers again, or use the now of a list_test_faxes result. Use it as since. Don’t use the agent’s own clock: agents often have none, or write a local time with a Z.

3. Send the test

   The person sends a fax to a test number, or an email with one attachment to a test address.

4. Poll the list

   Call list_test_faxes with that since until a candidate appears. Polling means repeating the same call at an interval until the result appears.

5. Check the candidate

   Show the person the view_url so they can check the page. In a chat that shows images, the agent also shows thumbnail_url as an image in its answer. get_test_fax reads one fax again by its slug or its view_url.

​

Polling rules

The server states these rules in its instructions (returned by initialize) and in its tool descriptions, so a client that passes them to the model gives the agent the same rules.

• Keep since fixed while you poll. In the server’s words: “Do not move it to the newest received_at: a long fax can appear after a newer, shorter one.”
• A match narrows the candidates; it doesn’t prove the fax is the person’s. Other people send tests at the same time. Filtering by time, sender, or page count lowers the number of candidates, so show the person the view_url.
• Wait between calls, and stop. The server says: “A new fax usually appears within a minute after the call ends or the email is sent; a few take longer. Wait about 30 seconds between calls, and stop after about 10 minutes.” If nothing appears, see My fax does not appear.

​

Tools

Each successful result has the JSON in structuredContent and the same JSON as text in content. An error is a tool result with isError: true and the message as text, not a JSON-RPC error.

​

get_test_numbers

Input: none.

Field	Contents
numbers	Each test number: country, label, local_format (to dial inside its country), international_format (to dial from any other country)
email_addresses	Each test email address: country, address. Left out while the email test is off
limits	public_days, email_max_message_bytes (the whole email), email_max_pages, email_messages_per_hour_per_sender
troubleshooting_url	The Email refusal messages page
now	The server time, ISO 8601 in UTC with Z. Use it as since

The values in limits are the ones on the Limits page.

When	Error text
The numbers can’t be read	”The test numbers cannot be read now. They are also on https://faxbeep.com. Try again later.”

​

list_test_faxes

The same list as GET /api/faxes: published tests from everyone, newest first, with one more filter, page_count.

Input	Type	Rule
since	ISO 8601 with offset	Only faxes received after this time. Default: 24 hours ago. A fax older than 30 days isn’t listed
from	Text, up to 255	Only faxes from this sender: the full number or station ID, or the sender address of an email test. Not the masked value. The whole value must match; case doesn’t matter
limit	Integer	1 to 100. Default: 20. No paging
page_count	Integer, 1 or more	Only faxes with this number of pages

An empty string or null counts as not given. The result has:

Field	Contents
faxes	A list of fax objects, the same as the API returns
since	The start time that was used, in UTC with Z
now	The server time
message	Only when faxes is empty: what to do next (below)

When faxes has limit items, more can match. Narrow the list with from, page_count, or a since closer to the test.

An empty list isn’t an error. Its message is: “No fax matches yet. This is normal while a fax is on its way. A new fax usually appears within a minute after the call ends or the email is sent; a few take longer. Call again with the same since. Wait about 30 seconds between calls, and stop after about 10 minutes. Then tell the person, and point them to https://faxbeep.mintlify.app/troubleshooting/fax-does-not-appear.”

When	Error text
Invalid since	”since must be an ISO 8601 time with an offset, such as the “now” value of a result. Leave it out for the last 24 hours.”
Invalid from	”from must be text of up to 255 characters: the full fax number, station ID or email address of the sender. Leave it out to list faxes from every sender.”
Invalid limit	”limit must be a whole number from 1 to 100. Leave it out for 20.”
Invalid page_count	”page_count must be a whole number, 1 or more. Leave it out to list faxes with any number of pages.”

​

get_test_fax

The same lookup as GET /api/faxes/{slug}.

Input	Type	Rule
fax	Text	Required. The slug (fax_ and 8 characters from 0-9 and a-f, for example fax_1a2b3c4d), or the view_url of the fax, with or without a language prefix such as /de

The result is one fax object, the same as an item of list_test_faxes, as text and as structured content. After it comes an image of page 1 (MCP image content, JPEG or PNG, about 400 pixels wide), so a client that shows images from a tool shows the fax without a click. The image is left out when it can’t be read; the fax object still comes. A client can draw a tool image very small (Claude does), so the server asks the agent to also show thumbnail_url as an image in its answer, in a chat that shows images, and to give view_url for the full page.

When	Error text
fax holds no valid slug	”Give the slug of the fax (fax_ and 8 characters from 0-9 and a-f, for example fax_1a2b3c4d) or the URL of its page on faxbeep.com (view_url).”
No published fax has the slug, or it is still processing	”No published fax has this slug. A new fax usually appears within a minute after the call ends or the email is sent; a few take longer. A fax that is still processing is not found yet. Check the slug (fax_ and 8 characters from 0-9 and a-f), or use list_test_faxes. Wait about 30 seconds between calls, and stop after about 10 minutes. Then tell the person, and point them to https://faxbeep.mintlify.app/troubleshooting/fax-does-not-appear.”
The fax was removed on request or after 30 days	”This fax was removed, or it is older than 30 days.”

A removed fax’s files are deleted, so it can’t be read again.

​

Sample answers for testing a connection

Real tests leave the list after 30 days, so the server also answers fixed samples. They aren’t real faxes, have a fixed date in the past (2026-01-05T09:30:00Z), and stay available.

Call	Answer
get_test_fax with fax_example	A sample fax object: 1 page, source phone, from FAXBEEP-EXAMPLE
get_test_fax with fax_example_removed	The removed-fax error: “This fax was removed, or it is older than 30 days.”
list_test_faxes with from=FAXBEEP-EXAMPLE	A list with only fax_example, whatever since says

The sample’s pdf_url and thumbnail_url are real files, and get_test_fax with fax_example returns the sample’s image of page 1. Its view_url points to the Faxbeep MCP page, and get_test_fax with that URL returns the sample again.

To check the endpoint without a client, call a tool directly. The server is stateless, so no initialize call is needed first:

curl -sS https://faxbeep.com/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_test_fax","arguments":{"fax":"fax_example"}}}'

​

Rate limit and errors

600 MCP messages per minute per IPv4 address, or per IPv6 /64 block. Every message counts: the handshake, the tool list, and each tool call. Chat apps such as Claude connect from their own servers, not from your device, so many users of one app can share an address. Over the limit, the server returns 429 with a Retry-After header; wait that many seconds. This limit is separate from the API’s 60 requests per minute.

Every response, including errors, is JSON and has Cache-Control: no-store, private, so caches don’t keep an old answer. GET and DELETE return 405 with {"message": "The MCP endpoint takes POST only."}.

​

Sending a test without a fax machine

Faxbeep only receives faxes. To send a test without a fax machine, use a fax sending service, for example PayPerFax.

​

Next steps

Find your fax

How time, sender, and page count narrow the results.

API reference

The fax object, the API rate limit, and errors.