Claude (MCP)

The ROOTKey MCP server connects Claude to your ROOTKey workspace. It implements the Model Context Protocol, the open standard Claude uses to talk to external systems, and exposes the entire documented ROOTKey REST API as tools Claude can call. Ask Claude to anchor a contract, check whether a file still matches its proof, pull the audit trail for a record, or build a recovery point, and it happens in your real workspace. Every tool call is an ordinary API request made with your own API key, so everything the server does is visible in the ROOTKey dashboard and subject to the same permissions, quotas and audit logging as any other API client.

The server runs locally on your machine and talks directly to api.rootkey.ai. Your API key stays in your own environment - it is never sent to Anthropic or to ROOTKey by any route other than the normal API call.

Requirements

Node.js 20 or newer on the machine running Claude
A ROOTKey API key, created in the platform under Developer Tools -> API Keys

See API Keys for how to create one. Use a test API key while you try things out: it works on your organization’s test data, kept separate from your live data, and files are anchored on a Polygon test network rather than Polygon Mainnet. Test requests still count toward your plan’s usage limits. See Test and Live Data.

Let your agent set it up

If you already have a coding agent open, hand it this URL and it will install and configure the server itself, in whichever client you use:

https://docs.rootkey.ai/agent-setup/prompt.md

Those instructions are published as the Agent Setup page, so you can read exactly what your agent is being told to do. To set it up by hand instead, follow the steps below.

Install

Claude Code
Claude Desktop
Shared with a team

Run this once, from anywhere:

claude mcp add rootkey --env ROOTKEY_API_KEY=your_api_key -- npx -y @rootkey/mcp

Start a new session and ask Claude what ROOTKey tools it has.

Open Settings -> Developer -> Edit Config and add the server to claude_desktop_config.json:

{
  "mcpServers": {
    "rootkey": {
      "command": "npx",
      "args": ["-y", "@rootkey/mcp"],
      "env": { "ROOTKEY_API_KEY": "your_api_key" }
    }
  }
}

On Windows, route the command through cmd so npx resolves correctly:

{
  "mcpServers": {
    "rootkey": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@rootkey/mcp"],
      "env": { "ROOTKEY_API_KEY": "your_api_key" }
    }
  }
}

Restart Claude Desktop for the change to take effect.

Commit a .mcp.json file at the root of your repository and let each person supply their own key from their environment:

{
  "mcpServers": {
    "rootkey": {
      "command": "npx",
      "args": ["-y", "@rootkey/mcp"],
      "env": { "ROOTKEY_API_KEY": "${ROOTKEY_API_KEY}" }
    }
  }
}

Never commit the key itself. API keys carry the full privileges of the account that created them.

Configuration

Every setting is an environment variable on the server process.

Variable	Default	Description
`ROOTKEY_API_KEY`	required	Your ROOTKey API key. The server exits immediately if it is missing.
`ROOTKEY_ENV`	`production`	Optional. `production` is the only accepted value, and the server refuses to start with `development`. ROOTKey has one public API.
`ROOTKEY_API_URL`	-	Full base URL including the `/api-v1/` path. Use it for a self-hosted or on-premise deployment. Plain `http://` is accepted only for loopback hosts, since the key travels in a header.
`ROOTKEY_READ_ONLY`	`false`	When `true`, only the read tools are registered, and downloads may only write inside `ROOTKEY_DOWNLOAD_DIR`.
`ROOTKEY_TIMEOUT_MS`	`30000`	Timeout for ordinary requests, in milliseconds.
`ROOTKEY_TRANSFER_TIMEOUT_MS`	`300000`	Timeout for uploads and downloads, in milliseconds.
`ROOTKEY_DOWNLOAD_DIR`	`~/Downloads`	Where downloads are saved when no path is given.
`ROOTKEY_ALLOWED_DIRS`	home, temp, cwd	Directories uploads may read from, separated by `;` on Windows and `:` elsewhere.
`ROOTKEY_LOG_LEVEL`	`info`	`silent`, `error`, `warn`, `info` or `debug`. Logs are written to stderr.

There is one public API, https://api.rootkey.ai/api-v1/, and no separate development environment. To try things out, use a test API key: it works on your organization’s test data, kept separate from your live data. See Test and Live Data. A ROOTKEY_ENV=development left over from an earlier version of the server is rejected with a configuration error; remove the variable.

Available tools

27 tools: every operation in the API Reference, plus a wait helper and one local diagnostic. Every tool name is prefixed rootkey_, so it cannot be confused with a same-named tool from another MCP server in the same session.

Vaults

Tool	What it does
`rootkey_create_vault`	Create a vault and return its address
`rootkey_update_vault`	Rename a vault or change its description
`rootkey_delete_vault`	Move a vault and its files to the trash, recoverable until retention purges them

Files

Tool	What it does
`rootkey_list_files`	List files in a vault, filtered by name, date range or anchoring status
`rootkey_upload_file`	Upload a local file into a vault and anchor it
`rootkey_get_file`	Fetch one file with its hashes, transaction details and usage metrics
`rootkey_download_file`	Download a file to local disk
`rootkey_delete_file`	Move a file to the trash, recoverable until retention purges it
`rootkey_list_file_versions`	List every version of a file
`rootkey_upload_file_version`	Upload a new version of an existing file
`rootkey_validate_file`	Check a local copy against the anchor and return ownership, integrity and validity
`rootkey_get_file_history`	Read the activity log for a file
`rootkey_get_file_validations`	List past validations, with current and previous hashes
`rootkey_generate_file_audit_report`	Queue a NIS2 or DORA compliance report

Records

Tool	What it does
`rootkey_list_records`	List records in a table with their metadata
`rootkey_create_record`	Write a record, or a new version of one
`rootkey_list_record_versions`	List every version of a record
`rootkey_get_record_history`	Read the activity log for a record
`rootkey_get_record_validations`	List past validations of a record
`rootkey_delete_record`	Move a record to the trash, recoverable until retention purges it

Data recovery

Tool	What it does
`rootkey_list_recovery_points`	List all recovery points
`rootkey_create_recovery_point`	Start building an encrypted backup archive
`rootkey_get_recovery_point`	Check build status and progress
`rootkey_wait_for_recovery_point`	Wait for the archive to finish building, reporting progress while it waits
`rootkey_download_recovery_point`	Download the encrypted archive
`rootkey_delete_recovery_point`	Permanently delete a recovery point

Diagnostics

Tool	What it does
`rootkey_get_environment_info`	Report the API base URL, what the server can tell about the key, and the tool count. Makes no API call and never reveals the key

Prompts

Besides the tools, the server offers four prompts: whole workflows your client can list, so you do not have to remember the sequence.

Prompt	What it does
`anchor_folder`	Anchors every file in a local folder into a vault, confirming first and reporting what landed
`compliance_evidence_pack`	Gathers the anchor, activity history, validations and version chain for one file, and writes it up
`verify_local_copies`	Validates local files against their anchors and leads with the failures
`backup_workspace`	Creates a recovery point, waits for it, downloads it, and handles the one-time password carefully

In read-only mode only compliance_evidence_pack is offered, since the other three write.

What to expect when using it

A few behaviours are worth knowing before your first session, because they follow from how the ROOTKey API works. Vault addresses come from the dashboard. The API has no endpoint that lists vaults, so the server cannot offer that tool. Claude will ask you for the address of the vault you mean. When rootkey_create_vault makes a new one, keep the address it returns. Files move through your own machine. Uploads read from the local disk of the computer running the server, and downloads are written there and reported back as a file path. File contents are never pasted into the conversation, so a large PDF costs you nothing in context. File anchoring is asynchronous. A newly uploaded file starts as PENDING and becomes REGISTERED once the anchor is confirmed, or FAILED if something went wrong. The create call returns before that happens. Only files are anchored on chain. Records are stored, hashed and audited, and come back REGISTERED immediately: there is no pending phase and no transaction hash for a record. Uploads can only read from a few directories. A file to be uploaded must sit in your home directory, the temp directory or wherever the server was started, and hidden directories inside those are refused. This matters because the path can be chosen by the model, and the model reads documents other people wrote. Widen it with ROOTKEY_ALLOWED_DIRS. Records are versioned by primary key. Creating a record whose key column matches an existing record adds a version to it rather than creating a duplicate. Asking Claude to “try that again” after a create will produce a second version, which is usually not what you want. Compliance reports arrive in the dashboard. rootkey_generate_file_audit_report queues the job and returns a report id. There is no API endpoint that returns the finished report, so collect it from the platform.

Safety

Deletions need your confirmation. rootkey_delete_vault, rootkey_delete_file and rootkey_delete_record move the item to the trash: it leaves every listing at once and stays recoverable from the Restore Center until the retention policy purges it. rootkey_delete_recovery_point is the exception and cannot be undone by anyone. Every delete is recorded in the activity log; a file that was anchored keeps its on-chain proof either way. All four are marked as destructive so Claude asks for confirmation, but the final responsibility for approving them is yours.

The recovery point password is shown exactly once. rootkey_create_recovery_point returns a decryption password that the API never returns again. The server displays it prominently and keeps it out of its own logs. Store it immediately - without it the downloaded archive cannot be opened.

Read-only mode

Setting ROOTKEY_READ_ONLY=true registers only the tools that read data. The write tools are not advertised at all, so Claude cannot call them, and the two download tools may only write inside the configured download directory.

{
  "mcpServers": {
    "rootkey": {
      "command": "npx",
      "args": ["-y", "@rootkey/mcp"],
      "env": {
        "ROOTKEY_API_KEY": "your_api_key",
        "ROOTKEY_READ_ONLY": "true"
      }
    }
  }
}

This is useful for analysis and reporting sessions where nothing should change. Treat it as a convenience rail rather than a security control: ROOTKey API keys have no scopes and carry the full privileges of the account that owns them, so anything else holding the key can still write. If you need a genuine boundary, use a key belonging to an account with narrower access.

Troubleshooting

Claude does not show any ROOTKey tools

Confirm Node.js 20 or newer is installed and on the PATH (node --version), then restart the Claude client completely - configuration is read at startup. In Claude Desktop, check the MCP server logs under Settings -> Developer; the server writes its startup line and any failure to stderr, which is what those logs show.

The server exits immediately

The most common cause is a missing key. The server refuses to start without ROOTKEY_API_KEY and says so on stderr, rather than failing later on the first tool call. Check that the variable is set inside the env block of the configuration, not only in your shell: Claude Desktop does not pass your shell environment to the server.

Every call returns 401 Unauthenticated

The API does not accept the key: it is not valid, or it has been deactivated. Check that ROOTKEY_API_KEY holds the complete key and that the key is active in Developer Tools. Ask Claude to run rootkey_get_environment_info to see the API base URL the server is using.

The server exits with a message about ROOTKEY_ENV

ROOTKey has one public API, so ROOTKEY_ENV accepts only production and is best left unset. A leftover ROOTKEY_ENV=development is refused at startup. Remove it and use a test API key to try things out. For a self-hosted or on-premise deployment, set ROOTKEY_API_URL instead.

Requests fail with 429 Too Many Requests

A request went over a rate limit: your plan’s API rate limit, or the limit of an operation that has its own - Rate Limits says which apply. The server automatically retries once the period indicated by the Retry-After header has passed, provided the wait is short. If 429s keep coming, spread those calls out over time, or move to a plan with a higher rate limit.

Requests fail with 503 Service Unavailable

ROOTKey was too busy to take the request for a moment. The server waits as long as the Retry-After header says and tries again, up to three attempts in all. It does this for listing and fetching, updating and deleting (GET, PUT and DELETE requests), but not for anything it sends as a POST, such as creating a file, a record or a vault: a repeat could create the same item twice. If one of those tools reports a 503, ask Claude to list the vault or table to see whether the item was created before you run the tool again. If a 503 keeps coming back, wait a little and try again, and contact [email protected] with the requestId the tool reports.

A tool reports the created file or record as null

The write succeeded. Several ROOTKey create endpoints do not return the id of what they created, so the server looks it up immediately afterwards; when anchoring has not yet surfaced the item, that lookup comes back empty. Ask Claude to list the vault or table again in a moment and the item will be there.

Windows: npx is not recognised

Use the cmd /c form of the Claude Desktop configuration shown in the Install section above. Windows needs the command routed through the shell for npx to resolve.

Current limits

The connector runs locally, which is what makes API key authentication safe: the key never leaves your machine. That has two consequences worth stating plainly.

It works in Claude Code and Claude Desktop, not in the claude.ai web app. Web connectors require a hosted server with OAuth, which is on the roadmap.
It covers the public API and nothing beyond it. There are no tools for managing API keys or organisation members, because the public API has no endpoints for them. Those arrive if and when the API does.

Source and support

The server is open source at github.com/ROOT-Key/rootkey-mcp and published on npm as @rootkey/mcp. Bug reports and feature requests are welcome on the issue tracker.

API Reference

Every endpoint the connector wraps, with interactive examples.

API Keys

Create, rotate and revoke the key the connector uses.

Introduction

Quickstart

Connectors

Integrations

Ecosystem Guides

Protocols

RKP-1 - Full On-Chain

RKP-2 - Off-Chain

RKP-3 - Hybrid

Data Sovereignty

Data Retention

Deployment Methods

On-Premise Installation

Developer Resources

Additional Resources

Requirements

Let your agent set it up

Install

Configuration

Available tools

Vaults

Files

Records

Data recovery

Diagnostics

Prompts

What to expect when using it

Safety

Read-only mode

Troubleshooting

Current limits

Source and support

API Reference

API Keys

​Requirements

​Let your agent set it up

​Install

​Configuration

​Available tools

​Vaults

​Files

​Records

​Data recovery

​Diagnostics

​Prompts

​What to expect when using it

​Safety

​Read-only mode

​Troubleshooting

​Current limits

​Source and support

API Reference

API Keys

Requirements

Let your agent set it up

Install

Configuration

Available tools

Vaults

Files

Records

Data recovery

Diagnostics

Prompts

What to expect when using it

Safety

Read-only mode

Troubleshooting

Current limits

Source and support