> ## Documentation Index
> Fetch the complete documentation index at: https://faxbeep.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://faxbeep.mintlify.site/api-reference/introduction.md) and is read-only: it can't send a fax or remove one. The [Faxbeep MCP page](https://faxbeep.com/test-fax-mcp) on faxbeep.com has example prompts and longer setup steps.

> [!WARNING]
>
> 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](https://faxbeep.mintlify.site/privacy/remove-a-fax.md).

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

```bash Claude Code theme={null}
claude mcp add --transport http faxbeep https://faxbeep.com/mcp
```

```bash Codex theme={null}
codex mcp add faxbeep --url https://faxbeep.com/mcp
```

```bash Gemini CLI theme={null}
gemini mcp add --transport http faxbeep https://faxbeep.com/mcp
```

```json Cursor theme={null}
{
  "mcpServers": {
    "faxbeep": {
      "url": "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`:

```toml theme={null}
[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](https://faxbeep.mintlify.site/troubleshooting/fax-does-not-appear.md).

## 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](https://faxbeep.mintlify.site/troubleshooting/email-refusals.md) 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](https://faxbeep.mintlify.site/reference/limits.md) page.

| When | Error text |
| - | - |
| The numbers can't be read | "The test numbers cannot be read now. They are also on [https://faxbeep.com](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](https://faxbeep.mintlify.site/developers/station-id.md), 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](https://faxbeep.mintlify.site/api-reference/faxes/get-a-fax.md), 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](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](https://faxbeep.mintlify.site/api-reference/faxes/get-a-fax.md), 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](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:

```bash theme={null}
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](https://payperfax.com/).

## Next steps

> [card] [Find your fax](https://faxbeep.mintlify.site/developers/find-your-fax.md)
>
> How time, sender, and page count narrow the results.

> [card] [API reference](https://faxbeep.mintlify.site/api-reference/introduction.md)
>
> The fax object, the API rate limit, and errors.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.