# Markdown Toc — MCP tool `findutils:markdown_toc`

Build a nested Markdown table of contents from a document's headings, with GitHub-style anchor links by default (or GitLab anchors, or plain labels), and return both the TOC and the document with the TOC inserted. Reads ATX (#) and Setext (=== / ---) headings; skips headings inside fenced and indented code blocks, HTML comments and front matter. Repeated headings get the anchors the host gives them (#setup, #setup-1). The TOC replaces a [TOC] line or fills <!-- toc --> ... <!-- tocstop -->; with no marker it goes after a leading H1, else at the top. A one-shot insert: nothing watches the file.

- Category: text
- MCP server: https://mcp.findutils.com/ (Streamable HTTP, API key for tools/call, 120 req/min per IP)
- REST endpoint: POST https://api.findutils.com/api/tools/markdown-toc/execute (API key, 60 req/min per IP)
- API key: Running a tool needs an API key. Keys are not for sale yet: ask for early access. Without a key, a tool call answers HTTP 402 Payment Required with the error code PAYMENT_REQUIRED. The catalog and the schemas stay open without a key. https://findutils.com/api/#api-keys
- Reference page: https://findutils.com/mcp/markdown-toc/
- Same tool on the other surface: https://findutils.com/api/markdown-toc/

## Connect

```bash
claude mcp add findutils --transport http https://mcp.findutils.com/ --header "Authorization: Bearer YOUR_API_KEY"
```

Claude Desktop (`claude_desktop_config.json`):

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

## Call the tool (verified example)

```bash
curl -X POST https://mcp.findutils.com/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "markdown_toc",
      "arguments": {
        "markdown": "# Project\n\n## Install\n\n## Usage\n\n### Options\n\n## Setup\n\n## Setup\n"
      }
    }
  }'
```

## Input schema

| Argument | Type | Required | Description |
|---|---|---|---|
| `markdown` | string | yes | The Markdown document. |
| `slug_style` | string (github \| gitlab \| plain) | no | Anchor rules: github (default), gitlab, or plain (labels without links). Default: `"github"`. |
| `min_level` | integer | no | Shallowest heading level listed, 1 to 6. Default 2, which leaves out a lone title H1. Default: `2`. |
| `max_level` | integer | no | Deepest heading level listed, 1 to 6. Default 4. Default: `4`. |
| `bullet` | string (- \| * \| 1.) | no | List marker: - (default), *, or 1. for a numbered list. Default: `"-"`. |
| `indent` | integer (2 \| 4) | no | Spaces per nesting level: 2 (default) or 4. A numbered list uses at least 3, which Markdown needs to nest under "1. ". Default: `2`. |
| `ignore_code_blocks` | boolean | no | Skip # lines inside fenced and indented code blocks. Default true. Default: `true`. |
| `add_heading` | boolean | no | Put a "## Table of Contents" heading above the list. Default false. Default: `false`. |

Example arguments (verified):

```json
{
  "markdown": "# Project\n\n## Install\n\n## Usage\n\n### Options\n\n## Setup\n\n## Setup\n"
}
```

## Also a REST endpoint

```bash
curl -X POST https://api.findutils.com/api/tools/markdown-toc/execute \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "markdown": "# Project\n\n## Install\n\n## Usage\n\n### Options\n\n## Setup\n\n## Setup\n"
  }'

# Parameter schema (no key needed)
curl https://api.findutils.com/api/tools/markdown-toc
```

Full REST reference: https://findutils.com/api/markdown-toc/ · OpenAPI 3.1 spec: https://findutils.com/api/openapi.json

---
Full catalog: POST https://mcp.findutils.com/ with method `tools/list` · https://findutils.com/mcp/ · https://findutils.com/llms.txt