MCP Server

Lumipact MCP Server

A remote Model Context Protocol server that lets Claude, Cursor, and other MCP-compatible AI clients query your Lumipact workspace. Access is scoped to the entities and departments you explicitly authorize.

Overview

Transport

Streamable HTTP

Auth

OAuth 2.1 + PKCE

Access

Read-only (v1)

The server URL is https://lumipact.com/api/mcp. It follows the MCP specification and the OAuth 2.0 Authorization Server Metadata standard (RFC 8414), so any compliant MCP client can discover and connect to it automatically.

Quick start — Claude Desktop

Add the following to your Claude Desktop configuration file. Claude will prompt you to authorize via your Lumipact account on first use.

~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "lumipact": {
      "type": "http",
      "url": "https://lumipact.com/api/mcp",
      "authorization_server": "https://lumipact.com"
    }
  }
}

On Windows the config file is at %APPDATA%\Claude\claude_desktop_config.json.

After restarting Claude Desktop, type something like "Show me contracts expiring in the next 30 days" — Claude will call list_alerts automatically.

Authorization

Lumipact uses OAuth 2.1 with PKCE. The discovery endpoint at https://lumipact.com/.well-known/oauth-authorization-server advertises all endpoints to compliant clients.

OAuth endpoints

GET/.well-known/oauth-authorization-serverServer metadata discovery

GET/POST/api/oauth/authorizeAuthorization endpoint

POST/api/oauth/tokenToken endpoint (PKCE exchange)

POST/api/oauth/revokeToken revocation

Authorization flow

1
Redirect to authorization
Redirect the user to /api/oauth/authorize with response_type=code, client_id, redirect_uri, code_challenge (S256), and state.
2
User authorizes
The user sees a consent screen where they choose which entities (and optionally departments) to expose. They authenticate with their Lumipact account if not already logged in.
3
Receive authorization code
Lumipact redirects back to your redirect_uri with a code parameter (valid for 10 minutes, single-use).
4
Exchange for access token
POST /api/oauth/token with grant_type=authorization_code, code, code_verifier, and client_id. Receive a Bearer token.
5
Call the MCP server
Pass the token as Authorization: Bearer <token> on every request to /api/mcp.

Token request example

POST /api/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=<authorization_code>
&code_verifier=<pkce_verifier>
&client_id=<your_client_id>
&redirect_uri=https://yourapp.com/callback

Token response

{
  "access_token": "lpt_...",
  "token_type": "Bearer",
  "scope": "contracts:read"
}

Register an OAuth app

Go to Settings → Developer in your Lumipact workspace to register an OAuth app. You'll get a client_id and a client_secret (shown once — save it securely). Add one or more redirect URIs that Lumipact will accept after authorization.

Public clients (e.g. Claude Desktop) use PKCE without a client secret. Confidential clients (server-side apps) can include the secret in the token request for additional verification.

Ready to build an integration?

Open Developer settings

Tools

All tools are read-only. Results are automatically filtered to the entities and departments the token was authorized for.

list_contracts

List contracts with optional filters. Returns paginated results sorted by creation date.

Parameters

statusstring · optionalFilter by status: active, expired, terminated, draft, or pending.

contract_typestring · optionalFilter by contract type (e.g. saas, service, nda).

counterparty_namestring · optionalPartial match on counterparty name.

limitnumber · optionalResults per page. Default 25, max 100.

offsetnumber · optionalPagination offset. Default 0.

get_contract

Get full details for a single contract by ID. Returns all metadata fields including value, dates, and renewal terms.

Parameters

idstringContract UUID.

search_contracts

Full-text search across titles, counterparty names, and summaries.

Parameters

querystringSearch terms.

limitnumber · optionalMax results. Default 20, max 50.

list_alerts

Get active contracts with upcoming renewal dates within a look-ahead window. Results ordered by next_renewal_date ascending.

Parameters

daysnumber · optionalLook-ahead window in days. Default 90, max 365.

get_stats

Get aggregate statistics: total contract count, count by status, sum of total_value and annual_value across all accessible contracts.

list_entities

List the entities (organizations) this token has access to.

list_departments

List departments defined in this workspace.

Scoping & access control

Every token is scoped to one or more entities (organizations within your Lumipact workspace). Optionally, it can be further restricted to specific departments. This scope is chosen by the user during authorization and is fixed for the lifetime of the token.

·A token can never access contracts outside the entities selected at authorization time.
·If department_ids is set on a token, only contracts in those departments are returned.
·Tokens are workspace-specific — they cannot cross tenant boundaries.
·Revoking a token immediately blocks all future requests that use it.

Errors

401Missing or invalid Bearer token

403Token valid but not authorized for the requested resource

400Invalid request — check required parameters

500Server error — retry with exponential backoff

MCP tool errors are returned as text content with an Error: … prefix rather than HTTP errors, so the AI client can surface them to the user.

Back to Developers Developer settings