SIGNALS Docs
Reader View

MCP server

Connect AI clients to the Signals v1 API over the Model Context Protocol — catalogue meta-tools, curated tools, plugin tools, install, auth, and LLM instructions.

Overview

Signals ships an MCP (Model Context Protocol) server that exposes the same /api/v1 REST surface external Sanctum clients use. AI clients (Claude, Claude Code, ChatGPT, and any MCP host) discover endpoints, inspect schemas, and invoke operations through authenticated tools — not a separate parallel API.

The Signals API MCP server supports HTTP and local stdio connections. HTTP transport is mounted at /mcp/api; local stdio is available via Artisan.

How coverage works

Three layers share OperationInvoker and OperationDescriber:

Layer What it exposes When to use
Meta-tools list-endpoints, describe-endpoint, execute-endpoint, get-model-schema, search-docs, get-docs-page, list-plugins, get-plugin-manifest Full catalogue coverage — any documented /api/v1 route, plus searchable in-app documentation and installed-plugin metadata
Curated tools First-class tools covering identity and search; API usage, request logs, and webhooks; rentals and projects; catalogue, rates, assets, availability, and custom fields; accounts, permissions, activities, and communications; imports and exports; dispatch, returns, finance, repairs, and stock; warehouses, scheduling, resources, fleet, facilities, and services; documents, approvals, and history; and reports and workflows Prefer these for typed args on common workflows
Plugin tools Claude-safe MCP names (for example, a separately installed plugin may expose plugin-signals-slots-demo-…); CLI keeps plugin:{package}:{tool} Package-specific actions declared in signals.yaml tools[]; none ship with core

Approval tools: list-approval-requests, get-approval-request, approve-approval-request, reject-approval-request, expire-approval-request, request-approval-changes, bulk-approve-approval-requests, delegate-approval, revoke-approval-delegation, and remind-approval-assignee. See Approvals Inbox for visibility and decision rules.

The fixed core surface is the catalogue meta-tools plus the curated tools. Each tool declares whether it is read-only (IsReadOnly); call tools/list for the current set and its annotations. Enabled plugins may add more tools.

Every curated tool result carries price_weight (cost of that call) and units_remaining (quota left on the token) alongside the payload, so an agent can budget without a separate describe-endpoint or whoami round trip.

Every catalogued API endpoint can be described (parameters and typed success response) and executed through these meta tools.

Plugin tools: see Plugin MCP / CLI tools.

Enable (cloud & self-hosted)

  1. Open Admin → Users & Security → MCP & CLI.
  2. Enable MCP server, and leave HTTP transport on for remote clients (stdio is optional for local Artisan).
  3. Mint a personal access token on API Tokens with the abilities your workflows need (catalogue-items:read, rentals:write, etc.). Add mcp:execute when the token may use the open-world execute-endpoint tool, and plugins:read when it may inspect installed plugins or manifests. Prefer least privilege over *.
  4. Ensure the token owner holds the mcp.access permission (and any resource permissions the underlying actions require).
  5. Use the endpoint URL shown on the settings page (typically https://<your-install>/mcp/api).

Settings keys: mcp.enabled, mcp.http_enabled, mcp.stdio_enabled, mcp.read_only, mcp.execute_endpoint_enabled, mcp.session_unit_budget.

Execute-endpoint control

The global mcp.execute_endpoint_enabled setting defaults to true. Turning it off removes execute-endpoint from tools/list and refuses a direct call to a previously cached tool definition. Curated tools remain available.

When the setting is on, a Sanctum personal access token must carry the mcp:execute ability in addition to the ability required by the selected API route. OAuth and stdio connection grants must carry the same abilities.

The record-portal-response, close-stock-check, complete-or-release-repair, post-invoice-write-off and allocate-settlement tools require explicit confirmation (true, 1, "1" or "true") after the user agrees. execute-endpoint refuses these and other confirmation-gated operations, including account anonymisation, invoice issue/void/refunds, credit note issue/apply/void, bulk approval and every DELETE route, with mcp_confirmation_required; use the dedicated tool or the authenticated API. The dedicated tools below cover additional confirmed operations. Confirmation is removed before the REST payload is validated. Each tool retains the REST permissions, token abilities, record policies, and read-only-mode refusal. Irreversible controller methods declare #[RequiresConfirmation]; aliases inherit the same policy, and the matched sub-request route is checked before dispatch. Recording a customer decision also requires documents.record-response.

Confirmed operation MCP tool Required authority
Accept or decline a rental version accept-rental-version, decline-rental-version rentals:write, rentals.edit, rental update policy
Complete a rental change-rental-state with action=complete rentals:write, rentals.edit, rental update policy
Dispatch a flightcase dispatch-flightcase flightcases:write, flightcases.view, flightcase dispatch and rental update policies
Dispatch a warehouse transfer dispatch-warehouse-transfer warehouse_transfers:write, warehouse transfer dispatch policy
Retire an asset retire-asset asset-retirements:write, asset-retirements.create, asset access policy
Publish a price or specification publish-catalogue-item-price, publish-rate-specification rates:write, rates.edit
Publish a pricing rule publish-pricing-rule pricing:write, pricing.manage
Redeliver a webhook delivery redeliver-webhook webhooks:manage, webhooks.manage, webhook ownership
Approve or reject an approval approve-approval-request, reject-approval-request approvals:write, approvals.act, assignment authority
Expire a due approval expire-approval-request approvals:write, approvals.manage, request visibility

All of these operations require confirm=true. Rental version tools accept expected_version and pass the caller's idempotency_key to both the command and HTTP retry boundary. Publication tools require expected_current_revision_id, expected_preview_hash, and reason from the reviewed publication preview. They check publication permission and the write token ability before confirmation or payload validation, returning 403 for an unauthorized caller even when the payload is malformed. Other tools retain the endpoint's HTTP idempotency behavior; a key does not add semantic replay where REST has none. Path arguments follow route names, including warehouse_transfer, catalogue_item, rate_specification, and rule_type.

Read-only mode

Read-only mode (mcp.read_only, off by default) restricts the whole MCP surface to reads, regardless of what the caller's token or permissions allow:

  • Curated write tools (create-rental, change-rental-state, associate-rental, dissociate-rental, create-associated-rental, extend-rental-into-associated, create-custom-field, update-custom-field, deactivate-custom-field, reactivate-custom-field, create-custom-field-group, set-entity-custom-field-values, create-account, create-activity, create-communication-draft, close-stock-check, complete-or-release-repair, share-document-for-approval, record-portal-response) are suppressed server-side — they never appear in tools/list, so a client cannot call what it cannot see.
  • execute-endpoint refuses any verb other than GET/HEAD.
  • Plugin-bridged write tools are suppressed and refused the same way.
  • Curated write tools refuse invocation too, as defence in depth — suppression from tools/list is the primary gate, but a tool instance reached by any other path still checks the posture before touching the API.

Every read-only refusal returns a JSON tool error carrying a machine-readable code, so an agent can tell a policy refusal from a transient failure and stop retrying:

{
  "message": "MCP is in read-only mode: POST requests are not permitted. …",
  "code": "mcp_read_only",
  "read_only": true,
  "method": "POST"
}

Tool-level refusals carry tool instead of method. The code is McpAccessGuard::READ_ONLY_CODE.

A curated tool counts as read-only when it declares the IsReadOnly annotation, so the posture advertised to clients and the posture enforced by the server are the same declaration — new write tools are gated automatically.

The associated-rental hot path is available without dropping to execute-endpoint: get-rental-tree returns stable depth-annotated descendants, associate-rental and dissociate-rental manage an existing child's parent, create-associated-rental creates a fresh child inheriting the parent's context, and extend-rental-into-associated creates a dated child while copying the parent's line tree. change-rental-state accepts to=quote, to=order or to=active with optional dry_run to preview a state transition. Use action=change with status for a within-state status change. It also accepts action=complete or action=cancel plus an optional explicit cascade_rental_ids list; every id must be an open descendant in the same state, and omitted descendants are never changed. For a nonempty list, obtain aggregate_version values from api.v1.rentals.cascade_preview through execute-endpoint, then pass a cascade_expected_versions object keyed by every selected descendant id. A nonempty selection also requires expected_version equal to the preview's root_aggregate_version. A missing version is refused with 422; a stale root or child returns 409 without mutation.

The curated get-rental-cascade-preview tool provides the same read-only preview. Use root_refusal_code and descendant refusal_code to branch on refusals; the corresponding messages are human-readable and may be translated. Allowed verdicts have null refusal codes. Neither this preview nor get-rental-available-actions grants write authority or replaces the command's current-state and version checks.

Read-only mode is a posture switch, not an authorisation layer: it narrows what MCP can do, it never widens it. Normal Sanctum abilities and Gate permissions still apply on top.

Session unit budget

Session unit budget (mcp.session_unit_budget, 0 = unlimited by default) caps how many weighted API units one MCP session may spend. A session is the principal's token context: the personal access token when one is presented, otherwise the resolved user. All calls on one credential share one budget, and the counter expires after api_metering.mcp_session.window_minutes (12 hours by default).

Spend is denominated in the same units as the X-Signals-Units-Charged header — each tool result already reports units_charged, and the budget is decremented by exactly that figure after the call. Nothing is metered twice, and a denial (which charges 0 units) costs the session nothing.

When the budget is spent, every metered tool call — reads and writes alike — returns a normal structured result rather than an error:

{
  "budget_exhausted": true,
  "code": "mcp_session_budget_exhausted",
  "tool": "list-rentals",
  "session_budget": { "limit": 5000, "consumed": 5000, "remaining": 0, "window_minutes": 720 },
  "units_charged": 0,
  "message": "This MCP session has spent its unit budget (5000 units). …"
}

This is deliberate: running out of budget is a stopping point the agent should report, not a failure it should retry. Under a budget, successful tool results also carry session_budget_remaining, and whoami returns the full picture under mcp.session_budget. With the default of 0 nothing is counted and no extra fields appear.

Rental tools use flat fields: starts_at, ends_at, uses_billable_days, billable_days, customer_collects, customer_returns, subtotal, tax_total and total. The billing and customer choices are booleans. list-rentals offers starts_at_from, starts_at_to, ends_at_from and ends_at_to; its filters map uses the same flat field names as REST.

Worked rental and project workflows

Associated rentals with curated tools

Use the typed tools for the association hot path. Read the tree before writing, then pass descendants explicitly when completing or cancelling:

{ "tool": "get-rental-tree", "arguments": { "rental": 42 } }
{ "tool": "associate-rental", "arguments": { "rental": 84, "parent_rental_id": 42 } }
{ "tool": "extend-rental-into-associated", "arguments": { "rental": 42, "title": "Festival load-out extension", "starts_at": "2026-09-08T08:00:00Z", "ends_at": "2026-09-09T18:00:00Z" } }
{ "tool": "change-rental-state", "arguments": { "rental": 42, "action": "complete", "confirm": true, "cascade_rental_ids": [84, 91], "cascade_expected_versions": { "84": 5, "91": 2 }, "expected_version": 17 } }

create-associated-rental creates an empty child inheriting the parent's commercial context; extend-rental-into-associated also copies the parent's line tree. dissociate-rental removes an existing child's parent and is idempotent for a root. The tree read needs rentals:read; the cascade preview and writes need rentals:write. cascade_rental_ids is always explicit, so an omitted descendant never changes silently.

For create-associated-rental and extend-rental-into-associated, pass the reviewed parent's aggregate_version as expected_version. The command checks it under the parent/tree locks before creating the child. A stale version returns version_conflict without creating any child or line events; read the current parent, review it and retry with the new version. The parent's own version does not advance when a child is created. Calls may omit the field.

Project costs and crew through execute-endpoint

Use catalogue endpoints where no dedicated project tool exists. The following tool inputs create a project cost and a project-owned crew assignment; the crew row must include the Labour service_id used to create its linked cost:

{
  "tool": "execute-endpoint",
  "arguments": {
    "route_name": "api.v1.rental_projects.costs.store",
    "path_params": { "rental_project": 12 },
    "body": { "description": "Site power", "amount": "450.00", "quantity": "1", "currency": "GBP" },
    "idempotency_key": "project-12-site-power"
  }
}
{
  "tool": "execute-endpoint",
  "arguments": {
    "route_name": "api.v1.resource-assignments.store",
    "body": { "rental_project_id": 12, "resource_type": "account", "resource_id": 71, "service_id": 19, "starts_at": "2026-09-02T10:00:00Z", "ends_at": "2026-09-02T18:00:00Z", "notes": "Lighting technician" },
    "idempotency_key": "project-12-crew-71-20260902"
  }
}

The project must already have a live linked rental. The first call requires projects:write; the second requires resource-assignments:write and atomically saves the assignment and Labour cost.

Branding and colour settings through execute-endpoint

Read each group with api.v1.settings.show and path_params.group set to branding or colour. A Sanctum PAT may use the scoped settings:read:branding or settings:read:colour ability instead of broad settings:read:

{ "tool": "execute-endpoint", "arguments": { "route_name": "api.v1.settings.show", "path_params": { "group": "branding" } } }
{ "tool": "execute-endpoint", "arguments": { "route_name": "api.v1.settings.show", "path_params": { "group": "colour" } } }

For a partial update, call api.v1.settings.update with settings.manage, settings:write, and only the keys that should change:

{
  "tool": "execute-endpoint",
  "arguments": {
    "route_name": "api.v1.settings.update",
    "path_params": { "group": "branding" },
    "body": { "settings": { "accent_colour": "#047857", "secondary_colour": "#188eaa", "tertiary_colour": "#c07c91" } },
    "idempotency_key": "branding-palette-20260829"
  }
}

Connect

Claude (claude.ai / Claude Desktop)

Desktop and claude.ai's custom connector UI only offers OAuth — it does not accept a bearer token. The MCP server supports this via Laravel Passport (see OAuth for Desktop/claude.ai below).

Settings → Connectors → Add custom connector.

  • URL: https://<your-install>/mcp/api
  • Auth: none to configure — pasting the URL and continuing opens a sign-in page. Desktop/claude.ai register themselves as an OAuth client automatically (dynamic client registration); there's no client ID/secret to create or paste.

The user who signs in must hold mcp.access, same as the PAT path. The approval screen records the explicit API abilities for that OAuth connection. The mcp:use transport scope does not grant API access by itself.

Claude Code

claude mcp add --transport http signals https://<your-install>/mcp/api --header "Authorization: Bearer <token>"

Replace <your-install> and <token> with your host and PAT. The same command is copyable from Admin → MCP & CLI.

ChatGPT

Settings → Connectors → Advanced / Developer mode → add an MCP server.

  • URL: https://<your-install>/mcp/api
  • Auth: Bearer personal access token

Generic MCP JSON

Many hosts accept a config entry shaped like:

{
  "mcpServers": {
    "signals": {
      "url": "https://<your-install>/mcp/api",
      "headers": {
        "Authorization": "Bearer <token>"
      }
    }
  }
}

Exact keys vary by client — prefer the client's native Streamable HTTP MCP connector settings when available (the HTTP+SSE transport is deprecated by the MCP specification).

Artisan stdio (local)

When mcp.stdio_enabled is on, approve a named stdio grant and configure the process identity:

php artisan signals:connection-grant approve \
  [email protected] --kind=stdio --connection=local-agent \
  --ability=accounts:read --ability=rentals:read

export [email protected]
export MCP_STDIO_CONNECTION=local-agent
php artisan mcp:start signals-api

Startup fails if the user, setting, or grant is missing, inactive, or revoked. Each call rechecks the grant generation, so revocation fails closed. A connection keeps one stable idempotency owner across grant rotations, but its authorization fingerprint changes. An original outcome therefore cannot be disclosed or executed again after rotation, revocation, permission change, or warehouse-scope change. Use signals:connection-grant list and revoke --grant-id=<id> to manage local connections.

OAuth for Desktop/claude.ai

Claude Desktop and claude.ai's custom connector UI only supports OAuth — it runs discovery against the connector URL and fails ("couldn't reach server") if the well-known metadata endpoints aren't served. The MCP server provides these via laravel/mcp's built-in OAuth support backed by Laravel Passport:

  • GET /.well-known/oauth-protected-resource(/{path}) and GET /.well-known/oauth-authorization-server(/{path}) — discovery metadata. Public, unauthenticated; gated only by the same mcp.enabled + mcp.http_enabled settings switch as the MCP endpoint itself (settings off → 404, same as /mcp/api).
  • POST /oauth/register — dynamic client registration (RFC 7591). Desktop/claude.ai call this automatically the first time they connect; no manual client setup.
  • GET/POST /oauth/authorize, POST /oauth/token — the standard Passport authorization-code + refresh-token flow. The /oauth/authorize approval screen requires a Signals web session, so connecting opens a normal sign-in page if the browser isn't already authenticated.

All tokens are issued under the mcp:use scope (the only scope the authorization server advertises); the MCP endpoint checks for it defensively even though every dynamically-registered client is granted it automatically.

Auth path is symmetric with the PAT path: the /mcp/api route accepts both auth:sanctum and auth:api. Both land in EnsureMcpAccess, which enforces the transport settings and mcp.access. A PAT forwards its abilities. OAuth resolves the active stored connection grant and installs its explicit abilities through OperationInvoker. Grant generations have distinct audit identities but share one connection-level idempotency owner. A changed authorization fingerprint refuses original replays.

Token ability scoping

Concern Guidance
MCP gate The resolved user (PAT owner or OAuth sign-in) must have mcp.access
API abilities (PAT path) execute-endpoint requires mcp:execute, plugin inspection requires plugins:read, and curated tools use the selected route's ability directly — missing ability → HTTP 403
API abilities (OAuth path) The active OAuth connection grant supplies explicit abilities. mcp:use only opens the transport
API abilities (stdio path) The configured named stdio grant supplies explicit abilities and is rechecked for revocation
Least privilege Scope PATs and connection grants to the resources the agent may touch; rotate or revoke them when no longer needed
Writes Prefer dedicated write-capable tokens only where needed; require Idempotency-Key when settings enforce it

Data egress and logging

Signals is bring-your-own-model: core Signals sends nothing to any model provider itself. When you connect an MCP client, it is that agent's provider — Anthropic, OpenAI, whoever runs the model — that receives the data, because the agent reads records through the tools and then reasons over them in its own context. The blast radius is therefore exactly what the connecting token can read, which is why ability scoping (above) is the real control. On our side, requests are logged as metadata by the LogApiRequest middleware (app/Http/Middleware/LogApiRequest.php), not as content, unless you opt in.

  • Always logged (when api_metering.logging_enabled, default on): method, path, route name, resource/operation, status code, duration, request/response byte counts, price weight and weighted units, token id, user id, first ability, IP address, and user agent.
  • Request/response bodies are NOT logged by default. They are captured only when API_METERING_CAPTURE_BODIES=true, and even then are redacted (Authorization, X-Signals-Signature, password, and the rest of config/api_metering.redaction) and truncated to API_METERING_BODY_MAX_BYTES (4 KB default).
  • Tool invocations use the caller's external-principal budget. PAT calls are metered against the token. OAuth, stdio, and CLI calls are metered against their persisted connection grant. MCP tool calls execute the same API operations and each result carries price_weight, units_charged, units_remaining, and daily_remaining so an agent can budget its own session.
  • Writes made over MCP are stamped via: mcp in the audit trail, so agent activity is separable from UI and CLI activity after the fact.
  • Embeddings are the one place core Signals calls out, and they are optional and separately documented — see AI embeddings & configuration.

The short answer for early adopters: Signals itself ships no model provider and sends no telemetry; its only outbound calls are operational (see below). Connecting an agent means that agent's provider sees whatever its token can read, so scope the token and, if you want a content-level record of what was read, turn body capture on deliberately.

Core Signals makes these outbound calls besides embeddings:

  • ECB exchange rates, fetched daily by the scheduler from ecb.europa.eu.
  • Release check against Packagist for available upgrades (cached).
  • VIES VAT number validation, when VAT numbers are checked.
  • what3words (and OpenStreetMap Nominatim geocoding) for address lookups.
  • Plugin registry index fetches when browsing or installing plugins.

Meta-tools

Tool Role
list-endpoints Search/filter the catalogue (resource, method, keyword); paginated compact rows. Use the stock_checks.counts.* routes for stock check counts.
describe-endpoint Full params, request/response schemas, filter/sort fields, price_weight, filter aliases (API/filter name → schema column) and enum encodings (enum_string for enum-backed fields, with stable lowercase snake_case values) per field — resolves the "is state an int or a string here" question without a live call.
execute-endpoint When globally enabled, invoke any catalogue endpoint when no curated tool fits. Sanctum PATs require mcp:execute plus the selected route's ability. Invalid filters return a coded 422; unsupported sorts are listed in meta.ignored_sorts.
get-model-schema Field metadata for a model slug. Defaults to a compact projection (name, label, type, filterable, sortable, searchable, required, aliases); pass full=true for the complete field-definition payload — describe-endpoint covers the common case at a fraction of the tokens.
search-docs Search in-app documentation titles, headings, descriptions, and page content. Each query term must match; title and heading matches rank first, including terms split across fields. Returns compact excerpts rather than full page bodies; use limit to cap results (10 by default, 25 maximum).
get-docs-page Return one documentation page as raw Markdown, including frontmatter title/description. Live endpoints, fields, and abilities directives remain unexpanded and are listed in live_directives; oversized sources are capped at 100 KB with truncated: true.
list-plugins List up to 50 installed plugin packages in package order with name, version, status, and capability grants. Pass offset to retrieve later packages. Requires plugins.manage; Sanctum PATs also require plugins:read.
get-plugin-manifest Return one installed package's stored manifest. Values under secret-, token-, password-, or key-like keys are recursively replaced with [redacted]; requires plugins.manage, and Sanctum PATs also require plugins:read.

API usage, request logs, and webhooks

Tool REST route Required access
get-api-usage GET /api/v1/usage api.usage.view + api-usage:read
list-request-logs GET /api/v1/request_logs api.logs.view + api-log:read
list-webhooks GET /api/v1/webhooks webhooks.manage + webhooks:manage
get-webhook GET /api/v1/webhooks/{webhook} webhooks.manage + webhooks:manage
list-webhook-deliveries GET /api/v1/webhooks/{webhook}/logs webhooks.manage + webhooks:manage
revoke-api-token DELETE /api/v1/api-tokens/{token} api.access + api-tokens:manage; revokes one of the caller's own tokens and is unavailable in read-only mode

The usage tool accepts preset or custom windows and grouping by token, endpoint, resource, day, or status. Request logs expose typed route, status, token, channel, created-at range, sort, and pagination arguments. Webhook list and show responses use the existing REST projections, which never include the delivery secret.

Custom fields

Tool Required token ability Role
list-custom-fields custom-fields:read List field definitions, optionally filtered by module type.
get-custom-field custom-fields:read Fetch one definition with its non-empty value usage count.
describe-custom-field-schema custom-fields:read Describe the registered module, field definitions, groups, and accepted value schema.
create-custom-field custom-fields:write Create a definition through the canonical custom-field action.
update-custom-field custom-fields:write Patch a definition; field type remains immutable once values exist.
deactivate-custom-field custom-fields:write Disable a definition without deleting its values.
reactivate-custom-field custom-fields:write Re-enable a disabled definition.
list-custom-field-groups custom-fields:read List configured field groups.
create-custom-field-group custom-fields:write Create a field group through the REST action.
get-entity-custom-fields custom-fields:read Read values from an entity selected by registered module_type and entity_id.
set-entity-custom-field-values custom-fields:write Patch entity values through that module's guarded update action.

Definition writes also require the corresponding custom-fields.manage permission. Entity reads and writes run the target model's policy and preserve its lifecycle, validation, audit, and event rules; they never write the custom_field_values table directly. Use the exact module key returned by describe-custom-field-schema (for example Account, Rental, or Equipment Test).

Resources & prompts

Beyond tools, the server registers MCP resources (read-only reference documents an agent can fetch without spending a tool call) and prompts (grounded multi-step flows):

Resource Contents
schema://models Index of every model whose field metadata is browsable; each row carries the schema://models/{model} template URI.
schema://models/{model} Field metadata for one model (filterable, sortable, searchable, aliases) — same projection as get-model-schema.
events://webhook Every domain event a webhook subscription may target, grouped by entity (resource.action names).
Prompt Flow
resolve-shortage Walk a stock shortage to resolution — detection, resolver options, sub-hire path — with dry_run and expected_version guardrails.
quote-from-enquiry Turn a free-text enquiry into a draft quote: match the account, build the rental and items, check availability.

Resources and prompts ride the MCP transport itself (no new REST routes) and honour the same token ability scoping as the tools.

LLM instructions

Use this client workflow:

Workflow

  1. Call whoami first when you don't already know the token's abilities, roles, rate limit, or remaining quota — no ability required, so it never 403s.
  2. When you need to find out how a Signals feature works, call search-docs with the user's terms, then pass the selected result's slug to get-docs-page for the complete Markdown page. Search returns excerpts of up to 300 characters; fetch the page before relying on details outside the excerpt. The documentation search dialog uses the same term ranking and searches full page bodies on the server. Its discovery index contains metadata without page bodies, and query responses contain at most 50 matching pages with excerpts.
  3. Prefer curated tools for identity and search; API usage, request logs, and webhooks; rentals and projects; catalogue, rates, assets, availability, and custom fields; accounts, permissions, activities, and communications; imports and exports; dispatch, returns, finance, repairs, and stock; warehouses, scheduling, resources, fleet, facilities, and services; documents, approvals, and history; and reports and workflows. They provide typed arguments with the same Sanctum token abilities as the REST API.
  4. list-endpoints — search/filter the catalogue (resource, method, keyword); paginated compact rows. Each row identifies the route, method, URI, summary and required ability.
  5. describe-endpoint — full params, request/response schemas, filter/sort fields (with per-field alias and enum-encoding metadata), price weight.
  6. execute-endpoint — invoke any catalogue endpoint when no curated tool fits.
  7. get-model-schema — Field metadata for a model slug; compact by default, full=true for the complete payload.
  8. Need revenue/utilisation/outstanding rolled up rather than paged and summed client-side? Use the aggregate curated tool (or GET /api/v1/aggregate/{model}): group_by (+ bucket=month|week|day for dates), measure, fn (sum|avg|min|max|count|count_distinct).

Writes

  • Pass Idempotency-Key on every POST/PUT/PATCH: the API dedupes on key+body unconditionally (identical key+body replays the original response, no duplicate row), regardless of the api.require_idempotency_key setting — that setting only controls whether the header is required, not whether it's honoured. whoami reports require_idempotency_key for the current token.
  • Only POST mutates. Every catalogue GET is read-only (readOnlyHint: true is accurate) — stock check lifecycle operations use POST.
  • Non-2xx responses are returned as structured tool errors (status + JSON body), not exceptions. 4xx bodies include a machine-readable code (e.g. invalid_state, invalid_date_window, or a guard-specific code) alongside the human-readable message/errors — branch on code, not on message text.
  • Composite create: create-rental accepts an lines array so a quote can be built (header + line items) in one call instead of 1 + N round trips.
  • Need more than a handful of rows? POST {resource}/bulk (e.g. activities/bulk, accounts/bulk) accepts an array of row payloads and returns per-row results — 201 when every row succeeds, 207 when some fail; check each row's status rather than the top-level HTTP status alone.
  • Rental transitions (transitions with a to target, or change_status) accept dry_run: true to run the guard pipeline and return a verdict in body.data, containing dry_run, allowed, reason, and code — use it to preview feasibility before spending a mutating call.
  • Writes made through this MCP server are stamped with via: mcp in the audit trail, distinguishable from UI/CLI writes.

Reads / pagination

  • List endpoints accept cursor=<token> (start with cursor=1) as an alternative to offset page= for large sweeps; the response meta then carries next_cursor/prev_cursor instead of total/page.
  • Sparse fieldsets (fields=id,name,sku) work on index, show, and action/lifecycle endpoints — ask for only what you need on high-fan-out responses (e.g. create-account's nested profile/addresses/emails).
  • semantic-search returns embeddings_available: false (plus a message) rather than a silent empty result set when ai.enabled is off — check that flag before concluding "no matches".

Filtering (list endpoints / execute-endpoint)

  • Pass a field/operator map under filters: {"name":{"contains":"stage"},"id":{"in":[1,2]},"custom_fields.attributes":{"contains":{"colour":"blue"}}}. Scalars mean equality. The API receives the same map under filter.
  • Curated convenience arguments combine with explicit filters. Duplicate canonical field/operator pairs, including aliases and query.filter conflicts, are rejected. Distinct range operators combine with AND.
  • Use native arrays for in/not_in, native objects for JSON containment, and the boolean true for unary null/not_null/blank/present. Empty strings remain values.
  • Use describe-endpoint for permitted filter and sort fields, and get-model-schema / describe-custom-field-schema for field types and operators. Only published relations are filterable; custom-field paths use custom_fields.<key>.
  • filters.search continues indexed search on supported lists; filters.similar_to selects semantic neighbours where available. Ranked cross-resource search uses the search tool's query argument.
  • Invalid filters return 422 with unknown_filter_field, invalid_filter_operator, invalid_filter_value, or filter_limit_exceeded. Correct the reported condition before retrying. Requests allow at most 50 conditions and 100 entries per list; see API Conventions for all limits.
  • Array query parameters use unbracketed tool argument names (types). Sort with sort=name or sort=-created_at; unsupported sorts appear in meta.ignored_sorts.

Auth

  • HTTP transport accepts a Sanctum bearer token (Claude Code) or a Passport OAuth session (Claude Desktop / claude.ai) whose resolved user holds mcp.access — see OAuth for Desktop/claude.ai.
  • execute-endpoint requires mcp:execute and the selected route's ability for PAT, OAuth, and stdio connections. Missing ability or application permission yields 403.

Plugins

  • Use list-plugins and get-plugin-manifest to inspect installed packages when the resolved user holds plugins.manage and the connection has plugins:read. Secret-like manifest values are always redacted.
  • Enabled plugins may register additional tools; MCP names are Claude-safe (hyphenated). CLI still uses plugin:{package}:{tool} (see PluginToolRegistry).

Error shapes

  • Validation failures: 422 with Laravel message + errors map, plus a machine-readable code on state/status/guard/window denials (e.g. invalid_state, invalid_date_window) — branch on code rather than parsing message.
  • Auth: 401 unauthenticated, 403 forbidden (ability or permission).
  • Not found: 404. Success bodies use data and optional root meta; forwarded REST responses appear under MCP body.data and body.meta.