MCP server
The CloakAPI MCP server (cloakapi-mcp) is a Model Context Protocol server that runs on your machine. It gives an AI client, or an agent you build, tools to tokenize text on the device, relay tokenized requests through the CloakAPI gateway and check receipts.
It is for developers who use MCP clients such as Claude Desktop, Claude Code, Cursor or VS Code, and for teams that build their own MCP hosts or agents. This page covers @cloakapi/mcp-server 0.6.2 on npm. The default model, when a call does not name one, is claude-haiku-5-5. The npm package bundles its own @cloakapi/sdk 1.6.1 with ruleset 1.6.1. A separately installed SDK cannot reuse the server’s process-local token-map handles or SDK-bound objects.
Requirements
- Node.js 20 or later, with npm.
- A CloakAPI API key for the tools that call the gateway. The on-device tools work without one. Create a key at app.cloakapi.io/api-keys, or get one without a browser.
The tokenizer ships inside the package as WebAssembly, so the server does not need the native engine download. It has been tested on Linux x86-64 with Node.js 20.
Install
npm install --global @cloakapi/mcp-servercloakapi-mcp@cloakapi/mcp-server 0.6.2 is on npm with the latest dist-tag. Version 0.5.1 remains on npm and bundles @cloakapi/sdk 1.5.0. The command name in the package bin is cloakapi-mcp. An npm version named 0.0.0-stage is a registry placeholder, not a release. Versions 0.4.0 and 0.4.1 stay withdrawn.
The install adds one command, cloakapi-mcp. npm installs koffi as an optional dependency for the local platform. The server tokenizes with WebAssembly, including when Koffi is unavailable.
Configure your client
Most MCP clients start the server as a local process and pass settings as environment variables. The entry looks like this:
{ "mcpServers": { "cloakapi": { "command": "cloakapi-mcp", "args": [], "env": { "CLOAKAPI_API_KEY": "cloak_your_key_here" } } }}Leave out env if you only use the on-device tools. Each client stores this in its own file and format:
If the client cannot find the command
Apps started from a desktop launcher often do not get the PATH from your shell, especially on macOS, so cloakapi-mcp or node may not be found. Use absolute paths instead: the path to node as command, and the path to the server script as the argument.
Find both paths on macOS or Linux:
which nodeecho "$(npm root -g)/@cloakapi/mcp-server/src/bin.js"On Windows, in PowerShell:
(Get-Command node).SourceJoin-Path (npm root -g) "@cloakapi\mcp-server\src\bin.js"Then put them in the entry in place of the example paths below. On Windows, write each backslash in JSON as \\.
{ "mcpServers": { "cloakapi": { "command": "/usr/local/bin/node", "args": ["/usr/local/lib/node_modules/@cloakapi/mcp-server/src/bin.js"], "env": { "CLOAKAPI_API_KEY": "cloak_your_key_here" } } }}Settings
CLOAKAPI_API_KEY is what the tools that call the gateway read. CLOAKAPI_DEFAULT_MODEL is the model private_completion, private_messages and count_tokens use when a call does not name one. A trial account can use any priced model, for example claude-haiku-5-5. CLOAKAPI_DEFAULT_TIER is balanced or max. CLOAKAPI_GATEWAY_URL must be a cloakapi.io host over https, or a loopback address. Any other host stops the server at startup. CLOAKAPI_APP_ID is an optional app identifier on relay calls. See Attribution headers. CLOAKAPI_PRETOKENISED_KEY is only for an offline MAC signer. Without it, the server asks the gateway for a MAC over each tokenized body, using your API key.
--help and -h print this list and exit before the server reads configuration. --http serves HTTP. --port selects the port. --manifest prints the discovery manifest and exits.
The names and defaults below are the same list as cloakapi-mcp --help and the package README. An empty Default cell means unset.
| Name | Default |
|---|---|
--help | |
-h | |
--http | |
--port | |
--manifest | |
CLOAKAPI_API_KEY | |
CLOAKAPI_PRETOKENISED_KEY | |
CLOAKAPI_GATEWAY_URL | https://api.cloakapi.io |
CLOAKAPI_API_PREFIX | /api |
CLOAKAPI_CHAT_PATH | /api/v1/chat/completions |
CLOAKAPI_MESSAGES_PATH | /api/v1/messages |
CLOAKAPI_MAC_PATH | /api/v1/pretokenised/mac |
CLOAKAPI_DEFAULT_MODEL | claude-haiku-5-5 |
CLOAKAPI_DEFAULT_TIER | balanced |
CLOAKAPI_TIMEOUT_MS | 60000 |
CLOAKAPI_APP_ID | |
CLOAKAPI_MCP_HOST | 127.0.0.1 |
CLOAKAPI_MCP_PORT | 9473 |
CLOAKAPI_MCP_ALLOWED_ORIGINS | |
CLOAKAPI_MCP_ALLOWED_HOSTS | |
CLOAKAPI_MCP_MAX_BODY_BYTES | 5242880 |
Tools
The server has 26 tools. The tool names use the British spelling tokenise.
| Tool | What it does | Where it runs | API key |
|---|---|---|---|
tokenise | Replaces the personal data it detects with stand-ins and returns the text with an opaque token-map handle. | Device | No |
detokenise | Puts the original values back, using a process-local token-map handle. | Device | No |
detect_pii | Counts detected values without changing the text or returning them. | Device | No |
tokenise_file | Reads a local text or markup file, or base64 content, and tokenizes the extracted text. | Device | No |
tokenise_image | Tokenizes text from an image, using local Tesseract OCR or text you pass in. | Device | No |
prepare_reviewed_prompt | Tokenizes a prompt and its attachments and returns a review summary per source. | Device | No |
reconstruct | Restores original values in a reply and rebuilds it as text, Markdown, HTML, CSV, JSON, YAML or XML. | Device | No |
engine_info | Reports the tokenizer version and hash. With check_allowlist, it also asks the gateway’s public engine list. | Device | No |
make_file | Checks a file spec and returns instructions for a host that builds the file with the CloakAPI browser SDK. | Device | No |
run_python | Checks Python code and returns instructions for a host that runs it with the CloakAPI browser SDK. | Device | No |
transcribe | Checks a local audio reference and returns instructions for a host that transcribes it with the CloakAPI browser SDK. | Device | No |
private_completion | Tokenizes the messages, sends them through the gateway in OpenAI chat format, and restores the reply. | Gateway | Yes |
private_messages | The same in Anthropic Messages format. | Gateway | Yes |
count_tokens | Tokenizes the messages, then asks the gateway for a token and cost estimate. | Gateway | Yes |
list_models | Lists the models available to your account. | Gateway | Yes |
verify_receipt | Checks a receipt signature on the device, and also asks the gateway when it can reach it. | Device and gateway | No |
get_receipt | Fetches a receipt by its ID. | Gateway | Yes, for your own receipts |
countersign_receipt | Adds your countersignature to a receipt. | Gateway | Yes |
list_receipts | Lists your account’s receipts. | Gateway | Yes |
receipt_chain_export | Exports your signed receipt chain. | Gateway | Yes |
chain_verify | Checks a receipt chain manifest. Pass a manifest you already have to skip the export call. | Device and gateway | Yes, unless you pass a manifest |
transparency_inclusion | Checks for a public inclusion proof. Proofs are available only for client-signed v3 receipts successfully anchored during gateway countersigning. | Gateway | No |
get_balance | Shows your prepaid balance. | Gateway | Yes |
usage_summary | Shows your usage and cost summary. | Gateway | Yes |
key_scopes | Lists the API key scope names. | Gateway | No |
meter | Reports a model name and token counts for billing, without content. | Gateway | Yes |
make_file, run_python and transcribe do not build files, run code or transcribe audio in this process. They return instructions that only a host built on the CloakAPI browser SDK carries out; general AI clients do not. For file and image formats, see MCP file and image tools.
The relay tools reach the model through the gateway, so calls are metered and billed to your account. A new key has a zero balance until you add credit: see Builder pricing.
What leaves the device and what does not
Your AI client talks to its own model first. Text you type into Claude Desktop, Cursor or any other client goes to that client’s model provider as usual. The client’s model decides when to call a tool, so by the time a tool runs, the model has already seen the text it passes in. CloakAPI is not between your client and its own model.
Tool results go back to the client, and most clients add them to the conversation they send to their model. In version 0.4.1, the results of tokenise, tokenise_file, tokenise_image and prepare_reviewed_prompt include the token map, which pairs each stand-in with its original value. In 0.6.2, those tools return an opaque handle for the map held in the server process. detokenise and reconstruct return original values by design, and private_completion and private_messages return replies with the original values restored.
Inside the server, the tools fall into three groups:
- On-device tools, such as
tokeniseanddetect_pii, process text in the server process on your machine and make no network call. private_completion,private_messagesandcount_tokenstokenize the messages in the server process first. The tokenized text is sent to the gateway, together with a short notice that tells the model the stand-ins are placeholders. The gateway relays the request to the model provider and does not tokenize it. The reply is restored on your machine.- The account and receipt tools send identifiers, hashes, counts and settings, not message text.
Detection runs on your device and can miss values: text the detector does not catch is sent as written, and the gateway does not check that detection ran. The built-in name list can miss uncommon names. When no name model runs, the call reports rules_only. See Known limitations.
If you build your own MCP host or agent, your code can call tokenise or private_messages directly, before any model sees the text.
Check that it works
In a terminal, print the server’s manifest:
cloakapi-mcp --manifestIt prints JSON and exits. Look for "version": "0.6.2" and a tools list with 26 names.
In your client, the cloakapi server should show as connected with 26 tools. Then ask the client:
Use the cloakapi detect_pii tool on: "Please email Jane Doe at jane.doe@example.com or call +1 415 555 0134."The result reports "entity_count": 3 and "has_pii": true. Ask for the tokenise tool on the same sentence and the text comes back with realistic stand-ins, for example richard.scott@harborline.com in place of the email address, plus an opaque handle. The token map stays in the MCP server process. Pass the returned text and handle to detokenise to restore the original values. That result includes the original values and goes back to your MCP host. In balanced mode, the default, the same input gives the same stand-ins. With mode set to max, you get opaque markers such as <<CLOAK:EMAIL:931>> instead, and the numbers change between runs; pass the same seed_hex in each call to keep replacements consistent.
Run over HTTP
For an MCP client that connects over HTTP, start the server in HTTP mode:
cloakapi-mcp --http --port 9473It listens on 127.0.0.1:9473 and accepts JSON-RPC at POST /mcp. A health check answers at /health:
curl -s http://127.0.0.1:9473/health# {"ok":true,"server":"cloakapi-mcp"}