{"openapi":"3.1.0","info":{"title":"mcpfax","version":"1.1.0","description":"Send real faxes worldwide from ChatGPT. Prepaid, no subscription: EUR 1.00 first page + EUR 0.20 per additional page (zone 1, incl. VAT). Always call getFaxPrice first and ask the user to confirm before sendFax."},"servers":[{"url":"https://mcpfax.de/api/v1"}],"paths":{"/fax/price":{"post":{"operationId":"getFaxPrice","summary":"Check price, pages and fax number before sending (sends nothing, free)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"recipient_fax_number":{"type":"string","description":"Recipient fax number exactly as given by the user, e.g. \"+43 1 2345678\" or \"01 2345678\". Never invent a number; if the user only names a saved recipient, omit it and pass recipient_name (resolved from the address book)."},"recipient_name":{"type":"string"},"openaiFileIdRefs":{"type":"array","items":{"type":"string"},"description":"The file(s) the user uploaded in this chat that should be faxed (PDF, JPG, PNG, DOCX). Only the first file is used."},"content":{"type":"string","description":"Fax text if there is no uploaded file (markdown or plain text), e.g. a letter you wrote for the user."},"content_format":{"type":"string","enum":["markdown","text"]},"cover_page":{"type":"boolean","description":"Add a cover page (+1 page)."},"send_at":{"type":"string","description":"Optional: send later instead of now (e.g. \"in 10 days\"). ISO 8601 date-time, preferably with UTC offset, e.g. \"2026-10-31T09:00:00+01:00\"; a date only means 09:00 local time; max. 365 days ahead. The amount is reserved now and refunded if cancelled before sending."},"timezone":{"type":"string","description":"Optional IANA time zone for send_at without offset, e.g. \"Europe/Berlin\"."}}}}}},"responses":{"200":{"description":"Quote","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/fax/send":{"post":{"operationId":"sendFax","summary":"Send the fax. External side effect that charges the balance – only after the user explicitly confirmed recipient, number, document and cost.","x-openai-isConsequential":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"recipient_fax_number":{"type":"string","description":"Recipient fax number exactly as given by the user, e.g. \"+43 1 2345678\" or \"01 2345678\". Never invent a number; if the user only names a saved recipient, omit it and pass recipient_name (resolved from the address book)."},"recipient_name":{"type":"string"},"subject":{"type":"string"},"cover_message":{"type":"string"},"idempotency_key":{"type":"string","description":"Unique key per send request; reuse on retries so the fax is never sent twice."},"max_cost":{"type":"number"},"openaiFileIdRefs":{"type":"array","items":{"type":"string"},"description":"The file(s) the user uploaded in this chat that should be faxed (PDF, JPG, PNG, DOCX). Only the first file is used."},"content":{"type":"string","description":"Fax text if there is no uploaded file (markdown or plain text), e.g. a letter you wrote for the user."},"content_format":{"type":"string","enum":["markdown","text"]},"cover_page":{"type":"boolean","description":"Add a cover page (+1 page)."},"send_at":{"type":"string","description":"Optional: send later instead of now (e.g. \"in 10 days\"). ISO 8601 date-time, preferably with UTC offset, e.g. \"2026-10-31T09:00:00+01:00\"; a date only means 09:00 local time; max. 365 days ahead. The amount is reserved now and refunded if cancelled before sending."},"timezone":{"type":"string","description":"Optional IANA time zone for send_at without offset, e.g. \"Europe/Berlin\"."}}}}}},"responses":{"200":{"description":"Fax handed over","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"402":{"description":"Balance too low","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/fax/{fax_id}":{"get":{"operationId":"getFaxStatus","summary":"Delivery status of a fax","parameters":[{"name":"fax_id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Status","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/fax/{fax_id}/resend":{"post":{"operationId":"resendFax","summary":"Send a previous fax again (only after confirmation)","x-openai-isConsequential":true,"parameters":[{"name":"fax_id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Fax handed over","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/fax/{fax_id}/cancel":{"post":{"operationId":"cancelScheduledFax","summary":"Cancel a scheduled fax before it is sent (full refund; only after confirmation)","x-openai-isConsequential":true,"parameters":[{"name":"fax_id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Cancelled","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"409":{"description":"Not scheduled anymore","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/faxes":{"get":{"operationId":"getFaxHistory","summary":"List sent faxes","parameters":[{"name":"limit","in":"query","schema":{"type":"integer"}},{"name":"since","in":"query","schema":{"type":"string","description":"YYYY-MM-DD"}}],"responses":{"200":{"description":"History","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/contacts":{"get":{"operationId":"findContact","summary":"Search the fax address book by name (use when the user names a recipient without a number)","parameters":[{"name":"q","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"Contacts","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}},"post":{"operationId":"saveContact","summary":"Save a recipient in the address book (only numbers the user provided or confirmed)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","fax_number"],"properties":{"name":{"type":"string"},"fax_number":{"type":"string"},"note":{"type":"string"},"contact_id":{"type":"integer"}}}}}},"responses":{"200":{"description":"Saved contact","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/balance":{"get":{"operationId":"getAccountBalance","summary":"Prepaid balance, prices and top-up link","responses":{"200":{"description":"Balance","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}}},"components":{"schemas":{},"securitySchemes":{"oauth":{"type":"oauth2","flows":{"authorizationCode":{"authorizationUrl":"https://mcpfax.de/oauth/authorize.php","tokenUrl":"https://mcpfax.de/oauth/token.php","scopes":{"fax":"Send faxes and read fax status"}}}}}},"security":[{"oauth":["fax"]}]}