# 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)](https://modelcontextprotocol.io), 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 Tools** | **Parameters** | **Scope & Description** | | --- | --- | --- | | `list-apis` | `filter` `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-endpoints` | `name` | **REST APIs only** Returns all endpoints and descriptions for a specific REST API. | | `get-endpoint-info` | `name` `path` `method` | **REST APIs only** Returns comprehensive details for a specific endpoint, including parameters, security schemes, and examples. | | `get-security-schemes` | `name` | **REST APIs only** Returns the authentication details for a specific REST API. | | `get-full-api-description` | `name` | **REST APIs only** Returns the complete OpenAPI description for a REST API. | | `search` | `query` | **All 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. | **API** | **Description** | | --- | --- | | Faxolution for Applications (Fax4A) REST API | Send faxes, monitor transmission status, and manage status reports. | | Fax Configuration API | Configure Mail-to-Fax, Fax-to-Email, Fax-to-FTP, and Fax-to-Webservice. | | Fax2WSPull | Actively retrieve received inbound faxes organized by topic. | | Faxolution for Applications status push notification API | Receive proactive push notifications for outbound fax job outcomes (XML or JSON). | | SMS for Applications REST API | Send SMS messages and look up delivery status. | | Transactional Email API | Submit and manage transactional email jobs. | | IDP Integration API | Upload documents and retrieve structured Intelligent Document Processing results. | | Continuity Service | Manage Email Continuity mailboxes and control failover routing. | | SEG Configuration Gateway | Manage customer configuration settings. | | Public Status API | Get 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: ```bash 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. ```bash 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** ```bash ● 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. ```bash 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. ```bash 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. ```bash 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: ```bash 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": "" } ] } 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.