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.

Sign-in is the recommended method. An API key has no per-connection permissions, and its secret sits in a config file. A signed-in connection keeps secrets out of config files and lets you disconnect it with one click. Use this package for CI and headless environments where nobody can approve a sign-in page.

Setup

Korala publishes @korala/mcp to npm at launch. Until then, npx -y @korala/mcp finds no package. Build the server from a checkout of the Korala repository with pnpm --filter @korala/mcp... build, then run node packages/mcp/dist/bin.js in place of npx -y @korala/mcp.

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.

A test-mode API key can still open and send live documents by their ID. Korala knows about this gap. Treat any API key as able to reach live documents. A signed-in assistant connection has no test mode: it works with live documents and cannot see test documents.

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" }

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.