Skip to content

Connecting AI tools to Retarus API Docs

Note

This guide covers best practices for using AI tools with Retarus developer documentation. AI tools can make mistakes. Always review generated code against the documentation, your environment, and your integration requirements before using it in production.

You can connect AI tools directly to Retarus API Docs, providing access to the developer documentation in context. This can improve code generation, support more accurate answers about endpoints and parameters, and speed up integration work without requiring manual lookup or copying of documentation

How it works

Retarus API Docs provides the Retarus Docs MCP server, which implements the Model Context Protocol (MCP), an open standard for providing structured context to AI tools.

When connected to the Retarus Docs MCP server, an AI tool can use the following tools.

MCP Server ToolsParametersScope & Description
list-apisfilter
page
limit		REST APIs only
Lists available Retarus REST APIs.
Use the optional filter parameter with a name fragment to narrow results. For example, fax returns only fax-related APIs.
Use page and limit to paginate results. The default is 300 per page.
All parameters are optional.
get-endpointsnameREST APIs only
Returns all endpoints and descriptions for a specific REST API.
get-endpoint-infoname
path
method		REST APIs only
Returns comprehensive details for a specific endpoint, including parameters, security schemes, and examples.
get-security-schemesnameREST APIs only
Returns the authentication details for a specific REST API.
get-full-api-descriptionnameREST APIs only
Returns the complete OpenAPI description for a REST API.
searchqueryAll content
Searches across all documentation, including Markdown pages, REST API docs, and GraphQL documentation.
Note

The Docs MCP server provides read-only access to Retarus API documentation. It does not make API calls on your behalf. Any generated code must still be reviewed, configured with your credentials, and executed in your own environment.

What the Docs MCP server can access

The available MCP tools differ depending on the content type. Use the structured API tools for OpenAPI-based REST APIs, and use search for GraphQL documentation and other Markdown-based content.

REST APIs (full tool support)

The API Catalog tools give structured, queryable access to all Retarus REST APIs published as OpenAPI descriptions. You can browse endpoints, inspect parameters, retrieve security schemes, and get full OpenAPI definitions.

APIDescription
Faxolution for Applications (Fax4A) REST APISend faxes, monitor transmission status, and manage status reports.
Fax Configuration APIConfigure Mail-to-Fax, Fax-to-Email, Fax-to-FTP, and Fax-to-Webservice.
Fax2WSPullActively retrieve received inbound faxes organized by topic.
Faxolution for Applications status push notification APIReceive proactive push notifications for outbound fax job outcomes (XML or JSON).
SMS for Applications REST APISend SMS messages and look up delivery status.
Transactional Email APISubmit and manage transactional email jobs.
IDP Integration APIUpload documents and retrieve structured Intelligent Document Processing results.
Continuity ServiceManage Email Continuity mailboxes and control failover routing.
SEG Configuration GatewayManage customer configuration settings.
Public Status APIGet overall service status, incidents, and planned maintenance by service and region.

GraphQL and other content (search only)

The GraphQL Reporting API documentation, along with all other Markdown-based documentation such as guides, concepts, and reference pages, is available through the search tool only.

Connect your AI tool

Once you understand the available tools and their scope, you can connect a supported AI tool to the Retarus Docs MCP server.

The Retarus Docs MCP server is available at https://developers.retarus.com/mcp and works with AI tools that support MCP. Use the button below to connect from Cursor or VS Code, or to copy the MCP configuration:

Example: Connecting Claude Code to the Docs MCP server

Run the following command, replacing retarus-mcp with your preferred server name:

claude mcp add retarus-mcp https://developers.retarus.com/mcp --transport http

In the Claude Code CLI, type /mcp to verify the connection and view the available tools.

Retarus-mcp MCP Server

Status:           ✔ connected
Auth:             ✔ authenticated
URL:              https://developers.retarus.com/mcp
Config location:  /home/username/.claude.json
Capabilities:     tools
Tools:            6 tools

❯ 1. View tools
  1. Re-authenticate
  2. Clear authentication
  3. Reconnect
  4. Disable

Test the connection

Ask the AI tool to perform a simple task using a Retarus API, for example:

"List all available Retarus APIs."

Result

● Here are all 10 available Retarus APIs:

  #: 1
  Name: Public Status API
  Version: 1.0
  Description: Overall status of Retarus Cloud Services — incidents, maintenances, and service info by region
  ────────────────────────────────────────
   #: 2
  Name: Fax Configuration API
  Version: 2.0
  Description: Administer Mail-to-Fax, Fax-to-Email, Fax-to-FTP, and Fax-to-Webservice
  ────────────────────────────────────────
  ... (output truncated)

Examples

The following examples show what you can ask an AI tool once connected to the Retarus Docs MCP server and the kind of output to expect. All examples were produced using Claude Code with the Retarus Docs MCP server connected.

List available endpoints

Prompt

Get endpoints for the Faxolution for Applications (Fax4A) REST API.

Result
The AI calls get-endpoints and returns a structured overview of the API, including the following endpoint table.


  Called retarus-mcp (ctrl+o to expand)

● Here are all endpoints for the Faxolution for Applications (Fax4A) REST API (v1):

  ---
  Base Path: /{custNr}/fax

  Method: POST
  Path: /{custNr}/fax      
  Summary: Send a fax — Submit a fax job; returns a Job ID for status tracking
  ────────────────────────────────────────
  Method: GET
  Path: /{custNr}/fax/reports
  Summary: Fetch all status reports — Lists completed fax jobs (oldest 1000; data-center-specific URL required)
  ────────────────────────────────────────
  Method: POST
  Path: /{custNr}/fax/reports
  Summary: Bulk operations on reports — Fetch or delete up to 1000 reports by Job ID list
  ────────────────────────────────────────
  Method: DELETE
  Path: /{custNr}/fax/reports
  Summary: Delete oldest status reports — Deletes up to 1000 oldest reports
  ────────────────────────────────────────
  Method: GET
  Path: /{custNr}/fax/reports/{jobId}
  Summary: Fetch single job report — Get status for a specific Job ID
  ────────────────────────────────────────
  Method: DELETE
  Path: /{custNr}/fax/reports/{jobId}
  Summary: Delete single job report — Delete and return the Job ID

  ---
  Servers

  ┌───────────────┬─────────────────────────────────────────┐
  │    Region     │                   URL                   │
  ├───────────────┼─────────────────────────────────────────┤
  │ Germany (DE1) │ https://faxws.de1.retarus.com/rest/v1   │
  ├───────────────┼─────────────────────────────────────────┤
  │ Germany (DE2) │ https://faxws.de2.retarus.com/rest/v1   │
  ├───────────────┼─────────────────────────────────────────┤
  │ Germany HA    │ https://faxws-ha.de.retarus.com/rest/v1 │
  ├───────────────┼─────────────────────────────────────────┤
  │ USA (US1)     │ https://faxws.us1.retarus.com/rest/v1   │
  ├───────────────┼─────────────────────────────────────────┤
  │ USA (US2)     │ https://faxws.us2.retarus.com/rest/v1   │
  ├───────────────┼─────────────────────────────────────────┤
  │ USA HA        │ https://faxws-ha.us.retarus.com/rest/v1 │
  ├───────────────┼─────────────────────────────────────────┤
  │ Switzerland   │ https://faxws.ch1.retarus.com/rest/v1   │
  ├───────────────┼─────────────────────────────────────────┤
  │ Singapore     │ https://faxws.sg1.retarus.com/rest/v1   │
  └───────────────┴─────────────────────────────────────────┘

  ▎ Note: The GET, POST, and DELETE operations on /reports (bulk) must use a data-center-specific URL — not an HA URL — to avoid inconsistent or erroneous results.

Get full details for a specific endpoint

Prompt

Get endpoint information for GET /{custNr}/fax/reports/{jobId}.

Result
The AI calls get-endpoint-info and returns complete documentation for the endpoint, including parameters, authentication, response schema, and an example response.

Called retarus-mcp (ctrl+o to expand)

● Here’s the full detail for GET /{custNr}/fax/reports/{jobId}:

Summary

Fetch the status report for a single fax job by its Job ID. Reports are available until deleted or until they expire (default: 30 days).

Parameters

┌────────┬──────┬──────────┬────────┬────────────────────────────────────────────────┐
│ Name   │ In   │ Required │ Type   │ Description                                    │
├────────┼──────┼──────────┼────────┼────────────────────────────────────────────────┤
│ custNr │ path │ yes      │ string │ Customer Number                                │
├────────┼──────┼──────────┼────────┼────────────────────────────────────────────────┤
│ jobId  │ path │ yes      │ string │ The Job ID returned when the fax was submitted │
└────────┴──────┴──────────┴────────┴────────────────────────────────────────────────┘

Authentication

HTTP Basic Auth — every request must include:
Authorization: Basic Base64Encoded(username:password)

▎ Note: A job’s status report can only be fetched using the same Login ID that created it.

Responses

200 — Success

{
  "jobId": "FJJ66GHGX105ZZBIELVCN1",
  "pages": 1,
  "recipientStatus": [
    {
      "number": "+49 89 1234567-8900",
      "status": "OK",
      "reason": "OK",
      "sentTs": "2017-08-10T13:05:09Z",
      "durationInSecs": 19,
      "sentToNumber": "00498912345678900",
      "remoteCsid": "+49/89/1234567-8900",
      "properties": null
    }
  ],
  "reference": {
    "customerDefinedId": "...",
    "billingCode": "...",
    "billingInfo": "..."
  }
}

Response fields:

┌──────────────────────────────────┬──────────┬───────────────────────────────────────────────┐
│ Field                            │ Type     │ Description                                   │
├──────────────────────────────────┼──────────┼───────────────────────────────────────────────┤
│ jobId                            │ string   │ The Job ID                                    │
├──────────────────────────────────┼──────────┼───────────────────────────────────────────────┤
│ pages                            │ integer  │ Number of pages in the fax                    │
├──────────────────────────────────┼──────────┼───────────────────────────────────────────────┤
│ recipientStatus[].number         │ string   │ Recipient’s fax number (international format) │
├──────────────────────────────────┼──────────┼───────────────────────────────────────────────┤
│ recipientStatus[].status         │ string   │ Transmission status (e.g. OK)                 │
├──────────────────────────────────┼──────────┼───────────────────────────────────────────────┤
│ recipientStatus[].reason         │ string   │ Explanation of the status                     │
├──────────────────────────────────┼──────────┼───────────────────────────────────────────────┤
│ recipientStatus[].sentTs         │ datetime │ When the fax was sent (ISO 8601)              │
├──────────────────────────────────┼──────────┼───────────────────────────────────────────────┤
│ recipientStatus[].durationInSecs │ integer  │ Transmission duration in seconds              │
├──────────────────────────────────┼──────────┼───────────────────────────────────────────────┤
│ recipientStatus[].sentToNumber   │ string   │ Number the fax was actually sent to           │
├──────────────────────────────────┼──────────┼───────────────────────────────────────────────┤
│ recipientStatus[].remoteCsid     │ string   │ Fax ID of the recipient device                │
├──────────────────────────────────┼──────────┼───────────────────────────────────────────────┤
│ reference.customerDefinedId      │ string   │ Custom ID (max 256 chars)                     │
├──────────────────────────────────┼──────────┼───────────────────────────────────────────────┤
│ reference.billingCode            │ string   │ Cost center info (max 80 chars)               │
├──────────────────────────────────┼──────────┼───────────────────────────────────────────────┤
│ reference.billingInfo            │ string   │ Additional accounting data (max 80 chars)     │
└──────────────────────────────────┴──────────┴───────────────────────────────────────────────┘

401 — Authentication failed

{ "code": 401, "message": "Authentication failed" }

404 — Report not found

{ "code": 404, "message": "No reports available; Job IDs {FJL8LN75OO01L0D15QUN1T}" }

Look up authentication requirements

Prompt

Get security schemes for the Fax4A API.

Result
The AI calls get-security-schemes and explains how to authenticate, including credential scoping rules and optional IP allowlisting.


Called retarus-mcp (ctrl+o to expand)

● The Fax4A REST API uses a single security scheme:

httpBasicAuth — HTTP Basic Authentication

Type: http / scheme: basic

Every request must include a Basic Authorization header with a Base64-encoded username:password string:

Authorization: Basic Base64Encoded(username:password)

Example:
- Username: John, Password: secret
- Base64 of John:secret → Sm9objpzZWNyZXQ=

Authorization: Basic Sm9objpzZWNyZXQ=

Additional Security Details

┌─────────────────────┬─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ Feature             │ Detail                                                                                                                                                                      │
├─────────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ Login ID management │ Multiple Login IDs can be configured via the Retarus EAS Portal, allowing concurrent processes with separate configurations                                                 │
├─────────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ Data isolation      │ Job and report data is scoped to the Login ID that created it — a report can only be fetched or deleted by the same Login ID that submitted the job                         │
├─────────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ IP whitelisting     │ Access per Login ID can optionally be restricted to a predefined list of IP addresses/subnets, configured in the EAS Portal; requests from non-whitelisted                  │
│                     │ IPs are rejected                                                                                                                                                            │
└─────────────────────┴─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

Search across all content

The search tool works across all content in Retarus API Docs, including Markdown documentation pages and API documentation for both OpenAPI-based REST APIs and GraphQL.

Prompt

How do I send a fax?

Result
The AI calls search and returns a workflow summary, the key request fields for POST /{custNr}/fax, request body examples, and response codes:


Called retarus-mcp (ctrl+o to expand)

POST /{custNr}/fax — Send a Fax

Authentication: HTTP Basic Auth
Content-Type: application/json

Only recipients is required. Everything else is optional.

Request Body Fields

┌───────────────────────────────────────────────────────┬──────────┬──────────────────────────────────────────────────────────────────────────────┐
│ Field                                                 │ Required │ Description                                                                  │
├───────────────────────────────────────────────────────┼──────────┼──────────────────────────────────────────────────────────────────────────────┤
│ recipients[].number                                   │ yes      │ Recipient fax number (international format, e.g. +12015551000)               │
├───────────────────────────────────────────────────────┼──────────┼──────────────────────────────────────────────────────────────────────────────┤
│ recipients[].properties                               │ no       │ Key/value pairs for cover page personalization                               │
├───────────────────────────────────────────────────────┼──────────┼──────────────────────────────────────────────────────────────────────────────┤
│ documents[].name                                      │ no*      │ Filename with extension (max 32 chars, no spaces/special chars)              │
├───────────────────────────────────────────────────────┼──────────┼──────────────────────────────────────────────────────────────────────────────┤
│ documents[].data                                      │ no*      │ Base64-encoded file content                                                  │
├───────────────────────────────────────────────────────┼──────────┼──────────────────────────────────────────────────────────────────────────────┤
│ documents[].reference                                 │ no*      │ URL pointing to the document (use instead of data)                           │
├───────────────────────────────────────────────────────┼──────────┼──────────────────────────────────────────────────────────────────────────────┤
│ documents[].charset                                   │ no       │ Encoding for .txt files (default: UTF-8)                                     │
├───────────────────────────────────────────────────────┼──────────┼──────────────────────────────────────────────────────────────────────────────┤
│ transportOptions.csid                                 │ no       │ Sender ID shown on recipient’s fax (max 20 chars)                            │
├───────────────────────────────────────────────────────┼──────────┼──────────────────────────────────────────────────────────────────────────────┤
│ transportOptions.isExpress                            │ no       │ Send as express transmission                                                 │
├───────────────────────────────────────────────────────┼──────────┼──────────────────────────────────────────────────────────────────────────────┤
│ transportOptions.isBlacklistEnabled                   │ no       │ Check Robinson/ECOFAX/Retarus blacklists before sending                      │
├───────────────────────────────────────────────────────┼──────────┼──────────────────────────────────────────────────────────────────────────────┤
│ renderingOptions.paperFormat                          │ no       │ A4 or LETTER                                                                 │
├───────────────────────────────────────────────────────┼──────────┼──────────────────────────────────────────────────────────────────────────────┤
│ renderingOptions.resolution                           │ no       │ LOW or HIGH                                                                  │
├───────────────────────────────────────────────────────┼──────────┼──────────────────────────────────────────────────────────────────────────────┤
│ renderingOptions.coverpageTemplate                    │ no       │ Cover page template name (e.g. coverpage-default.ftl.html)                   │
├───────────────────────────────────────────────────────┼──────────┼──────────────────────────────────────────────────────────────────────────────┤
│ renderingOptions.overlay.name                         │ no       │ Name of a pre-deployed overlay/stationery TIF                                │
├───────────────────────────────────────────────────────┼──────────┼──────────────────────────────────────────────────────────────────────────────┤
│ renderingOptions.overlay.mode                         │ no       │ ALL_PAGES, FIRST_PAGE, LAST_PAGE, ALL_BUT_FIRST_PAGE, etc.                   │
├───────────────────────────────────────────────────────┼──────────┼──────────────────────────────────────────────────────────────────────────────┤
│ renderingOptions.header                               │ no       │ Header string with control characters                                        │
├───────────────────────────────────────────────────────┼──────────┼──────────────────────────────────────────────────────────────────────────────┤
│ statusReportOptions.reportMail.successAddress         │ no       │ Email for delivery confirmations                                             │
├───────────────────────────────────────────────────────┼──────────┼──────────────────────────────────────────────────────────────────────────────┤
│ statusReportOptions.reportMail.failureAddress         │ no       │ Email for failure notifications                                              │
├───────────────────────────────────────────────────────┼──────────┼──────────────────────────────────────────────────────────────────────────────┤
│ statusReportOptions.reportMail.attachedFaxImageMode   │ no       │ NEVER / SUCCESS_ONLY / FAILURE_ONLY / ALWAYS                                 │
├───────────────────────────────────────────────────────┼──────────┼──────────────────────────────────────────────────────────────────────────────┤
│ statusReportOptions.reportMail.attachedFaxImageFormat │ no       │ TIFF / PDF / PDF_WITH_OCR                                                    │
├───────────────────────────────────────────────────────┼──────────┼──────────────────────────────────────────────────────────────────────────────┤
│ statusReportOptions.httpStatusPush.targetUrl          │ no       │ Webhook URL for HTTP status push notifications                               │
├───────────────────────────────────────────────────────┼──────────┼──────────────────────────────────────────────────────────────────────────────┤
│ reference.customerDefinedId                           │ no       │ Custom tracking ID (max 256 chars)                                           │
├───────────────────────────────────────────────────────┼──────────┼──────────────────────────────────────────────────────────────────────────────┤
│ reference.billingCode                                 │ no       │ Cost center info (max 80 chars)                                              │
└───────────────────────────────────────────────────────┴──────────┴──────────────────────────────────────────────────────────────────────────────┘

▎ *Either a document or a cover page template must be provided — the job will be rejected if neither is present. For documents, use either data (base64) or reference (URL), not both.

Examples

Minimal — send a PDF by base64:

{
  "recipients": [{ "number": "+498900000000" }],
  "documents": [
    {
      "name": "invoice.pdf",
      "data": "<base64-encoded-pdf>"
    }
  ]
}

Send a PDF from a URL:

{
  "recipients": [{ "number": "+498900000000" }],
  "documents": [
    {
      "name": "document.pdf",
      "reference": "https://example.com/document.pdf"
    }
  ]
}

Send with cover page only:

{
  "recipients": [
    {
      "number": "+498900000000",
      "properties": [
        { "key": "FromName", "value": "John Doe" },
        { "key": "FromCompanyName", "value": "Retarus" },
        { "key": "ToName", "value": "Jane Doe" },
        { "key": "SubjectTitle", "value": "My Fax Subject" }
      ]
    }
  ],
  "renderingOptions": {
    "paperFormat": null,
    "coverpageTemplate": "coverpage-default.ftl.html"
  }
}

Responses

┌──────┬──────────────────────────────────────────────────────────────┐
│ Code │ Meaning                                                      │
├──────┼──────────────────────────────────────────────────────────────┤
│ 200  │ Job accepted — returns { "jobId": "FJKQQUVF1J0IADYARQEXKC" } │
├──────┼──────────────────────────────────────────────────────────────┤
│ 400  │ Invalid/incomplete request (e.g. missing recipient number)   │
├──────┼──────────────────────────────────────────────────────────────┤
│ 401  │ Authentication failed                                        │
├──────┼──────────────────────────────────────────────────────────────┤
│ 429  │ Too many requests (rate limited)                             │
├──────┼──────────────────────────────────────────────────────────────┤
│ 500  │ Server/processing error                                      │
└──────┴──────────────────────────────────────────────────────────────┘

Save the returned jobId — you’ll need it to poll the status report via GET /{custNr}/fax/reports/{jobId}.

The same search-based approach also works for other content in Retarus API Docs. For example, asking “How do I query the GraphQL Reporting API?” retrieves results from the GraphQL documentation pages.

Working with mock servers