> ## Documentation Index > Fetch the complete documentation index at: https://docs.rootkey.ai/llms.txt > Use this file to discover all available pages before exploring further. # Claude (MCP) > Connect Claude to ROOTKey with the official MCP server and operate vaults, files, records and recovery points in plain language. The ROOTKey MCP server connects Claude to your ROOTKey workspace. It implements the [Model Context Protocol](https://modelcontextprotocol.io), 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 **Platform -> Developer Tools -> API Keys** See [API Keys](/pages/api-keys) for how to create one. Use a development key (`rk_test_`) while you try things out: the development environment costs nothing and anchors nothing to Polygon Mainnet. *** ## 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](/agent-setup/prompt) 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 Run this once, from anywhere: ```bash theme={null} claude mcp add rootkey --env ROOTKEY_API_KEY=rk_live_your_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`: ```json theme={null} { "mcpServers": { "rootkey": { "command": "npx", "args": ["-y", "@rootkey/mcp"], "env": { "ROOTKEY_API_KEY": "rk_live_your_key" } } } } ``` On **Windows**, route the command through `cmd` so `npx` resolves correctly: ```json theme={null} { "mcpServers": { "rootkey": { "command": "cmd", "args": ["/c", "npx", "-y", "@rootkey/mcp"], "env": { "ROOTKEY_API_KEY": "rk_live_your_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: ```json theme={null} { "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` | `production` or `development`. Selects the matching API base URL. | | `ROOTKEY_API_URL` | - | Full base URL including the `/api-v1/` path. Overrides `ROOTKEY_ENV`. 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. | To work against the development environment, set `ROOTKEY_ENV=development` and use an `rk_test_` key. See [Environments](/pages/environments) for the difference between the two. *** ## Available tools 27 tools: every operation in the [API Reference](/api-reference/overview), 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 or table 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 configured environment, key type and 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. ```json theme={null} { "mcpServers": { "rootkey": { "command": "npx", "args": ["-y", "@rootkey/mcp"], "env": { "ROOTKEY_API_KEY": "rk_live_your_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 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 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. The key and the environment do not match. `rk_test_` keys work only against the development API and `rk_live_` keys only against production. Ask Claude to run `rootkey_get_environment_info` to see which environment the server is configured for, then align the key or set `ROOTKEY_ENV` accordingly. You have exceeded the rate limit for that API key. The server automatically retries once the period indicated by the `Retry-After` header has passed, provided the wait is short. Repeated 429s mean the workload needs a higher plan limit - see [Rate Limits](/pages/rate-limits). 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. 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, organisation members or webhooks, 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](https://github.com/ROOT-Key/rootkey-mcp) and published on npm as [`@rootkey/mcp`](https://www.npmjs.com/package/@rootkey/mcp). Bug reports and feature requests are welcome on the issue tracker. Every endpoint the connector wraps, with interactive examples. Create, rotate and revoke the key the connector uses.