@spotdraft/spotdraft-mcp

v0.2.0

Published

16 days ago

Integrate the SpotDraft API into agentic workflows via MCP

0High
0Medium
0Low

codebreach

anirudhvarma

bharath-ravi

mcp spotdraft agent autonomous ai contract

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

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.