SpotDraft MCP Server

Integrate the SpotDraft API into agentic workflows via MCP.

npm: — release notes: CHANGELOG.md.

Alpha Software — not covered by any support SLA. Do not use in production.

Tools

Contract Management

• get_contract_list — List contracts (filters include contract_id with $eq / $in for one or more composite IDs)
• get_contract_download_link — Get a contract download link
• get_contract_status — Get contract status
• get_contract_activity_log — Get activity log (comments)
• get_contract_approvals — Get contract approvals
• get_contract_key_pointers — Get contract key pointers

Write Tools (require write mode)

These tools are only listed and callable when write mode is enabled (see Write capabilities):

• upload_contract_version — Upload a new contract version (PDF) for an existing contract
• send_contract_to_counterparties — Send the contract to counterparties by email
• create_contract_approvals — Create and send adhoc approval requests for a contract
• add_contract_comment — Add a comment to the contract activity log

Template Management

• get_templates — List templates
• get_template_details — Get template details
• get_template_metadata — Get template metadata

Counter Party Management

• get_counter_parties — List counter parties
• get_counter_party_details — Get counter party details

Facet Discovery

• get_workspace_facets — Retrieves available search facets for filtering and searching contracts in the workspace
• get_workspace_facet_options — Gets facet options for contract search filtering

Legal Intake Management

• get_legal_intakes — List all legal intakes
• get_legal_intake_by_id — Get specific legal intake by id

Other

• get_key_pointers — Retrieves key pointers
• get_contract_types — Retrieves available contract types

Setup

Prerequisites

• Node.js 20+
• SpotDraft API credentials (Client ID and Client Secret)

Environment Variables

Required (Stdio Mode)

Variable	Description
SPOTDRAFT_CLIENT_ID	SpotDraft API Client ID
SPOTDRAFT_CLIENT_SECRET	SpotDraft API Client Secret

Required (HTTP Mode)

Variable	Description
SERVER_PUBLIC_URL	Public URL of this MCP server (e.g., https://mcp.example.com)

Optional

Variable	Description	Default
SPOTDRAFT_BASE_URL	SpotDraft API base URL	https://api.spotdraft.com/api
SPOTDRAFT_USER_EMAIL	User email for scoping requests	—
LOG_LEVEL	debug, info, warn, or error	info
SD_MCP_ENABLE_WRITE	Enable write tools. Set to true, 1, or yes (case-insensitive). When set, write tools (upload version, send contract, approvals, comments) are listed and callable.	—

OAuth 2.0 (Optional — enables OAuth support)

Variable	Description	Default
OAUTH_AUTHORIZATION_SERVER_URL	OAuth Authorization Server URL	—
OAUTH_JWKS_URI	JWKS URI for JWT signature validation	—
OAUTH_AUDIENCE	Expected audience claim in tokens	SERVER_PUBLIC_URL

Installation & Usage

Option 1: NPX (Recommended)

npx @spotdraft/spotdraft-mcp

Claude Desktop — Stdio Mode

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "spotdraft": {
      "command": "npx",
      "args": ["@spotdraft/spotdraft-mcp"],
      "env": {
        "SPOTDRAFT_CLIENT_ID": "<YOUR_CLIENT_ID>",
        "SPOTDRAFT_CLIENT_SECRET": "<YOUR_CLIENT_SECRET>",
        "SPOTDRAFT_BASE_URL": "<SPOTDRAFT_BASE_URL>"
      }
    }
  }
}

Claude Desktop — HTTP Mode

Start the server separately with node build/index.js --http, then add:

{
  "mcpServers": {
    "streamable-http-spotdraft": {
      "type": "streamable-http",
      "url": "http://localhost:3000/mcp?baseUrl=https%3A%2F%2Fapi.us.spotdraft.com%2Fapi"
    }
  }
}

To enable write tools (upload version, send contract, approvals, comments), append &enable_write=true to the URL or set SD_MCP_ENABLE_WRITE=true in the server environment.

Option 2: Local Development

git clone https://github.com/spotdraft/spotdraft-mcp.git
cd spotdraft-mcp
npm install
npm run build
export SPOTDRAFT_CLIENT_ID="your_client_id"
export SPOTDRAFT_CLIENT_SECRET="your_client_secret"
# Required: set SERVER_PUBLIC_URL or startup fails with ZodError (server.publicUrl expected string, received undefined)
export SERVER_PUBLIC_URL="http://localhost:3000"
npm start

For HTTP mode, start with: SERVER_PUBLIC_URL=http://localhost:3000 node build/index.js --http (or set the env var before npm start and pass --http).

Option 3: Docker

# Build
docker build -t spotdraft-mcp .

# Run — stdio mode (default)
docker run -e SPOTDRAFT_CLIENT_ID=your_client_id -e SPOTDRAFT_CLIENT_SECRET=your_client_secret spotdraft-mcp

# Run — HTTP mode
docker run -p 3000:3000 \
  -e SPOTDRAFT_CLIENT_ID=your_client_id \
  -e SPOTDRAFT_CLIENT_SECRET=your_client_secret \
  -e SPOTDRAFT_BASE_URL=https://api.us.spotdraft.com/api \
  spotdraft-mcp node build/index.js --http

Server Modes

Stdio (default) — Used by MCP clients like Claude Desktop. Communicates over stdin/stdout. Logs go to stderr in JSON format.

HTTP (--http flag) — Exposes REST endpoints for web integrations. Logs go to stdout in human-readable format.

Endpoint	Method	Description
/health	GET	Health check
/mcp	POST	MCP tool calls

Write capabilities

Write tools (upload_contract_version, send_contract_to_counterparties, create_contract_approvals, add_contract_comment) are disabled by default. They are only listed in tools/list and only executable when write mode is on.

Enabling write mode

• HTTP mode — Use either:
  • Query parameter: call the MCP URL with enable_write=true (e.g. http://localhost:3000/mcp?enable_write=true or .../mcp?baseUrl=...&enable_write=true), or
  • Environment variable: set SD_MCP_ENABLE_WRITE=true (or 1 / yes, case-insensitive) when starting the server.
• Stdio mode — Set SD_MCP_ENABLE_WRITE=true (or 1 / yes) in the environment where the server runs (e.g. in your Claude Desktop config env).

If a client calls a write tool while write mode is off, the server responds with 403 and error code WRITE_DISABLED and a message explaining how to enable write.

OAuth 2.0 Authorization

Optional MCP Authorization Spec compliant OAuth 2.0 support. The server acts as an OAuth 2.0 Protected Resource (RFC 9728).

OAuth is fully backward-compatible — existing Basic Auth integrations continue working.

Authentication Methods

Basic Auth — Send clientId:clientSecret as the Bearer token:

curl -X POST http://localhost:3000/mcp \
  -H "Authorization: Bearer clientId:clientSecret" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

OAuth Bearer Token — Send a JWT from an Authorization Server:

curl -X POST http://localhost:3000/mcp \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

The server auto-detects: tokens containing : use Basic Auth; JWT-formatted tokens (3 dot-separated parts) use OAuth.

Protected Resource Metadata

When OAUTH_AUTHORIZATION_SERVER_URL is set, the server exposes:

GET /.well-known/oauth-protected-resource

{
  "resource": "https://your-mcp-server.com",
  "authorization_servers": ["https://your-auth-server.com"],
  "resource_name": "SpotDraft MCP Server"
}

Example Configuration

Production:

SERVER_PUBLIC_URL=https://mcp.spotdraft.com
OAUTH_AUTHORIZATION_SERVER_URL=https://api.spotdraft.com
OAUTH_JWKS_URI=https://api.spotdraft.com/.well-known/jwks.json
OAUTH_AUDIENCE=https://mcp.spotdraft.com
SPOTDRAFT_BASE_URL=https://api.spotdraft.com/api

Development:

SERVER_PUBLIC_URL=http://localhost:3000
OAUTH_AUTHORIZATION_SERVER_URL=http://localhost:8000/api/v1/oauth
OAUTH_JWKS_URI=https://api.dev.spotdraft.com/.well-known/jwks.json
OAUTH_AUDIENCE=https://api.spotdraft.com
SPOTDRAFT_BASE_URL=https://api.in.dev.spotdraft.com/api

Development

npm run build       # Compile TypeScript
npm run watch       # Watch mode
npm run inspector   # MCP inspector for debugging

Project Structure

src/
├── index.ts                 # Entry point
├── handler.ts               # Shared request handlers
├── spotdraft_client.ts      # API client
├── auth/                    # Authentication
├── errors/                  # Error types
├── logging/                 # Logging
├── validation/              # Input validation
├── servers/                 # HTTP and stdio servers
└── tools/                   # Tool implementations
    ├── contracts/
    ├── contract-types/
    ├── counter-parties/
    ├── facets/
    ├── key-pointers/
    └── templates/

Changelog

Version history and migration notes: CHANGELOG.md.

License

MIT — see LICENSE.