Use Tickmarks from an AI assistant

Tickmarks is also an MCP server, so an AI assistant can extract and check document data for you without you writing any API code. The server is https://api.tickmarks.nl/mcp, over Streamable HTTP. It is a thin layer over the v1 API: the same checks, the same responses and the same usage.

You authenticate with an API key, sent as Authorization: Bearer tmk_…. Sign up and create a key in the panel if you don’t have one yet. The panel’s MCP page, https://app.tickmarks.nl/mcp, has the snippets below with your key already filled in.

Tools

Tool	Arguments	Does
`extract`	`document`, `schema`, `language?`, `reference?`	Runs a document through a schema and returns the extraction, like `POST /v1/extractions`.
`validate_schema`	`schema`	Compiles a schema and returns its errors or warnings, like `POST /v1/schemas/validate`.
`list_schemas`		Lists your saved schemas.
`get_schema`	`id`	Returns one saved schema.
`get_usage`	`from?`, `to?`	Reports your reads and input tokens for a period.
`list_docs`		Lists the available Tickmarks documentation pages and their source URLs.
`search_docs`	`query`, `limit?`	Finds documentation by words or phrase and returns excerpts and source URLs.
`get_doc`	`id`	Returns the full Markdown for one documentation page.

Read and explain the documentation

The assistant can retrieve Tickmarks documentation directly through MCP. Ask, for example:

“Read the schema docs and explain how to check that an invoice total equals net plus VAT.”
“Look up how Tickmarks confidence works. Is it a calibrated probability?”
“Read the response guide and explain the conflict in this extraction, using its evidence.”

The assistant can call list_docs to find page ids, search_docs with a query such as confidence or date relations, and get_doc with an id such as schemas/overview or responses/reading-responses. Search accepts up to 200 characters and returns at most 10 matching pages (limit defaults to 5), each with an excerpt. get_doc returns the complete page and its public URL so the assistant can cite its source.

The same pages are available as MCP resources under tickmarks://docs/, for clients that support resource browsing. Documentation is bundled with the API release, so retrieval works without a request to another website. It uses no reads and works with any valid API key, regardless of its extraction or validation scopes.

When explaining a response, the assistant should distinguish resolved values, values derived from relations, missing evidence and conflicts. Confidence is model-relative, not a calibrated probability. A conflict needs review of the evidence; the assistant should not quietly choose a value. See Reading responses for the full interpretation guide.

These tools retrieve Tickmarks documentation. They do not fetch arbitrary websites, PDFs or scans; provide source-document text to extract as described below.

Each extract uses reads exactly as an API call does: a read is one pass of Hydra Extract over up to 4,096 tokens of schema plus document, and the result reports usage. validate_schema runs no model and uses no reads. The document is text, so an assistant that holds a PDF or a scan needs to turn it into text first (see Scans, photos and PDFs).

Set up your client

Replace tmk_YOUR_KEY with your API key in each snippet.

Claude Code

claude mcp add --transport http tickmarks https://api.tickmarks.nl/mcp --header "Authorization: Bearer tmk_YOUR_KEY"

Run claude mcp list to check that tickmarks is connected.

Claude Desktop

Claude Desktop reads local servers from its config file, and the file has no field for headers on a remote server. Bridge the remote server with the mcp-remote package instead. Open Settings, then Developer, then Edit config, and add this to claude_desktop_config.json. It needs Node.js installed.

{
  "mcpServers": {
    "tickmarks": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.tickmarks.nl/mcp",
        "--header",
        "Authorization:${TICKMARKS_AUTH}"
      ],
      "env": { "TICKMARKS_AUTH": "Bearer tmk_YOUR_KEY" }
    }
  }
}

Restart Claude Desktop afterwards.

Cursor

Add a remote server to ~/.cursor/mcp.json, or to .cursor/mcp.json in a project:

{
  "mcpServers": {
    "tickmarks": {
      "url": "https://api.tickmarks.nl/mcp",
      "headers": { "Authorization": "Bearer tmk_YOUR_KEY" }
    }
  }
}

Any other client

Any client that supports remote MCP servers over Streamable HTTP works. Give it:

URL: https://api.tickmarks.nl/mcp
Transport: Streamable HTTP
Header: Authorization: Bearer tmk_YOUR_KEY

The server is stateless, so there is no session to keep alive between calls. If your client only speaks stdio, bridge the URL with mcp-remote as in the Claude Desktop example.

Keep your key safe

Anyone who holds the key can run extractions that use your reads. Config files like the ones above often end up in version control, so keep them out of it, and revoke a key in the panel as soon as it leaks. Give a key its own name per client, so you can revoke one without breaking the others.