API key (CI and headless)

@korala/mcp is an npm package that runs the Korala MCP server on your machine over stdio. It authenticates with a Korala API key and offers the same tools as the hosted server.

Setup

Create an API key in Korala under Settings → API Keys. Start with a test-mode key.
Add the server to your client with the key in its environment. The examples name the server korala-local, which keeps it apart from a signed-in korala connection.

Documents that a test-mode key creates are unbilled and send no email, and their completed PDFs carry a TEST watermark. Test mode allows 10 sends and 10 documents created from a template per billing period, on every plan. After that the API answers with a quota error, and the assistant reports it.

Claude Code:


claude mcp add korala-local \
  --env KORALA_API_KEY_ID=your-key-id \
  --env KORALA_API_SECRET=your-secret \
  -- npx -y @korala/mcp

Codex, in ~/.codex/config.toml:


[mcp_servers.korala-local]
command = "npx"
args = ["-y", "@korala/mcp"]
env = { KORALA_API_KEY_ID = "your-key-id", KORALA_API_SECRET = "your-secret" }
required = true

required = true makes Codex wait for the server before it builds a turn’s tools. See Codex.

Cursor, Claude Desktop and other clients with a JSON config:


{
  "mcpServers": {
    "korala-local": {
      "command": "npx",
      "args": ["-y", "@korala/mcp"],
      "env": {
        "KORALA_API_KEY_ID": "your-key-id",
        "KORALA_API_SECRET": "your-secret"
      }
    }
  }
}

Environment variables

Variable	Required	Purpose
`KORALA_API_KEY_ID`	For everything except draft links	Key ID
`KORALA_API_SECRET`	For everything except draft links	Key secret
`KORALA_MCP_ALLOW_SEND`	No. Default `false`	`true` lets the assistant send documents to signers and void them. With `false`, `send_document` and `void_document` return a link so you review and act in Korala.
`KORALA_API_URL`	No	Defaults to `https://api.korala.ai/api/v1`
`KORALA_WEB_URL`	No	Defaults to `https://korala.ai`. The server builds review links and draft links from it.

The server exits at startup in two cases: you set one of the two key variables without the other, or KORALA_MCP_ALLOW_SEND holds a value other than true or false.

KORALA_MCP_ALLOW_SEND stands in for the Send and void documents permission of a signed-in connection. The other three permissions have no equivalent here.

Draft-only mode

Start the server with no key and it runs in draft-only mode. It offers one tool, create_draft_link, which needs no Korala account:


claude mcp add korala-local -- npx -y @korala/mcp

The assistant writes a Markdown agreement and returns an “Open in Korala” link. Open the link, review the rendered draft and choose Save in Korala, where you sign in or create an account. Korala saves and sends nothing until you do.

Anyone with the link can read the draft. Use example data in it, and keep credentials and private customer data out. The syntax matches Markdown templates.

Safety

The assistant cannot sign for anyone. Tool results leave out signer access tokens, the credential a signing link carries. Permissions and safety covers the rest.