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)
- Open Admin → Users & Security → MCP & CLI.
- Enable MCP server, and leave HTTP transport on for remote clients (stdio is optional for local Artisan).
- Mint a personal access token on API Tokens with the abilities your workflows need (
catalogue-items:read,rentals:write, etc.). Addmcp:executewhen the token may use the open-worldexecute-endpointtool, andplugins:readwhen it may inspect installed plugins or manifests. Prefer least privilege over*. - Ensure the token owner holds the
mcp.accesspermission (and any resource permissions the underlying actions require). - 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 intools/list, so a client cannot call what it cannot see. execute-endpointrefuses any verb other thanGET/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/listis 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})andGET /.well-known/oauth-authorization-server(/{path})— discovery metadata. Public, unauthenticated; gated only by the samemcp.enabled+mcp.http_enabledsettings 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/authorizeapproval 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 ofconfig/api_metering.redaction) and truncated toAPI_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, anddaily_remainingso an agent can budget its own session. - Writes made over MCP are stamped
via: mcpin 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
- Call
whoamifirst when you don't already know the token's abilities, roles, rate limit, or remaining quota — no ability required, so it never 403s. - When you need to find out how a Signals feature works, call
search-docswith the user's terms, then pass the selected result's slug toget-docs-pagefor 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. - 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.
list-endpoints— search/filter the catalogue (resource, method, keyword); paginated compact rows. Each row identifies the route, method, URI, summary and required ability.describe-endpoint— full params, request/response schemas, filter/sort fields (with per-field alias and enum-encoding metadata), price weight.execute-endpoint— invoke any catalogue endpoint when no curated tool fits.get-model-schema— Field metadata for a model slug; compact by default,full=truefor the complete payload.- Need revenue/utilisation/outstanding rolled up rather than paged and summed client-side? Use the
aggregatecurated tool (orGET /api/v1/aggregate/{model}):group_by(+bucket=month|week|dayfor dates),measure,fn(sum|avg|min|max|count|count_distinct).
Writes
- Pass
Idempotency-Keyon every POST/PUT/PATCH: the API dedupes on key+body unconditionally (identical key+body replays the original response, no duplicate row), regardless of theapi.require_idempotency_keysetting — that setting only controls whether the header is required, not whether it's honoured.whoamireportsrequire_idempotency_keyfor the current token. - Only
POSTmutates. Every catalogueGETis read-only (readOnlyHint: trueis accurate) — stock check lifecycle operations usePOST. - 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-readablemessage/errors— branch oncode, not on message text. - Composite create:
create-rentalaccepts anlinesarray 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 —201when every row succeeds,207when some fail; check each row'sstatusrather than the top-level HTTP status alone. - Rental transitions (
transitionswith atotarget, orchange_status) acceptdry_run: trueto run the guard pipeline and return a verdict inbody.data, containingdry_run,allowed,reason, andcode— use it to preview feasibility before spending a mutating call. - Writes made through this MCP server are stamped with
via: mcpin the audit trail, distinguishable from UI/CLI writes.
Reads / pagination
- List endpoints accept
cursor=<token>(start withcursor=1) as an alternative to offsetpage=for large sweeps; the responsemetathen carriesnext_cursor/prev_cursorinstead oftotal/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 nestedprofile/addresses/emails). semantic-searchreturnsembeddings_available: false(plus amessage) rather than a silent empty result set whenai.enabledis 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 underfilter. - Curated convenience arguments combine with explicit filters. Duplicate canonical field/operator pairs, including aliases and
query.filterconflicts, are rejected. Distinct range operators combine with AND. - Use native arrays for
in/not_in, native objects for JSON containment, and the booleantruefor unarynull/not_null/blank/present. Empty strings remain values. - Use
describe-endpointfor permitted filter and sort fields, andget-model-schema/describe-custom-field-schemafor field types and operators. Only published relations are filterable; custom-field paths usecustom_fields.<key>. filters.searchcontinues indexed search on supported lists;filters.similar_toselects semantic neighbours where available. Ranked cross-resource search uses thesearchtool'squeryargument.- Invalid filters return
422withunknown_filter_field,invalid_filter_operator,invalid_filter_value, orfilter_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 withsort=nameorsort=-created_at; unsupported sorts appear inmeta.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-endpointrequiresmcp:executeand the selected route's ability for PAT, OAuth, and stdio connections. Missing ability or application permission yields 403.
Plugins
- Use
list-pluginsandget-plugin-manifestto inspect installed packages when the resolved user holdsplugins.manageand the connection hasplugins: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:
422with Laravelmessage+errorsmap, plus a machine-readablecodeon state/status/guard/window denials (e.g.invalid_state,invalid_date_window) — branch oncoderather than parsingmessage. - Auth:
401unauthenticated,403forbidden (ability or permission). - Not found:
404. Success bodies usedataand optional rootmeta; forwarded REST responses appear under MCPbody.dataandbody.meta.