SpotDraft MCP Server

Integrate the SpotDraft API into agentic workflows via MCP.

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

Tools

Contract Management

• get_contract_list — List contracts
• 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

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

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"
    }
  }
}

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"
npm start

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

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/

License

MIT — see LICENSE.