# MCP server

> Let Claude Code, Codex, Cursor and other AI agents convert local files, web pages and PDF links to Markdown, splitting files over the API limits into parts.

`@tlelabs/md-mcp` is an MCP server that lets an AI agent convert local PDF, DOCX, PPTX, XLSX and HTML files, web pages and PDF links to Markdown. It runs on your machine over stdio, reads the file from disk and sends it to `POST /v1/convert` with your API key; web pages and PDF links go to `POST /v1/fetch` and `POST /v1/fetch-pdf`.

## Set up

Create an API key under [API keys](https://md.tlelabs.com/keys) (see [Authentication](https://md.tlelabs.com/docs/authentication/)), then add the server to your client with the key in `MD_API_KEY`. Node.js 20 or newer is required.

Each command below installs the server for every project (user scope). Replace `mdw_live_...` with your key; the dashboard’s key dialog shows them with the key filled in.

**Claude Code** (`~/.claude.json`)

```sh
claude mcp add -s user md -e MD_API_KEY=mdw_live_... -- npx -y @tlelabs/md-mcp
```

**Codex** (`~/.codex/config.toml`)

```sh
codex mcp add md --env MD_API_KEY=mdw_live_... -- npx -y @tlelabs/md-mcp
```

**Antigravity** (`~/.gemini/config/mcp_config.json`; flags go before the name)

```sh
agy mcp add --env MD_API_KEY=mdw_live_... md -- npx -y @tlelabs/md-mcp
```

**Devin** (`~/.config/devin/mcp_config.json`; without `-s user` the server is saved in the project’s `.devin/`)

```sh
devin mcp add -s user md --env MD_API_KEY=mdw_live_... -- npx -y @tlelabs/md-mcp
```

**Cursor** (`~/.cursor/mcp.json`), **Claude Desktop** and other clients using `mcpServers` JSON. In Cursor, the dashboard’s **Add to Cursor** link writes the same entry after you confirm it.

```json
{
  "mcpServers": {
    "md": {
      "command": "npx",
      "args": ["-y", "@tlelabs/md-mcp"],
      "env": { "MD_API_KEY": "mdw_live_..." }
    }
  }
}
```

To raise the Codex tool timeout, add one line to the table `codex mcp add` wrote in `~/.codex/config.toml`:

```toml
[mcp_servers.md]
# ... command and args written by codex mcp add ...
tool_timeout_sec = 600
```

Long PDFs that need OCR can take a few minutes. If your client stops waiting before the conversion ends, raise its tool timeout (Codex `tool_timeout_sec`, Claude Code `MCP_TOOL_TIMEOUT` in milliseconds).

## The `convert_file` tool

| Argument                              | Description                                                                                        |
| ------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `path`                                | File to convert. Relative paths resolve against the server’s working directory                     |
| `output_path`                         | Optional. Write the Markdown to this file instead of returning it; use it for long documents       |
| `overwrite`                           | Optional. Replace `output_path` if it exists (default `false`: an existing file is never replaced) |
| `ocr`, `ocr_model`, `preserve_images` | Optional. Same as [Convert a file](https://md.tlelabs.com/docs/convert/)                           |

The result holds the Markdown (or the path it was saved to) and a summary: format, pages, OCR pages, credits charged and remaining, and warnings.

### Large files

A file the API refuses as too large is split into parts on your machine. This covers a file over 50 MB, a PDF over 500 pages or one that needs more OCR than one request allows, a PPTX over 200 slides, an XLSX over 50 sheets, and a PPTX, XLSX, DOCX or HTML file over the XML limits of [Formats and pricing](https://md.tlelabs.com/docs/formats-and-pricing/). Each part is converted and the Markdown is joined in source order; each part is at most 50 MB. The summary says the file was split into parts and names each part (`pages 1–500`, `slides 201–260`, `sheet "Data" rows 1–30000`…).

The output can lose some quality where parts meet:

- text spanning two parts may be split, so a paragraph or a table can break at the join;
- a PDF part keeps its pages but loses the outline (bookmarks) and page labels;
- an XLSX run of rows loses merged cells and hyperlinks;
- names that point across parts are dropped (defined names, the active sheet).

A part that cannot be converted is listed in the summary as `Not converted`, and the other parts are still returned. If your credits run out midway, the parts already converted are returned and the summary says where it stopped.

## The `fetch_url` tool

Renders a web page and converts it, like [Convert a web page](https://md.tlelabs.com/docs/fetch/).

| Argument                   | Description                                                                |
| -------------------------- | -------------------------------------------------------------------------- |
| `url`                      | Public `http`/`https` URL of the page                                      |
| `output_path`, `overwrite` | Optional. As for `convert_file`                                            |
| `preserve_images`          | Optional. Same as [Convert a web page](https://md.tlelabs.com/docs/fetch/) |

## The `convert_pdf_url` tool

Downloads a PDF from a link and converts it, like [Convert a PDF from a link](https://md.tlelabs.com/docs/fetch-pdf/). A PDF the API refuses as too large (over 50 MB or 500 pages) is downloaded by the MCP server and split into parts like a local file. The server downloads it only from a public address; an address on your network is refused, after every redirect and every DNS lookup. The parts are charged like `convert_file`, with no download fee.

| Argument                              | Description                                                              |
| ------------------------------------- | ------------------------------------------------------------------------ |
| `url`                                 | Public `http`/`https` URL of the PDF                                     |
| `output_path`, `overwrite`            | Optional. As for `convert_file`                                          |
| `ocr`, `ocr_model`, `preserve_images` | Optional. Same as [Convert a file](https://md.tlelabs.com/docs/convert/) |

The result of both tools holds the Markdown (or the path it was saved to) and a summary with the final URL, pages and credits.

## Billing

Every call is a new conversion and is charged like `POST /v1/convert`: 1 credit per page, 15 credits per OCR page with `ocr_model=auto` ([pricing](https://md.tlelabs.com/docs/formats-and-pricing/)). `fetch_url` costs 5 credits per fetch, whatever the length of the page; `convert_pdf_url` costs the PDF price plus 5 credits. Calling again with the same file or URL is charged again. A split file is charged for the pages of every part. For PDF and PPTX that is the same total as the whole file. DOCX, XLSX and HTML count a page per 3,000 characters in each part, so each part may add one page from rounding.

The server retries a request on its own only in these cases:

- a part the API refused as too large is split in half and sent again; a refused request is not charged;
- a rate-limited part is sent again after the wait the API asks for;
- a part whose response was lost (a dropped connection, or a server error without the API’s answer) is sent again alone, up to 2 times. The lost response may already have been charged, so such a part may be charged twice. The summary names each part that was sent again; check [Usage](https://md.tlelabs.com/usage).

Checks that fail locally (missing file, a file over 50 MB that cannot be split, `output_path` already exists) run before upload and cost nothing. If the connection drops, the result says the conversion may have been charged: check [Usage](https://md.tlelabs.com/usage) before converting again.

## Environment

| Variable      | Required | Default                      |
| ------------- | -------- | ---------------------------- |
| `MD_API_KEY`  | yes      | —                            |
| `MD_API_BASE` | no       | `https://api.md.tlelabs.com` |
