Skip to content
Sign in Create account

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

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-server
cloakapi-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:

MCP client configuration
{
"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 node
echo "$(npm root -g)/@cloakapi/mcp-server/src/bin.js"

On Windows, in PowerShell:

(Get-Command node).Source
Join-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 \\.

MCP client configuration with absolute paths
{
"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.

NameDefault
--help
-h
--http
--port
--manifest
CLOAKAPI_API_KEY
CLOAKAPI_PRETOKENISED_KEY
CLOAKAPI_GATEWAY_URLhttps://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_MODELclaude-haiku-5-5
CLOAKAPI_DEFAULT_TIERbalanced
CLOAKAPI_TIMEOUT_MS60000
CLOAKAPI_APP_ID
CLOAKAPI_MCP_HOST127.0.0.1
CLOAKAPI_MCP_PORT9473
CLOAKAPI_MCP_ALLOWED_ORIGINS
CLOAKAPI_MCP_ALLOWED_HOSTS
CLOAKAPI_MCP_MAX_BODY_BYTES5242880

Tools

The server has 26 tools. The tool names use the British spelling tokenise.

ToolWhat it doesWhere it runsAPI key
tokeniseReplaces the personal data it detects with stand-ins and returns the text with an opaque token-map handle.DeviceNo
detokenisePuts the original values back, using a process-local token-map handle.DeviceNo
detect_piiCounts detected values without changing the text or returning them.DeviceNo
tokenise_fileReads a local text or markup file, or base64 content, and tokenizes the extracted text.DeviceNo
tokenise_imageTokenizes text from an image, using local Tesseract OCR or text you pass in.DeviceNo
prepare_reviewed_promptTokenizes a prompt and its attachments and returns a review summary per source.DeviceNo
reconstructRestores original values in a reply and rebuilds it as text, Markdown, HTML, CSV, JSON, YAML or XML.DeviceNo
engine_infoReports the tokenizer version and hash. With check_allowlist, it also asks the gateway’s public engine list.DeviceNo
make_fileChecks a file spec and returns instructions for a host that builds the file with the CloakAPI browser SDK.DeviceNo
run_pythonChecks Python code and returns instructions for a host that runs it with the CloakAPI browser SDK.DeviceNo
transcribeChecks a local audio reference and returns instructions for a host that transcribes it with the CloakAPI browser SDK.DeviceNo
private_completionTokenizes the messages, sends them through the gateway in OpenAI chat format, and restores the reply.GatewayYes
private_messagesThe same in Anthropic Messages format.GatewayYes
count_tokensTokenizes the messages, then asks the gateway for a token and cost estimate.GatewayYes
list_modelsLists the models available to your account.GatewayYes
verify_receiptChecks a receipt signature on the device, and also asks the gateway when it can reach it.Device and gatewayNo
get_receiptFetches a receipt by its ID.GatewayYes, for your own receipts
countersign_receiptAdds your countersignature to a receipt.GatewayYes
list_receiptsLists your account’s receipts.GatewayYes
receipt_chain_exportExports your signed receipt chain.GatewayYes
chain_verifyChecks a receipt chain manifest. Pass a manifest you already have to skip the export call.Device and gatewayYes, unless you pass a manifest
transparency_inclusionChecks for a public inclusion proof. Proofs are available only for client-signed v3 receipts successfully anchored during gateway countersigning.GatewayNo
get_balanceShows your prepaid balance.GatewayYes
usage_summaryShows your usage and cost summary.GatewayYes
key_scopesLists the API key scope names.GatewayNo
meterReports a model name and token counts for billing, without content.GatewayYes

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 tokenise and detect_pii, process text in the server process on your machine and make no network call.
  • private_completion, private_messages and count_tokens tokenize 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 --manifest

It 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 9473

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