Docs menu

IntegrationsMCP server

MCP server

Give your MCP client, such as Claude Code, Codex, Cursor or VS Code, tools to render Markdown and to design, preview and render templates.

The MCP server lives at https://api.legivel.com/mcp. It speaks the Streamable HTTP transport, protocol version 2025-11-25, 2025-06-18 or 2025-03-26, whichever the client asks for: POST-only, one JSON response per request, no SSE stream, no server-initiated messages, no sessions. initialize and tools/list answer without a credential. A tool call needs either the same Bearer API key the REST API takes or an OAuth access token from signing in to legivel, and runs through the same handlers, so the same account, rate limits and documents per period apply.

Connect a client#

A client that speaks Streamable HTTP works with an API key in a static Authorization header; a client that supports MCP sign-in can sign in instead. With a key, three facts are all a client needs:

EndpointTransportHeader on every request
https://api.legivel.com/mcpStreamable HTTP, POST onlyAuthorization: Bearer lgvl_…

The key is the same API key as for REST; create one on the API keys page. Keep it out of any file that goes into a repository: where the client can, the setups below read it from an environment variable; the Cline and Zed files hold the key itself and stay out of repositories. The setups are in alphabetical order; none is the default. The version named beside each is the one the setup was checked with against the service; client formats change, so check the client's own reference when yours is newer.

shell
export LEGIVEL_API_KEY="lgvl_your_key_here"

Listed on the official MCP Registry as com.legivel/legivel, with this endpoint and header; a client that reads the registry finds the same setup there. The same server is listed on Glama and mcp.so.

Claude Code

Add the server once with the CLI; the header reads the key from the environment, so the entry Claude Code writes holds no secret.

claude mcp add --transport http legivel https://api.legivel.com/mcp --header 'Authorization: Bearer ${LEGIVEL_API_KEY}'
.mcp.json
{
  "mcpServers": {
    "legivel": {
      "type": "http",
      "url": "https://api.legivel.com/mcp",
      "headers": { "Authorization": "Bearer ${LEGIVEL_API_KEY}" }
    }
  }
}

Add --scope project to write the entry to .mcp.json in the repository for the whole team; each person sets the variable.

Checked with Claude Code 2.1.

Cline

Open the MCP Servers panel, choose Configure, and add the entry to cline_mcp_settings.json; the extension and the CLI keep it at ~/.cline/data/settings/cline_mcp_settings.json. Set the type: without it Cline falls back to the older SSE transport.

cline_mcp_settings.json
{
  "mcpServers": {
    "legivel": {
      "type": "streamableHttp",
      "url": "https://api.legivel.com/mcp",
      "headers": { "Authorization": "Bearer lgvl_your_key_here" },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Cline reads no variables in headers; this file is not meant for a repository.

Checked with Cline 4.1.

Cursor

Add the entry to .cursor/mcp.json in the project, or ~/.cursor/mcp.json for every project. Cursor resolves ${env:NAME} in url and headers, so the file holds no secret; it reads the variable from the shell it was started from, so start Cursor from a shell that has it.

.cursor/mcp.json
{
  "mcpServers": {
    "legivel": {
      "url": "https://api.legivel.com/mcp",
      "headers": { "Authorization": "Bearer ${env:LEGIVEL_API_KEY}" }
    }
  }
}

Checked with Cursor 3.26.

Devin Desktop (formerly Windsurf)

Devin Desktop picks up the MCP servers set up for Claude Code on the same machine: the user-level entries and a project’s .mcp.json. Set up Claude Code as above, and legivel shows as connected under Customizations.

Checked with Devin Desktop 3.10, through the Claude Code entry.

Gemini CLI

Add the server once with the CLI. Gemini CLI expands $LEGIVEL_API_KEY in the header when the server starts, so the entry holds no secret; the default scope writes .gemini/settings.json in the project, --scope user writes ~/.gemini/settings.json.

gemini mcp add --transport http -H 'Authorization: Bearer $LEGIVEL_API_KEY' legivel https://api.legivel.com/mcp
.gemini/settings.json
{
  "mcpServers": {
    "legivel": {
      "url": "https://api.legivel.com/mcp",
      "type": "http",
      "headers": { "Authorization": "Bearer $LEGIVEL_API_KEY" }
    }
  }
}

gemini mcp list shows the server as connected once the variable is set.

Checked with Gemini CLI 0.65.

OpenAI Codex

Add the server once with the CLI. Codex reads the key from the environment variable named in bearer_token_env_var and sends it as the Authorization header, so ~/.codex/config.toml holds no secret. The Codex IDE extension and the ChatGPT desktop app read the same file.

codex mcp add legivel --url https://api.legivel.com/mcp --bearer-token-env-var LEGIVEL_API_KEY
~/.codex/config.toml
[mcp_servers.legivel]
url = "https://api.legivel.com/mcp"
bearer_token_env_var = "LEGIVEL_API_KEY"

Checked with Codex CLI 0.163.

VS Code with GitHub Copilot

Copilot’s agent reads .mcp.json at the root of the workspace, the same file Claude Code reads, and takes the key from the environment variable; start VS Code from a shell that has it. The ${input:…} key prompt of .vscode/mcp.json is not supported by Copilot’s agent; it offers to migrate such an entry to this file.

.mcp.json
{
  "mcpServers": {
    "legivel": {
      "type": "http",
      "url": "https://api.legivel.com/mcp",
      "headers": { "Authorization": "Bearer ${LEGIVEL_API_KEY}" }
    }
  }
}

The server starts with the first message of a chat; the tools are then listed under the server’s name in the chat’s tool picker.

Checked with VS Code 1.143, Copilot chat 0.71.

Zed

Add the entry under context_servers in Zed's settings.json. With the header Zed uses the API key.

settings.json
{
  "context_servers": {
    "legivel": {
      "url": "https://api.legivel.com/mcp",
      "headers": { "Authorization": "Bearer lgvl_your_key_here" }
    }
  }
}

Zed reads no variables in headers; keep this in the user settings, not in a repository's .zed/settings.json.

Checked with Zed 1.25.

Sign in instead of a key

A client that supports MCP sign-in needs only the endpoint. Its first tool call is answered 401 with the address of the server's sign-in metadata; the client then opens legivel's sign-in page, the person signs in and allows the app, and the client calls the tools with the access token it receives. The access token lasts an hour and the client renews it on its own; an app not used for 30 days asks the person to sign in again. Each app the account has allowed is listed under connected apps in the account, where it can be disconnected.

Tools#

tools/list returns ten tools. Each takes a JSON object as input. Each carries readOnlyHint and destructiveHint: get_usage, get_template_format, list_templates, get_template and preview_template only read; update_template and delete_template can overwrite or remove a template, so a client can ask before they run.

render_pdf

Render markdown to a PDF. Returns the PDF as a base64 resource, without a watermark. We generate the PDF in memory and never store your Markdown or your PDFs.

NameTypeDescription
markdownrequiredstringThe markdown source to render.
languagestringOptional document language, such as en-GB. Automatic hyphenation is enabled by default when a supported language is specified. The PDF records it as its document language. Overrides the document's front-matter language. Without either, the PDF records the main language of the text, which the converter detects, or en; that language serves the tags only, with no hyphenation. The result names the PDF's language and where it came from.
pageobjectOptional page settings: size (such as A4, A5 landscape or 210mm 99mm), margin (one to four lengths in CSS order), header and footer (a string for the center, true for the default, false, or left, center and right), numbering (a style 1, a, A, i or I, a text, false, or style, text, position and start) and first (false for a title page without them). Placeholders: {page}, {pages}, {title}, {author}. Overrides the document's front-matter page key by key. See page settings and header and footer.
format, papersize, width, height, margin, header, footer, page_numberingstring, number, false or objectThe older spelling of the page keys. They still work; a key under page wins over its older spelling.
features.hyphenationbooleanSet false to disable automatic hyphenation. An omitted value uses front matter, then defaults to enabled. No language means no automatic hyphenation. See language settings.
features.archive, features.accessible, features.mathml, features.standardsboolean | stringEvery PDF is accessible unless accessible is false, and claims PDF/UA-2 when it meets it; archive asks for PDF/A-4 as well. The result names the standards the PDF meets, the PDF's language with its source, and gives each warning as a sentence. standards: "strict" refuses a render that leaves a requested standard out. See Standards and warnings.
signobject | booleanRequest a customer seal with {certificate: name}, {p12: base64, password} or {key, cert, chain?, password?} as PEM text or Base64 DER. Optional reason, location and contact use the REST contract. true is refused with invalid_request; false or omission leaves the PDF unsealed.
idempotency_keystringThe equivalent of REST's Idempotency-Key. Follow the same retry rules; sealed retries require the prepared-resource mode and valid credentials on each attempt.

The result has one content item of type resource. Its uri is legivel://render/latest.pdf, its mimeType is application/pdf, and blob holds the PDF bytes as base64. Decode the blob to get the file. Each successful call costs one of the account's documents for the current period, except a successful idempotent replay.

A customer seal applies your certificate on your instruction, with the same plan, ownership, audit and failure rules as REST. The result includes _meta["legivel/signature"] = "signed" when the returned PDF carries the requested seal. Sealing failure never returns an unsealed PDF. The customer seal guidance explains certificate trust and the limits of the feature's legal claims.

get_usage

The current period's boundaries, the documents the plan includes, the documents granted, the plan limits and the documents used, split by API key; editor downloads are the remainder of credits_used. One optional argument, period: one of the account's usage period IDs as a decimal string, for an earlier period. The result has one content item of type text whose text is the JSON usage object, the same object GET /v1/usage returns:

{
  "plan": "free",
  "period_start": "2026-11-01T00:00:00.000Z",
  "period_end": "2026-12-01T00:00:00.000Z",
  "credits_included": 100,
  "credits_granted": 0,
  "credits_used": 3,
  "limits": {
    "markdown_kb": 512,
    "resources_mb": 1.5,
    "pages_max": 20,
    "timeout_s": 30,
    "concurrency": 1,
    "requests_per_min": 5,
    "previews_per_hour": 120
  },
  "keys": [
    { "id": "<apikey.id>", "name": "CI", "credits": 2 }
  ]
}

get_template_format

The template format as Markdown, with the formula functions, barcode types and fonts, and a list of the starter templates. No arguments. An agent reads it before it writes or changes a template body.

list_templates

The account's saved templates, as GET /v1/templates returns them: each with its id, name, revision and the fields it reads, and the plan's template limit. No arguments.

get_template

One template, as GET /v1/templates/{id} returns it: body, the editor document; the fields it reads; its revision. template is the id or the name.

create_template

Saves a new template from exactly one of markdown, html, body (an editor document, see the template format) or starter (blank, invoice, letter, label or certificate), with a name unique in the account. Templates you save are stored encrypted until you delete them. In Markdown and HTML, {{customer.name}} becomes a field. The result is the id, the revision, the fields, and left: what the import left out, such as images. A starter also answers sample: its data and csv, ready for preview_template. An agent can draft a document as Markdown, save it as a template, and render it with render_template.

update_template

Changes template. Send base_revision, the revision you read; a save in between is the tool error template_version_conflict. What you leave out stays as it was: send markdown, html or body to replace the document, name to rename it. To change one thing, read the body with get_template, edit it and send it back.

delete_template

Deletes template and its pictures for good. Renders that name it fail with not_found at once.

preview_template

Pictures of a saved template's pages, filled with sample data, so an agent sees how it looks before it renders. It does not count as a document and nothing is stored. It uses your plan's hourly preview budget, which the editor's previews share. It takes template, data and csv as render_template does, and first_page (default 1), page_count (1 to 4, default 4) and dpi (72 to 144, default 96; the longer side stays at most 1,568 pixels). The result is one image item per page (image/jpeg), then a text item with the template id, revision, the page count, the pages shown and issues. An issue is data that does not fill the template, or a layout a reader would see as broken: text that does not fit its box or table cell, an item that covers text, or an item past the page edge. Each issue names the item by its path (placed[3], blocks[6]), its page and a fix. A layout issue is a warning and never stops a render. A missing field shows as ‹path› in the picture; a graphic that does not draw shows as an empty frame. The email check and the burst limit are those of a render; the plan's hourly preview budget is shared with the editor.

The loop an agent follows: read get_template_format, create the template, preview it, change the body with update_template, preview again, and render the PDF when the pictures are right.

render_template

Fills a saved template with data and returns the PDF as a resource item, followed by a text item with the template id, revision, page count and size, and warnings with the layout problems the preview names, when there are any. The PDF is made all the same. template is the id or the name. data holds the field values, csv maps each table source to CSV text and idempotency_key makes a retry safe. Data that does not fit the template is a tool error whose _meta lists the problems under legivel/issues; nothing is counted.

Claude Code saves the PDF as a file. claude.ai and the Claude desktop app do not take PDF files from tools yet, so the PDF does not reach you there. To get the file, use Claude Code, the editor on legivel.com or the API.

Raw JSON-RPC#

You do not need an SDK. Each request is one JSON-RPC 2.0 message posted with the key in the Authorization header. The three calls below initialize, list the tools and render a small document.

# 1. initialize
curl https://api.legivel.com/mcp \
  -H "Authorization: Bearer $LEGIVEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-06-18",
      "capabilities": {},
      "clientInfo": { "name": "curl", "version": "0" }
    }
  }'

# 2. list tools
curl https://api.legivel.com/mcp \
  -H "Authorization: Bearer $LEGIVEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "jsonrpc": "2.0", "id": 2, "method": "tools/list" }'

# 3. render a PDF
curl https://api.legivel.com/mcp \
  -H "Authorization: Bearer $LEGIVEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "render_pdf",
      "arguments": { "markdown": "# Hello\n\nRendered over MCP." }
    }
  }'

The third call answers with the PDF as a base64 resource:

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "resource",
        "resource": {
          "uri": "legivel://render/latest.pdf",
          "mimeType": "application/pdf",
          "blob": "JVBERi0xLj…"
        }
      }
    ]
  }
}

The server also accepts ping, which returns an empty result. Batches work: post a JSON array of up to 10 requests and you get an array of responses back. A request with no id is a notification; a body that contains only notifications is acknowledged with HTTP 202 and no body.

Errors#

Failures inside a tool call are tool results, not protocol errors, so the calling agent can read them and decide what to do. Everything else follows JSON-RPC and HTTP.

WhereShapeCases
Tool resultisError: true, one text item reading <code>: <message>quota_exhausted, rate_limited, queue_full, render_timeout, too_many_pages, render_unavailable, quota_unavailable, render_failed, empty_document; also a missing or non-string markdown argument
JSON-RPC errorerror.code on a 200 response-32602 unknown tool, -32601 unknown method
JSON-RPC error-32700 with HTTP 400Body is not valid JSON
JSON-RPC error-32600 with HTTP 400A batch of more than 10 requests, or an empty one; none of them runs. A message without "jsonrpc": "2.0" or a method; in a batch, that message alone is answered -32600. An MCP-Protocol-Version header naming a version the server does not support
HTTP 401{"code":"unauthorized",…}, WWW-Authenticate naming resource_metadataA tool call without an API key or access token, or any request with an invalid one
HTTP 429{"code":"rate_limited",…}, Retry-AfterToo many new API keys or refused access tokens from one address; limit names key_verifications
HTTP 403{"code":"origin_not_allowed",…}Any request whose Origin header is not claude.ai, chatgpt.com or localhost. A request without an Origin header is served
HTTP 403{"code":"insufficient_scope",…}, WWW-Authenticate naming error="insufficient_scope"A tool call with an access token from a sign-in that did not allow the mcp scope
HTTP 405{"code":"method_not_allowed",…}, Allow: POST, OPTIONSAny method other than POST or OPTIONS, including GET and DELETE

Errors and quota explains what each code means, and Limits carries the numbers behind each plan.