SpotDraft MCP Server

Give Claude direct, safety-gated access to your SpotDraft contracts.

This is a locally-hosted MCP (Model Context Protocol) server that wraps the SpotDraft Public API so you can query and drive your SpotDraft workspace -- contracts, templates, counterparties, obligations, analytics -- conversationally from Claude, instead of clicking through the UI or writing one-off scripts.

It ships as two separate servers built from one codebase:

• spotdraft-read -- every read-only operation. Safe to blanket-allow; nothing here has side effects.

• spotdraft-write -- every mutating operation (create/send/void/invite/etc.). Every single tool requires your explicit approval on every call -- it cannot be pre-approved or run unattended.

That split exists so you can tell your MCP client "always allow reads, always ask before writes" in one line each, instead of trusting a single server's internal judgment about what's safe.

What can you do with this?

Once connected, ask Claude things like:

• "List all contracts pending signature from Acme Corp"

• "What's the status of contract T-4821?"

• "Show me the obligations tracked on H-102"

• "Draft a new NDA from the Standard NDA template for this counterparty" (write -- will prompt for approval)

• "Void contract T-991, it was created by mistake" (write + destructive -- will prompt for approval)

• "Run an analytics query for all contracts executed last quarter by contract type"

Claude figures out which SpotDraft API call(s) to make; you approve anything that changes data.

Related MCP server: cfr-compliance-mcp

Coverage

This server covers the v2.1 SpotDraft API family (the current/latest version) plus the small set of v1-only endpoints that have no v2.1 successor (legal intake, native integrations, obligation types, view-email, webhook-sample) -- 114 operations total. Superseded v2 and old-v1 endpoints with a v2.1 replacement are intentionally excluded.

Coverage is delivered two ways:

1. Curated tools (~15 read + ~13 write) for the most common contract-lifecycle workflows -- listing/searching contracts, checking status, downloading, creating from a template, sending to counterparties, voiding, managing counterparties and users, etc. Tight, well-described input schemas.

2. A search + execute fallback, so nothing is out of reach even if it doesn't have a curated tool:

   • search_actions(intent, access?) -- keyword-search the full 114-operation catalog.

   • execute_read_request(operationId, ...) -- call any read-classified operation by ID.

   • execute_write_request(operationId, ...) -- call any write-classified operation by ID (write server only; force-gated like every other write tool).

Re-vendoring a newer OpenAPI spec and re-running npm run gen:catalog keeps this catalog current without hand-editing generated code.

Quick start

What you'll need

1. Node.js 20+ and git.

2. A SpotDraft API credential (Client ID + Client Secret): in SpotDraft, go to Settings -> Developer Settings -> Generate API Credential. If you don't have access to that page, ask whoever administers your SpotDraft workspace to generate one for you.

3. An MCP-capable client (e.g. Claude Code).

1. Clone and build

git clone <this-repo-url> spotdraft-mcp
cd spotdraft-mcp
npm install
npm run build

This produces dist/index.js, which both server modes run.

2. Configure your MCP client

Add two server entries -- one per mode -- pointing at the same built file, with SPOTDRAFT_MODE as the only thing that differs:

{
  "mcpServers": {
    "spotdraft-read": {
      "command": "node",
      "args": ["/absolute/path/to/spotdraft-mcp/dist/index.js"],
      "env": {
        "SPOTDRAFT_MODE": "read",
        "SPOTDRAFT_CLIENT_ID": "your-client-id",
        "SPOTDRAFT_CLIENT_SECRET": "your-client-secret",
        "SPOTDRAFT_REGION": "us"
      }
    },
    "spotdraft-write": {
      "command": "node",
      "args": ["/absolute/path/to/spotdraft-mcp/dist/index.js"],
      "env": {
        "SPOTDRAFT_MODE": "write",
        "SPOTDRAFT_CLIENT_ID": "your-client-id",
        "SPOTDRAFT_CLIENT_SECRET": "your-client-secret",
        "SPOTDRAFT_REGION": "us"
      }
    }
  }
}

On Windows, double the backslashes in the path (C:\\Users\\you\\...).

If you only ever need read access, register just spotdraft-read.

3. Set your approval rules

In your MCP client's permission settings, add:

{
  "permissions": {
    "allow": ["mcp__spotdraft-read__*"],
    "ask": ["mcp__spotdraft-write__*"]
  }
}

This blanket-allows every read tool and requires per-call approval for every write tool. Every write tool also sets _meta["anthropic/requiresUserInteraction"] = true, which forces approval on supporting clients even if a broader "don't ask again" rule is in effect.

4. Verify

Ask Claude to "list SpotDraft users" (calls list_users, a good connectivity check) and confirm it returns your workspace roster without any approval prompt. Then ask it to do something mutating (e.g. draft a contract note) and confirm it does prompt for approval.

Configuration reference

Region -> base URL mapping: us -> api.us.spotdraft.com, eu -> api.eu.spotdraft.com, in -> api.in.spotdraft.com, me -> api.me.spotdraft.com.

Curated tools

Read (spotdraft-read) -- always safe, never prompts

Write (spotdraft-write) -- every call requires approval

Security model

• Two servers, not one with internal flags. Approval tooling in MCP clients keys off the tool name mcp__<server-name>__<tool-name>, so splitting read/write into two server names is what makes "always allow reads, always ask on writes" expressible as two simple rules.

• Every write tool force-gates. In addition to the two-server split, every write tool sets _meta["anthropic/requiresUserInteraction"] = true and readOnlyHint: false; void_contract additionally sets destructiveHint: true. Read tools set readOnlyHint: true and never force-gate. This is belt-and-suspenders: the server split is the primary control, the tool annotations are a second, client-enforced layer that can't be bypassed by a broad allow rule. Any operation reachable through execute_read_request / execute_write_request is checked against the same catalog access flag server-side, so the fallback path can't be used to sneak a write through the read server or vice versa.

• Semantic, not just HTTP-method-based, classification. A handful of POST endpoints with no side effects (analytics query, contract preview, sidebar query, clickwrap agreement preview, contract-download-link generation) are classified as read. Everything else that isn't a GET is write.

• Credentials never leave your machine and are never logged. SPOTDRAFT_CLIENT_SECRET / SPOTDRAFT_CLIENT_ID are read from environment variables supplied by your MCP client, and are redacted from any error message or log line before it can be printed or returned to the model.

• Composite IDs are never mutated. SpotDraft composite contract IDs (T-123, H-45) are sent to the API exactly as given -- never re-prefixed, re-cased, or reformatted.

How it works

You -> Claude -> spotdraft-read / spotdraft-write (this server, on your machine) -> SpotDraft API -> Your workspace

Both server modes are built from the same dist/index.js; SPOTDRAFT_MODE decides which tool set gets registered at startup (see src/server.ts). The operation catalog (src/generated/catalog.ts) is generated from a vendored copy of SpotDraft's own OpenAPI spec (openapi/spotdraft-openapi.json) by scripts/gen-catalog.ts -- re-run npm run gen:catalog after re-vendoring a newer spec to pick up new operations.

Project structure

spotdraft-mcp/
├── package.json               # bin: spotdraft-mcp-read / spotdraft-mcp-write; scripts: build/dev/gen:catalog/test
├── tsconfig.json
├── openapi/
│   ├── spotdraft-openapi.json # vendored OpenAPI spec (source of truth for coverage)
│   └── FETCHED.md             # provenance / fetch date for the vendored spec
├── scripts/
│   ├── gen-catalog.ts         # parses the vendored spec -> src/generated/catalog.ts
│   └── run-tests.mjs          # cross-shell test runner (see "Development" below)
├── src/
│   ├── index.ts                # entry point for both bin commands
│   ├── server.ts                # builds the McpServer per SPOTDRAFT_MODE
│   ├── config.ts                # env parsing, region resolution, validation
│   ├── http.ts                   # SpotDraft HTTP client: auth, retries, redaction
│   ├── generated/catalog.ts      # generated operation catalog (do not hand-edit)
│   ├── tools/
│   │   ├── read/                 # curated read tool modules
│   │   ├── write/                 # curated write tool modules
│   │   ├── shared.ts               # registration helper (annotations, error handling, pagination)
│   │   └── fallback.ts            # search_actions + execute_read_request + execute_write_request
│   └── util/ (ids.ts, format.ts, errors.ts)
└── test/                        # unit tests (node:test)

Development

npm install          # install dependencies
npm run gen:catalog   # regenerate src/generated/catalog.ts from openapi/spotdraft-openapi.json
npm run build          # compile TypeScript -> dist/
npm test                # run the unit test suite
npm run dev              # run src/index.ts directly via tsx (no build step)

npm test runs scripts/run-tests.mjs, which enumerates test/*.test.ts and passes them explicitly to Node's built-in test runner -- letting the test runner glob-scan the test/ directory itself conflicts with the tsx ESM loader hook on some Node versions.

License

MIT.