# @actalumen/mcp-server

MCP server for [ActaLumen](https://actalumen.com) — verify documents for compliance from Claude Desktop, Cursor, and Claude Code.

## What it does

Exposes ActaLumen's verification, chat, and document tooling to any MCP-compatible AI agent. Your agent can upload a contract, run it against a compliance template (SOC2, GDPR, custom), and chat with the document — all grounded in citations.

**PII is redacted server-side before storage.** Agents never see un-redacted content, even when explicitly asked.

## Install

### Easiest: MCPB bundle (Claude Desktop one-click)

Download `actalumen-<version>.mcpb` from the [latest release](https://github.com/actalumen/mcp-server/releases) and double-click it. Claude Desktop will prompt for your API key and upload directory, then install. No Node, no JSON editing.

### Or via npm (Cursor, Claude Code, custom MCP clients)

### Prerequisites

1. An ActaLumen API key with `read`, `write`, and `verify` scopes. Create one at **app.actalumen.com → Settings → API Keys**.
2. Node.js 18.17 or newer.
3. A directory the agent is allowed to upload from. Default: `~/actalumen-inbox` (create it: `mkdir ~/actalumen-inbox`).

### Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "actalumen": {
      "command": "npx",
      "args": ["-y", "@actalumen/mcp-server"],
      "env": {
        "ACTALUMEN_API_KEY": "ak_live_..."
      }
    }
  }
}
```

Restart Claude Desktop. You should see the ActaLumen tools in the tools menu.

### Cursor

Add to `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "actalumen": {
      "command": "npx",
      "args": ["-y", "@actalumen/mcp-server"],
      "env": { "ACTALUMEN_API_KEY": "ak_live_..." }
    }
  }
}
```

### Claude Code

```bash
claude mcp add actalumen -- npx -y @actalumen/mcp-server
# then set the key in your shell or settings:
export ACTALUMEN_API_KEY=ak_live_...
```

## Configuration

| Env var | Default | Purpose |
|---|---|---|
| `ACTALUMEN_API_KEY` | (required) | Org-scoped API key. |
| `ACTALUMEN_BASE_URL` | `https://api.actalumen.com` | Override for self-hosted or staging. |
| `ACTALUMEN_UPLOAD_DIR` | `~/actalumen-inbox` | Path allowlist — agents can only upload files from inside this directory. |

## Tools

| Tool | Purpose |
|---|---|
| `upload_document` | Upload a PDF (must be inside `ACTALUMEN_UPLOAD_DIR`). Returns a document ID; PII is redacted on the server before storage. |
| `get_document` | Poll a document's status — wait for `READY` before verifying or chatting. |
| `list_documents` | Find existing documents by name without re-uploading. |
| `list_templates` | Discover available compliance templates (e.g., SOC2 Vendor). |
| `start_verification` | Run a document against a template. Returns a `jobId`. |
| `get_verification` | Fetch report status and findings. |
| `chat_with_document` | Ask grounded questions about one or more documents. |
| `get_usage` | Check plan quota before batch operations. |

## Example agent flow

> "Check whether `~/actalumen-inbox/acme-msa.pdf` meets our SOC2 vendor requirements and summarize the gaps."

The agent will:

1. `list_templates` → find the SOC2 template.
2. `upload_document` → get a document ID, wait for `READY` via `get_document`.
3. `start_verification` → get a `jobId`.
4. `get_verification` (polling) → receive the full report.
5. Summarize the failed criteria back to you with page citations.

## Verify your install

```bash
ACTALUMEN_API_KEY=ak_live_... npx -y @actalumen/mcp-server --health
# → ok — https://api.actalumen.com — org Acme Inc — upload dir /Users/.../actalumen-inbox
```

## License

MIT