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
searchquery
product		All content
Searches the full documentation set, including the complete GraphQL Reporting API documentation, Markdown pages, and REST API references. Returns the full content of matching pages.
Use the optional product parameter to filter results by a specific product.
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.
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 Docs MCP server exposes the complete Retarus API documentation to a connected AI tool. This includes all REST API references, the full GraphQL Reporting API documentation, and every guide, concept, and reference page.

There are two ways to retrieve that content:

  • All content: full search access
    The search tool works across the entire content set, including the REST API references, the complete GraphQL Reporting API documentation, and all Markdown-based pages. A single query returns the full content of the matching pages, including field references, request and response fields, and examples.
  • REST APIs: structured navigation
    In addition to search, Retarus REST APIs published as OpenAPI descriptions support the API Catalog tools. These give structured, queryable access, so an AI tool can browse endpoints, inspect parameters, retrieve security schemes, and get full OpenAPI definitions without composing a search query.

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 an 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}.

Search across GraphQL documentation

The same search tool retrieves the full GraphQL Reporting API documentation. A natural-language request is enough for an AI tool to build a runnable query.

Prompt

Show me all outbound faxes from last month for billing codes FIN and OPS, with the destination country, delivery status, and page count per job. Generate everything I need to run this in Altair.

Result
The AI calls search, retrieves the full faxOutUdrReport reference from the GraphQL documentation, and returns a parameterized query, its variables, and an example response, ready to run in Altair.

Generated query

query faxOutUdrReport(
  $customerId: String!
  $filterFax: FaxOutColumnUdrFilters
  $datePeriod: DatePeriod!
  $pageIndex: Int
  $pageSize: Int
) {
  faxOutUdrReport(
    customerId: $customerId
    datePeriod: $datePeriod
    filter: $filterFax
    page: $pageIndex
    size: $pageSize
  ) {
    content {
      jobId
      faxId
      jobBillingCode
      calledCountry
      statusName
      statusReason
      docPages
      sumPagesTransmitted
      jobSubmittedAt
    }
    pageIndex
    pageSize
    hasMoreElements
  }
}

Variables

{
  "customerId": "retarus-0123456789",
  "datePeriod": {
    "fromIncluded": "2026-06-01T00:00:00.000Z",
    "toExcluded": "2026-07-01T00:00:00.000Z"
  },
  "filterFax": {
    "jobBillingCode": { "values": ["FIN", "OPS"] }
  },
  "pageIndex": 0,
  "pageSize": 20
}

Example response

{
  "data": {
    "faxOutUdrReport": {
      "content": [
        {
          "jobId": "MF6A1D02C1123BD5850000",
          "faxId": "MN6A1D02C45A1C0735006F",
          "jobBillingCode": "FIN",
          "calledCountry": "DEU",
          "statusName": "OK",
          "statusReason": "OK",
          "docPages": 2,
          "sumPagesTransmitted": 2,
          "jobSubmittedAt": "2026-06-01T03:55:45Z"
        },
        {
          "jobId": "MF6A1D04785DD788D50000",
          "faxId": "MN6A1D047B5391010C0098",
          "jobBillingCode": "OPS",
          "calledCountry": "DEU",
          "statusName": "OK",
          "statusReason": "OK",
          "docPages": 1,
          "sumPagesTransmitted": 1,
          "jobSubmittedAt": "2026-06-01T04:03:03Z"
        },
        {
          "jobId": "MF6A1D0594215D561F0000",
          "faxId": "MN6A1D059728DFF5B700CE",
          "jobBillingCode": "FIN",
          "calledCountry": "DEU",
          "statusName": "OK",
          "statusReason": "OK",
          "docPages": 7,
          "sumPagesTransmitted": 7,
          "jobSubmittedAt": "2026-06-01T04:07:49Z"
        }
      ],
      "pageIndex": 0,
      "pageSize": 20,
      "hasMoreElements": true
    }
  }
}

Replace customerId with your own customer number, and configure the GraphQL endpoint and authentication in Altair before running the query. The AI tool resolves the correct query structure, filter syntax, and field names from the GraphQL documentation, so a plain-language request returns a working query without manual lookup.

The same search-based approach works for every content type in Retarus API Docs. A single query returns the full content of the matching pages, whether they document a REST API, the GraphQL Reporting API, or a Markdown guide.

Working with mock servers