# Mathfold API and MCP server

> Convert Markdown to Word (.docx), PDF or HTML from code or from an AI agent. Keys are created at https://mathfold.com/developers after signing in with Google.


Mathfold converts Markdown into Word (.docx), PDF or print-ready HTML over HTTP. The REST API and the MCP server use the same engine as the web app, so a document looks the same however it was made. The machine-readable description is at [/openapi.json](/openapi.json).

### Authentication

Create a key on this page after signing in with Google. Send it with every request:

```http
Authorization: Bearer mf_YOUR_KEY
```

The `X-API-Key: mf_YOUR_KEY` header works too. Keys count against your plan: 100 calls a month on Free (watermarked) and 1,000 a month on Pro. Each key is limited to 60 requests a minute.

### POST /v1/convert

Send raw Markdown as the body and choose options with query parameters:

```bash
curl -X POST "https://mathfold.com/v1/convert?format=docx&theme=standard" \
  -H "Authorization: Bearer mf_YOUR_KEY" \
  -H "Content-Type: text/markdown" \
  --data-binary @answer.md -o answer.docx
```

Or send JSON, which also lets you attach images that the Markdown references by file name:

```json
{
  "markdown": "# Report\n\n![chart](chart.png)\n\n$$E = mc^2$$",
  "format": "pdf",
  "options": { "theme": "academic", "pageSize": "Letter", "toc": true },
  "files": { "chart.png": "<base64>" }
}
```

| Option | Values | Default |
|---|---|---|
| `format` | `docx`, `pdf`, `html` | `docx` |
| `theme` | `standard`, `academic`, `modern`, `compact` (all but standard need Pro) | `standard` |
| `pageSize` | `A4`, `Letter`, `A5`, `A3`, `Legal` | `A4` |
| `orientation` | `portrait`, `landscape` | `portrait` |
| `autoLandscape` | `true`, `false`: give wide tables and diagrams landscape pages | `true` |
| `toc` | `true`, `false`: start with a table of contents | `false` |
| `title` | Text used when the document has no title | none |
| `mathMode` | `auto`, `latex`, `asciimath` | `auto` |

The response is the file itself, with `Content-Disposition`, `X-Watermarked` (1 or 0) and `X-Calls-Remaining` headers. Send `Accept: application/json` to get `{ filename, mime, base64, watermarked, warnings, remaining }` instead.

### Errors

Errors are JSON: `{ "error": "code", "message": "..." }`.

| Status | Code | Meaning |
|---|---|---|
| 400 | `empty_markdown`, `bad_format`, `bad_json` | The request is incomplete or malformed |
| 401 | `invalid_api_key` | Missing, wrong or revoked key |
| 402 | `quota_exceeded` | Monthly API calls used up |
| 402 | `pro_theme` | The theme needs Pro |
| 413 | `payload_too_large` | Body over 8 MB |
| 429 | `rate_limited` | Over 60 requests a minute; see `retryAfterSeconds` |

### MCP server

`https://mathfold.com/mcp` is a remote MCP server (Streamable HTTP) with one tool, `convert_markdown`. It takes `markdown` plus optional `format`, `theme`, `pageSize`, `toc` and `title`, and returns a download link that stays valid for 30 minutes. Add it to Claude Code:

```bash
claude mcp add --transport http mathfold https://mathfold.com/mcp \
  --header "Authorization: Bearer mf_YOUR_KEY"
```

Or to any client that reads an `mcp.json`:

```json
{ "mcpServers": { "mathfold": {
    "url": "https://mathfold.com/mcp",
    "headers": { "Authorization": "Bearer mf_YOUR_KEY" } } } }
```