<!--
  immut documentation, machine-readable.

  Everything in one file:  https://www.immut.io/llms-full.txt
    What immut is, which integration path to choose, authentication and scopes, and the COMPLETE
    API reference: every endpoint with parameters, responses and a runnable curl. Fetch this first
    if you intend to call the API.

  Index of all pages:      https://www.immut.io/llms.txt
  OpenAPI contract:        https://www.immut.io/docs/openapi.json
  This page as HTML:       https://www.immut.io/docs/mcp

  Any page on this site is available as raw markdown by appending .md to its URL.
-->

# MCP connector: use immut as a tool, not an API

immut runs a hosted MCP server. Point your agent host at it and immut becomes a set of tools your model can call. No code, no SDK.

**URL:** `https://backend.immut.io/mcp`

This is the fastest way in if your host speaks MCP. If it does not, use the [REST API](/docs/api) instead. Both do the same work.

## How do I connect it?

One command sets it up in Claude Code.

```bash
claude mcp add --transport http immut https://backend.immut.io/mcp \
  --header "Authorization: Bearer imut_live_your_key"
```

Other hosts take a config file. Cursor is one.

```json
{
  "mcpServers": {
    "immut": {
      "url": "https://backend.immut.io/mcp",
      "headers": { "Authorization": "Bearer imut_live_your_key" }
    }
  }
}
```

Create the key in the immut app under Organization Settings, then AI Agents. Per-host setup steps are on the [Connect page](/docs/connect).

## What are the transport rules?

Streamable HTTP, and stateless. `POST` only. `GET` and `DELETE` return `405`.

Authenticate with `Authorization: Bearer imut_live_...`. This endpoint also accepts `x-api-key`, because some hosts allow no other header. That is true here and nowhere else. The `/api/v1` routes require Bearer.

## What tools does it expose?

32, each with its own page in the sidebar.

Every page is generated from the server itself, so a tool cannot exist without one. Each lists the arguments, which are required, and the REST endpoint behind it.

| Group | What it covers |
|---|---|
| Documents | Protect a file, add a version, read back what was protected and why |
| Sweeps | Report a sweep, read the history, see what the agent left alone |
| Review queue | Files the agent staged because it could not decide |
| Proofs | Certificates and keyless verification |
| Workspaces | The folder tree a file is filed into |
| Sharing | Give a named person access, and see who opened it |
| Account | Usage against your allowance, and who is in the organisation |

Machine-readable forms: the [tool contract](/docs/mcp-tools.json) as JSON, or [llms-full.txt](https://www.immut.io/llms-full.txt) for everything in one fetch. Add `.md` to any tool page for its raw markdown.

Three things to know before you build:

- `protect_path` is not on the hosted server. It reads the server's own disk, so it is off in production. Use `protect_file`, which takes the bytes.
- `reject_staged` deletes permanently. It is the only destructive tool.
- `get_certificate` returns metadata here, not the PDF. Download that from the app.

## Does the connector change what my key can do?

No. It forwards your key to the same v1 API.

Scopes apply exactly as they do over REST. A tool your key lacks scope for returns a clean tool error. It does not end the session. So the connector is a different door, not a wider one.

This matters more than it sounds. A new agent key carries six scopes: `documents:write`, `documents:read`, `folders:read`, `folders:write`, `certificates:read` and `workspaces:read`. Five tools need a scope that is not in that list, so they fail until an admin grants it.

| Tool | Scope it needs |
|---|---|
| `read_document` | `documents:content` |
| `create_workspace` | `workspaces:write` |
| `get_usage` | `billing:read` |
| `list_users` and `get_user` | `users:read` |

`documents:content` is the one to think about. Without it a leaked key shows file names. With it, the file contents. That is why it is never a default.

## What can the connector not do that the app can?

It adds evidence and reads it back. It does not manage your account or remove anything.

These need a person in the app:

- Delete, rename or move a document, folder or workspace.
- Archive anything, or restore it.
- Build the diligence export as a ZIP.
- Approve or reject a document in the admin queue. That is separate from the agent review queue.
- Add or remove people, or change what they can see.
- Change your plan, your seats or your card.
- Create or revoke an API key.

The pattern is deliberate. An agent adds proof and reports on it. Deleting evidence stays a human decision, made by someone who is signed in.

Two exceptions, because an agent needs them to finish its job. It can reject a file from the review queue, which deletes that staged file for good. It can also revoke a share link belonging to its organisation, including one a person made.

## How does immut record a connector upload?

As an API upload. There is no separate connector channel.

A file protected through the connector looks the same in the record as one sent by `curl`. What changes the record is the kind of key, not the door you came through. An agent key records the upload as `agent` and keeps the classification you send with it. A personal key records it as `api` and drops that classification, without an error.

So use an agent key. A personal key still works, and you will not be told what you lost.

## Can it read files off my computer?

No. The hosted server has no filesystem access.

It protects bytes you pass it. If you want something that reads your disk and decides what matters, that is the [agent skill](/docs/agents), which runs on your own machine. The two are complements. Many teams run both.

**This matters more if your AI cannot read your disk either.** Ask whether your assistant can open the file itself. A chat window with a PDF attached cannot: it has the **text it extracted**, not the file. Sending that text would anchor a proof of the text, and the certificate would not match the customer's file. immut refuses when it can spot it, returning `FILE_BYTES_NOT_VERIFIED`, but some formats have no signature to check. If you cannot open the file, say so and stop. Do not reconstruct it.

Local file reading exists in the code for people self-hosting the server beside themselves. It is ignored in production, whatever the environment says. A public deployment must never read arbitrary host paths.

## Which should I use, the connector or the skill?

Pick by what you need it to do.

| You want | Use |
|---|---|
| Your model to protect files you hand it | MCP connector |
| Something to scan your drive and decide what matters | [Agent skill](/docs/agents) |
| Your own code to call immut directly | [REST API](/docs/api) |
| Proof without uploading the file | `POST /proofs`, see [API reference](/docs/api) |

## What happens when a tool call fails?

You get a tool error with the same codes the REST API uses.

Read the code, not the message. The list, and which errors are worth retrying, is on the [Errors page](/docs/errors).