MCP tool reference - Shor Documentation

Shor’s MCP server exposes 10 read tools and five write tools over the public API. For customer setup, capabilities, and example prompts, start with Connect AI assistants.

Connection and API routes

An assistant sends MCP requests to the hosted /mcp endpoint, using the server address displayed in Settings → Integrations. The HTTP routes below are the underlying public API operations on the API origin; they are not separate MCP endpoints or URLs to enter into the assistant. Hosted connections use OAuth and are scoped to the signed-in Shor workspace. Setup creates the connection automatically for an admin. API keys are for direct API integrations; do not send an assistant’s OAuth token directly to /v1. The OpenAPI reference defines HTTP request and response schemas. The API also serves its current contract at GET /v1/openapi.json without authentication.

Read tools

Every tool in this table requires read and allows the current admin, member, or viewer role within the connection’s granted access. Reads do not request write confirmation. Initial hosted setup and connection management require an admin.

MCP tool	HTTP method and route	Inputs and result
`get_business`	`GET /v1/business`	No arguments. Returns the current workspace’s ID, name, country, business verification status, and timestamps.
`list_contracts`	`GET /v1/contracts`	Optional contract filters and pagination. Returns contract summaries.
`get_contract`	`GET /v1/contracts/{id}`	Required `id`. Returns a contract summary, including worker ID/name, status, and dates.
`list_timesheets`	`GET /v1/timesheets`	Optional timesheet filters and pagination. Returns work periods, units, rates, totals, payment dates, automatic payment settings, and review versions.
`get_timesheet`	`GET /v1/timesheets/{id}`	Required `id`. Returns one timesheet, including its `version` and nullable `paymentId`.
`list_milestones`	`GET /v1/contracts/{id}/milestones`	Required `contractId`, mapped to the route’s `{id}`. Optional status and pagination. Returns milestones for that contract.
`get_milestone`	`GET /v1/milestones/{id}`	Required `id`. Returns amount, due/payment dates, status, `version`, and nullable `paymentId`.
`list_payments`	`GET /v1/payments`	Optional payment filters and pagination. Returns current payment states, gross/net amounts, and dates.
`get_payment`	`GET /v1/payments/{id}`	Required `id`. Returns one payment and its current status.
`get_balances`	`GET /v1/balances`	No arguments. Returns available/pending amounts by currency and an `asOf` timestamp.

IDs are UUIDs returned by Shor. Single resources are objects; lists return { data, hasMore, nextCursor }. Money uses { amount, currency }, with amount a decimal string. Dates use YYYY-MM-DD; timestamps use UTC ISO 8601. The MCP result carries the JSON representation in a text content block.

List filters and pagination

All four list tools accept numeric limit from 1–100, defaulting to 25 for MCP. Direct HTTP list calls default to 50. Continue with nextCursor as cursor while hasMore is true, keeping the other filters unchanged.

Tool	Additional filters
`list_contracts`	`status`, `updatedSince`, `includeDeleted`, `externalReference`
`list_timesheets`	`status`, `contractId`, `updatedSince`
`list_milestones`	Required `contractId`; optional `status`
`list_payments`	`status`, `contractId`, `updatedSince`

includeDeleted is the string "true" or "false" (default "false"), including in MCP arguments. updatedSince is an inclusive UTC timestamp. externalReference looks up a draft within the same workspace and integration principal. Timesheet status filters are submitted, approved, and rejected. Milestone filters are pending, submitted, approved, completed, paid, and rejected. Payment filters are pending, processing, completed, failed, and cancelled. Contract statuses and complete schemas are in the OpenAPI reference. For example, the arguments to list_timesheets can be:

{ "status": "submitted", "limit": 25 }

Milestones have no workspace-wide list or updatedSince filter. List contracts first, then scan each relevant contract’s milestone pages. For overlap windows, deletion handling, and other reconciliation rules, see Polling and TypeScript SDK.

Write tools

Every write in this table requires explicit human confirmation through the MCP host. The scopes listed are required for the MCP tool, and the role is checked against the current membership on every action and replay.

MCP tool	HTTP method and route	Required MCP scopes	Allowed roles
`create_contract_draft`	`POST /v1/contracts`	`contracts:write`	`admin`, `member`
`approve_timesheet`	`POST /v1/timesheets/{id}/approve`	`read` + `timesheets:write`	`admin`
`reject_timesheet`	`POST /v1/timesheets/{id}/reject`	`read` + `timesheets:write`	`admin`
`approve_milestone`	`POST /v1/milestones/{id}/approve`	`read` + `milestones:write`	`admin`
`reject_milestone`	`POST /v1/milestones/{id}/reject`	`read` + `milestones:write`	`admin`

Approval/rejection tools require read because they fetch the resource and its contract before asking for confirmation. Their HTTP POST routes require the corresponding write scope; direct API clients must separately fetch and review the resource to obtain expectedVersion.

Create a contract draft

create_contract_draft requires title and intentId. Optional inputs are professionalEmail, description, employmentType, contractType, countryOfEmployment, startDate, endDate, and externalReference. Employee contracts require countryOfEmployment, and any supplied employment/contract types must agree. Example tool arguments using a synthetic intent ID:

{
  "title": "Website redesign",
  "externalReference": "example-project-001",
  "intentId": "example-draft-001"
}

The confirmation displays the workspace and supplied fields. After confirmation, MCP removes intentId from the body and sends it as the HTTP Idempotency-Key header. The result is a contract summary; direct HTTP creation returns status 201. This initializes a draft for completion in Shor. It does not accept the dashboard’s nested compensation payload, sign an agreement, or activate a contract.

Approve or reject submitted work

The four review tools accept id and intentId. Rejections also require a trimmed, nonempty reason of at most 2,000 characters. They act on submitted work; other states may be rejected by the API. MCP fetches the timesheet or milestone and its contract, then shows the worker, contract, workspace, amount/currency, and payment date for review. Timesheet reviews also include the work period. Approval shows the timesheet’s automatic payment setting or the milestone’s immediate processing behavior; rejection shows the reason. The server retains the fetched resource version in signed review state. After confirmation, it sends { expectedVersion } for approval or { expectedVersion, reason } for rejection, with intentId in Idempotency-Key. Do not supply expectedVersion or confirmed as tool arguments: those fields are not accepted by these tools. The result is the updated timesheet or milestone. Approval creates a payment; timesheet processing follows its due date and effective automatic payment setting, while milestone approval attempts processing immediately. Follow a returned paymentId with get_payment to determine payout status. A successful approval is not a completed payout.

Confirmation, retries, and stale reviews

For the 2026-07-28 protocol, the first write call returns an input-required response containing signed requestState and a confirmation request. A compatible host presents that request to the human and resumes with the signed state and accepted input response. Review state lasts five minutes and binds the principal, workspace, tool, arguments, and reviewed resource version where applicable. A model-generated confirmed value does not authorize a write. Changing the arguments or reusing another workspace’s review fails validation. Remote hosts that cannot carry the required confirmation can read but receive CONFIRMATION_UNSUPPORTED for writes. Verify compatibility with the actual host/version; successful tool discovery does not establish support for confirmed writes. Every intentional write needs a unique intentId of 16–128 letters, digits, underscores, or hyphens. Retain it and the exact arguments across retries of that operation. Successful API results are retained for seven days. Do not reuse the ID after retention. For an intentional new action, generate a new ID. If the review expires or the resource changes, fetch and confirm current details again. A changed resource version returns STALE_RESOURCE_VERSION; use a new intent for the newly reviewed action. For an uncertain prior outcome, reconcile the resource/payment state before creating a new operation. An API replay returns the original operation result, which may differ from current resource state. externalReference can correlate contract drafts after operation retention, but is scoped to the workspace and integration principal. Separate MCP grants and independently created API keys are different integrations. MCP uses the typed client’s default 15-second deadline and two retries for network failures and 429/502/503/504 responses. Authorization errors and 409 conflicts need caller handling. See API errors and retries for rate limits and HTTP error semantics.

Error handling

Tool failures use isError: true with a JSON error in text content. API-originated errors include code, status, and available requestId/retryAfterSeconds; confirmation failures may contain only code. Transport or protocol errors can occur before a tool result is produced.

Code	Next step
`CONFIRMATION_UNSUPPORTED`	Use a host/version that supports the required confirmation, or perform the action in Shor.
`CONFIRMATION_DECLINED`	No write was authorized. Stop unless the user requests another review.
`CONFIRMATION_MISMATCH`	Arguments or review state no longer match. Start a fresh review.
`CONFIRMATION_EXPIRED`	Legacy confirmation timed out. Review again; invalid modern signed state may instead fail at the protocol layer.
`STALE_RESOURCE_VERSION`	Fetch and review the latest resource before a new intent.
`INVALID_CREDENTIAL` / `INSUFFICIENT_SCOPE`	Check sign-in, workspace, active connection, scopes, and current role.
`INTEGRATION_DISABLED` / `WRITES_DISABLED`	Check workspace rollout and write availability with Shor.
`IDEMPOTENCY_KEY_REUSED`	Retry only the original arguments, or use a new ID for a separate intended action.
`OPERATION_IN_PROGRESS`	Wait and retry the same operation.
`OPERATION_EXPIRED`	Reconcile state before deciding whether another action is needed.
`EXTERNAL_REFERENCE_EXISTS`	Look up the contract using the same `externalReference`.
`TOOL_FAILED` / `MCP_UNAVAILABLE`	Inspect current state before retrying an uncertain write; contact Shor if the failure persists.

Retain request IDs for support without logging credentials or sensitive request bodies. A failed balance read must not be interpreted as zero.

Access and discovery

The tool catalog is filtered by effective scopes. For tokens containing signed Shor API scopes, access is the intersection of those scopes, the connection grant, and the current membership role. Hosted sign-in with identity-only scopes creates an admin-scoped grant; subsequent exchanges synchronize its scopes to the current role’s allowed API operations. Missing organization, client, or scope claims fail closed. Refresh discovery after changing access; every underlying API call still checks live authorization. The server also provides these read-scoped MCP features:

Feature	Identifier	Behavior
Resource	`shor://business`	Reads the current workspace through `GET /v1/business`.
Prompt	`payroll_review`	Supplies a review checklist covering submitted work, amounts, payment dates, automatic payment settings, and explicit approval confirmation. It performs no write itself.

Protected-resource discovery is available at both GET /.well-known/oauth-protected-resource and GET /.well-known/oauth-protected-resource/mcp on the MCP origin. The metadata advertises OAuth identity scopes (openid, profile, email, offline_access); Shor API permissions are resolved through the connection rather than requested as identity scopes.

Remote host configuration

Use the hosted server address from Settings for your environment. These examples show the production address; they do not certify a host’s support for confirmed writes. For Claude Code:

claude mcp add --transport http shor https://mcp.shorpay.com/mcp

Complete sign-in through the host’s OAuth flow. See Claude Code MCP configuration. For Cursor, the remote entry in its MCP configuration is:

{
  "mcpServers": {
    "shor": { "url": "https://mcp.shorpay.com/mcp" }
  }
}

Complete the OAuth prompt after adding it. See Cursor MCP configuration. For Claude and ChatGPT setup from the dashboard, use Connect AI assistants. The current tools exclude signing/activation, standalone payout initiation, arbitrary ledger addresses, full worker profiles, general search, upcoming-payment summaries, and webhooks. Use Shor’s application for workflows outside this catalog.

​Connection and API routes

​Read tools

​List filters and pagination

​Write tools

​Create a contract draft

​Approve or reject submitted work

​Confirmation, retries, and stale reviews

​Error handling

​Access and discovery

​Remote host configuration