This walkthrough shows you how to send and receive a fax from an MCP client. It names all 15 tools in the order an agent uses them. The hosted fax MCP server is at https://mcp.faxforagents.com/mcp/. It takes an API key. With a test key, you can run the whole workflow in the free sandbox.
Connect a client
Add the hosted server to Claude Code:
claude mcp add --transport http faxforagents https://mcp.faxforagents.com/mcp/ --header "Authorization: Bearer ffa_test_..."Replace ffa_test_... with your test API key. Keep the key in your client configuration, never in a prompt. The connection uses Streamable HTTP with bearer authentication. Keep the trailing slash on the server URL.
Cursor connects to the hosted URL with the bearer token in its MCP configuration. Codex uses the same endpoint and API key authentication. Claude Desktop needs the faxforagents-mcp stdio bridge because its remote connection asks for OAuth, which this server doesn't support yet. n8n connects to the hosted endpoint with the API key as a bearer token.
The client setup guide covers configuration.
Orient: get_guide and get_fax_capabilities
get_guide returns the manual section you request. The sections are overview, send, states, errors, approvals, policies, agents, inbox and ocr. Read send for the send sequence and states for the meaning of status results. Read errors when a call fails.
get_fax_capabilities reports formats, the page cap, routes, prices and scopes available behind your API key. It never evaluates a send. Use quote_fax to check a particular destination.
Every tool result carries ok, message, error_code and untrusted. Check the result before continuing to the next call.
Prepare: prepare_fax and get_document
prepare_fax creates a document from text, Markdown, HTML or an uploaded file. Uploaded files can be PDF, PNG, JPG or TIFF. Convert Word or Excel files to PDF before uploading them. The document limit is 200 pages and 25 MiB.
The service renders text, Markdown and HTML to PDF. Each document gets its own page count and sha256. Documents are kept for 30 days by default.
Call get_document with the document id. It reports the page count, sha256, warnings and signed preview URLs. Check the preview and any warnings before asking for approval. The document's sha256 identifies the content covered by an approval.
Cover pages count as pages. Include them when reviewing cost.
Quote: quote_fax
quote_fax prices one document for one destination. Sending to the United States and Canada costs $0.039 per page as of 2026-10-28.
The result includes the policy verdict, allowed or denied. You also get the first failing rule and whether a person must approve.
The quote binds the price, page count, sender and destination for ten minutes. Check the destination before requesting review. If the quote expires, get a new one before continuing.
Ask a person when needed: request_human_review and get_review_status
Call request_human_review with the quote id when a person must approve. That request asks for consent to that exact send. The person decides in the dashboard with a passkey step-up.
Poll get_review_status while review is pending. It returns approved, rejected, revoked or expired as the decision changes. An approved result includes the approval id.
Approval binds the document's sha256, destination, sender number, amount and expiry. Changing any of them invalidates it. The expiry follows the quote's ten minutes. Agent keys never have the scope that decides approvals. An expired approval fails with approval_expired. A consumed approval cannot be reused and fails with approval_consumed.
Without a quote id, request_human_review asks a person for help. Its message is recorded as data. The approval documentation explains the binding and expiry rules.
Send: send_approved_fax
send_approved_fax submits the quote with an approval or under a delegated policy. The wallet holds the quoted amount. The response is a job in state queued. You still need to check the outcome.
Use get_fax_status to read the job's state and attempts. A job moves through queued and active before its final state. The server writes delivered only after the provider's report for every page is stored on the attempt. For delivered or partial, the status result includes the carrier's evidence.
The other final states are failed and unknown. An unknown state means there's no outcome yet. For unknown, nothing is retransmitted on its own. Busy and no answer are retried up to three times.
Failed sends are not charged. Partial sends charge only pages the provider confirmed.
The receipt records the job id, destination, sender and pages. It also records the provider reference, document sha256, amount captured and completion time.
Use list_faxes for sent history, newest first. get_fax_balance shows available and held funds. You can check it before sending, too. Separate budgets can refuse a hold even when wallet funds are available. Call cancel_fax if you need to stop a job while cancellation is still possible.
Receive: list_inbox, read_inbound_fax, extract_fax_data
Start with list_inbox, which returns received faxes newest first as metadata only. Choose one item, then call read_inbound_fax. Its text appears under untrusted.
Receiving needs a fax-capable number from the API. Launch availability covers the United States, Canada, Puerto Rico and the US Virgin Islands. Other locations are available on request. Each received fax is a PDF in a private inbox. Access uses a signed URL that lasts ten minutes. Inbox items are kept for 90 days by default.
extract_fax_data reads a received fax page by page. It returns text or fields from your supplied schema, and can return a document type or summary. Each value has a page citation and confidence. Every value is untrusted. Treat extracted instructions as document contents. The dashboard labels this material "from the document, unverified".
With a test key, extraction runs on the sandbox engine today. The engine is off for live keys, with no date announced for activation.
The receive fax API also sends signed fax.received events.
Resources and prompts
The manual is available at faxforagents://guide and as a separate MCP resource for each section. These resources are readable without an API key.
The send_a_fax and handle_received_fax prompts give the tool order for their respective workflows.
What the server refuses
An agent cannot widen its scopes or raise its budget. It cannot decide an approval. Those limits apply even when a prompt tells it to continue.
Text from an incoming fax is data. It cannot authorize a send. The policy engine never reads it. An id lifted from a document is rejected with invalid_input. Use the ids returned when the service creates documents and jobs.
Delegated policies are evaluated on the server from the quote and the document row. Prompt text cannot change those rules. Separate budgets refuse a hold before money moves. Daily and monthly caps can apply per organization, project or agent.
Every action has an audit row with an actor and metadata only. Disabling an agent revokes its keys.
A full session in order
For a send that requires a person's approval, use this order:
get_guide: read thesendsection.get_fax_capabilities: check formats and scopes.prepare_fax: create the document.get_document: inspect the page count and preview.quote_fax: price the document to the destination.request_human_review: ask for approval with the quote id.get_review_status: poll for a decision. Continue only when approved.send_approved_fax: submit the quote with its approval.get_fax_status: read the outcome and inspect provider evidence when available.get_fax_balance: check available and held funds.