Soloft MCP reference

A Model Context Protocol server that lets AI assistants such as Meta Muse read and, with the user's explicit OAuth consent, update a Soloft workspace: clients, projects, invoices, expenses, bookings, content and portfolio.

Overview

Authentication

OAuth 2.1 authorization code flow with PKCE (S256 only) and RFC 8707 resource indicators. API keys are not supported. Every request to /mcp needs Authorization: Bearer <access_token>.

Discovery

An unauthenticated or invalid request returns 401 with WWW-Authenticate: Bearer resource_metadata="https://mcp.soloft.io/.well-known/oauth-protected-resource".

Endpoints

Flow

1. The client sends the user to /authorize with response_type=code, client_id, a registered redirect_uri, scope, state, code_challenge (S256), code_challenge_method=S256 and resource=https://mcp.soloft.io.
2. The user signs in to Soloft and approves a consent screen that lists each requested permission in plain language.
3. Soloft redirects to redirect_uri with code and state (or error=access_denied).
4. The client POSTs to /token with grant_type=authorization_code, code, redirect_uri, client_id, code_verifier and the same resource.

{
  "access_token": "…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "…",
  "scope": "crm:read projects:read invoices:read"
}

Token lifetimes and rules

• Authorization codes last 5 minutes and are single use. Access tokens last 1 hour; refresh tokens last 30 days and rotate on every use. Reuse of a rotated refresh token revokes the whole token family for that grant.
• Strict audience: a token must be bound to resource=https://mcp.soloft.io. Tokens without it are rejected by /mcp with 401.
• Public clients authenticate with PKCE only (token_endpoint_auth_method: none). Confidential clients may use client_secret_basic or client_secret_post.
• Redirect URIs are matched exactly against the client's registered list. Tokens and codes are stored only as hashes.
• Users can disconnect an app at any time in Soloft under Settings → Connected apps. Deleting the account also ends all tokens.

Scopes

tools/list returns only the tools whose scope the token holds, further narrowed to the modules enabled for the workspace's business type. Read scopes never allow writes.

Tools that change stock quantities (creating or cancelling orders, inventory adjustments, production runs, purchase-order receipt) are not available over MCP; do those in Soloft.

Protocol

JSON-RPC 2.0 over POST /mcp. Supported methods: initialize, ping, tools/list, tools/call. Notifications without an id return 202. Request bodies are limited to 256 KB and must be application/json. Requests carrying a browser Origin header that is not on the allowlist are rejected with 403.

POST /mcp
Authorization: Bearer <access_token>
Content-Type: application/json

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18"}}

{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{
  "name":"soloft_list_invoices","arguments":{"status":"overdue","limit":5}}}

Tool results are returned as a text content item plus structuredContent holding the same JSON, with isError: false. Every tool carries title and annotations (readOnlyHint, destructiveHint, idempotentHint), and arguments are validated against the tool's JSON Schema.

Tools

All names are prefixed soloft_. List tools return at most 100 rows (default 20). Arguments not in a tool's schema are rejected. tools/list is the authoritative list for a connection; the tables below group tools by scope.

Read tools Read

Write tools Write

None of these is destructive. Insert tools accept an optional client_request_id; repeating a call with the same id returns the original record instead of creating a duplicate.

Write behavior

• Writes apply immediately to the user's own workspace and are the same changes the user could make in the app.
• No tool deletes data. No tool sends email, SMS or portal messages, publishes content, creates payment links or moves money.
• Every write is scoped to the workspace bound to the token; ids belonging to another workspace are treated as not found.
• Updates that cannot apply (for example marking a draft invoice paid) return a stable error code and change nothing.

Errors

A tool error is a normal JSON-RPC result with isError: true:

{"jsonrpc":"2.0","id":3,"result":{
  "content":[{"type":"text","text":"{\"error\":\"insufficient_scope\",\"message\":\"This connection lacks the invoices:write permission.\"}"}],
  "structuredContent":{"error":"insufficient_scope","message":"This connection lacks the invoices:write permission."},
  "isError":true}}

Limits

• 60 tools/call requests per minute per user; 120 requests per minute per client IP on /mcp.
• 200 successful write calls per user per rolling day.
• List tools return at most 100 rows. Request bodies are limited to 256 KB.

Testing

Reviewer access with a sample workspace is provided in the submission notes. To verify the server without OAuth, an unauthenticated call should return 401 with the discovery header:

curl -i -X POST https://mcp.soloft.io/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

A health check is available at GET https://mcp.soloft.io/mcp/health.

Data & privacy

• Tools read and write only the authenticated user's own workspace; every query is filtered by the owner bound to the token, never by tool arguments.
• Single-record tools may return a client's contact details; list tools return names, ids and contact email; booking lists never return booker emails or join links. Payment-provider tokens, calendar and integration credentials, and other secrets are never exposed.
• Soloft keeps an audit log of each tool call (which app, which tool, when and the outcome) without arguments or results. Nothing from the connector is shared with third parties. See the privacy policy and terms.
• Support and security contact: founder@tenderlab.studio.