# API key (CI and headless)

> Run the `@korala/mcp` package with a Korala API key on machines where nobody can approve a sign-in page.

Source: https://docs.korala.ai/ai-agents/api-key

---

`@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](https://docs.korala.ai/ai-agents/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

1. Create an API key in Korala under **Settings → API Keys**. Start with a test-mode key.
2. 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:

```bash
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`:

```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:

```json
{
  "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:

```bash
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](https://docs.korala.ai/guides/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](https://docs.korala.ai/ai-agents/permissions) covers the rest.