MCP server

The MCP server lives at https://api.legivel.com/mcp. It speaks the Streamable HTTP transport, protocol version 2025-06-18: POST-only, one JSON response per request, no SSE stream, no server-initiated messages, no sessions. Authentication is the same Bearer API key the REST API takes, and every tool call runs through the same handlers, so the same account, rate limits and documents per period apply.

Connect a client#

Claude Code

Register the server once with the CLI. The --header value is the Authorization header sent on every request.

claude mcp add --transport http legivel https://api.legivel.com/mcp --header "Authorization: Bearer lgv_your_key_here"

Claude Desktop and other clients

Clients that read an mcpServers map take an HTTP entry with the URL and a static header:

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

Tools#

tools/list returns two tools. Both take a JSON object as input.

render_pdf

Render markdown to a PDF. Returns the PDF as a base64 resource, without a watermark.

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-09-09T00:00:00.000Z",
  "period_end": "2026-10-09T00: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 }
  ]
}

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 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.

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