# Plugins and commands

One install per editor. All three run the same server, against the same
[API](/api), with the same [25 tools](/mcp) and the same [guidance](/skill).
The only thing that differs is where the configuration lives.

Installation is this page. What each tool does is the [MCP server](/mcp) page;
why the shipped rules are the safety mechanism is [agent guidance](/skill). The
endpoints behind the tools are documented in [parsing](/parsing),
[extraction](/extraction) and [knowledge bases and
search](/knowledge-bases).

Two things are needed in every case: the server, and an API key in the
environment the editor launches it in. Most failed installs are the second one.

## Claude Code

Two commands. The plugin brings the server, the guidance and the tools
together — there is no separate download and no version to pin.

```bash
/plugin marketplace add ProvidusAI/docai-plugins
```

```bash
/plugin install docai
```

The plugin declares the server like this, and you do not need to write it
yourself:

```json
{
  "mcpServers": {
    "docai": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/server/index.js"],
      "commandWindows": "node \"$env:CLAUDE_PLUGIN_ROOT\\server\\index.js\"",
      "env": { "DOCAI_API_KEY": "${DOCAI_API_KEY}" }
    }
  }
}
```

Two things follow from that config. It runs on **node**, not bun — Claude Code
users already have node, and requiring bun would be a new install. And
`DOCAI_API_KEY` is read from the environment rather than stored in the plugin,
so the key never ends up in a config file:

```bash
export DOCAI_API_KEY="docai_..."
```

Put that in your shell profile, not just in one terminal. The server inherits
the environment Claude Code was launched from, so a key exported in a different
window does not reach it.

To register the two permanent-delete tools, which are hidden by default:

```bash
export DOCAI_MCP_ALLOW_DESTRUCTIVE=true
```

## Cursor

Add to `.cursor/mcp.json` in your project, or the global equivalent:

```json
{
  "mcpServers": {
    "docai": {
      "command": "npx",
      "args": ["-y", "github:ProvidusAI/docai-plugins"],
      "env": { "DOCAI_API_KEY": "${DOCAI_API_KEY}" }
    }
  }
}
```

`${DOCAI_API_KEY}` is expanded from your environment, so the file stays safe to
commit. Writing the literal key there instead makes the file organization-root
access — see [security](/mcp#security).

Cursor also reads project rules, and the server ships one. Copy the DocAI
guidance into `.cursor/rules/docai.mdc`:

```
---
description: DocAI document tools
alwaysApply: false
---

## Working with DocAI
...
```

The body is the same four rules as everywhere else — see [agent
guidance](/skill) for the full text and the reasoning. `alwaysApply: false`
means Cursor loads it when the description matches the work, rather than
carrying it in every prompt.

## Codex

Add to `~/.codex/config.toml`:

```toml
# Add to ~/.codex/config.toml
[mcp_servers.docai]
command = "npx"
args = ["-y", "github:ProvidusAI/docai-plugins"]
env = { DOCAI_API_KEY = "your-key-here" }
```

Codex takes the key literally in the table, so this file holds a real
credential. Keep it out of any repository, and treat it as production access to
the whole organization.

For the guidance, put the same four rules under a `# DocAI` heading in your
`AGENTS.md`.

## On-prem

Every install above talks to `https://api.providus.ai` by default. Point it at
your own deployment with one more variable:

```bash
export DOCAI_BASE_URL="https://docai.your-company.internal"
```

Or in the editor's own config, alongside the key:

```json
{
  "mcpServers": {
    "docai": {
      "command": "npx",
      "args": ["-y", "github:ProvidusAI/docai-plugins"],
      "env": {
        "DOCAI_API_KEY": "${DOCAI_API_KEY}",
        "DOCAI_BASE_URL": "https://docai.your-company.internal"
      }
    }
  }
}
```

Trailing slashes are stripped, so both forms of the URL work. Nothing else
differs: the tools, the guidance and the `/v1` surface are identical.

## Check it worked

Three checks, cheapest first.

**Read the startup line.** The server writes one diagnostic to stderr, which
your editor shows in its MCP log:

```
[docai-mcp] 20 tools against https://api.providus.ai
```

That single line answers three questions at once — the server started, which
API it is pointed at, and whether the destructive gate is open. Twenty-one
tools means the gate is closed, 23 means it is open.

**Ask for the knowledge bases.** Ask the agent to list them. It should call
`docai_list_knowledge_bases` and come back with names, not an apology.

**Ask for an index.** Ask it about a knowledge base by name. A correctly
configured agent goes to `docai_kb_index` rather than listing files and
fetching each one. If it crawls file by file, the guidance is not loaded — the
server is fine, but the rules are not reaching the model.

## When it does not work

**No DocAI tools at all, and the log says the key is required.** The server
exits at startup with:

```
DOCAI_API_KEY is required. Create a key in DocAI Settings and set it.
```

The key is missing from the environment the **editor** launched the server in,
which is not the same as your shell. Editors started from a Dock icon or a
Start menu shortcut do not read your shell profile. Either put the key in the
editor's own `env` block, or start the editor from a terminal that has it.

**No DocAI tools and no error at all, on Windows.** The Claude Code plugin
config uses `commandWindows` with the PowerShell expansion form
`"$env:CLAUDE_PLUGIN_ROOT\server\index.js"`. If that string reaches something
other than PowerShell, the variable is not expanded, node is handed a literal
path that does not exist, and the server never starts. It fails quietly,
because a server that never connected has no tools to report as missing. Check
the MCP log for a node error about a path containing `$env:`.

**Permanent deletes are missing.** Expected, unless
`DOCAI_MCP_ALLOW_DESTRUCTIVE` is set to `true`, `1` or `yes`. The two tools are
skipped at registration, so they are absent from the list rather than present
and refusing. Set the flag in the same environment the server is launched in —
the editor's `env` block is the reliable place — and restart the editor. The
startup line changes from 20 tools to 22 once it has taken.

**`npx` cannot fetch the server.** The Cursor and Codex configs install from
GitHub at launch. On a machine with no route to `github.com`, npx fails and
nothing starts. Use the Claude Code plugin, which ships the bundle, or vendor
the built `dist/index.js` locally and point `command`/`args` at it.

**Every tool call returns an authentication error, but the server started.**
The key is present but not valid for that host. The usual cause is a cloud key
against an on-prem `DOCAI_BASE_URL`, or the reverse. Keys are per-deployment.

**The agent asks to delete something you did not mention.** Stop and check
which key is configured. An API key is organization-root, so an agent working
in one project can reach every knowledge base the organization has. See
[security](/mcp#security).