MCP authorization
Toolora’s public Model Context Protocol (MCP) endpoint accepts a verified bearer
token at /mcp. Business tools then resolve the active company, require current
permissions and check the requested resource. Authentication to the transport
alone does not grant business access. Metadata resources and business resources
have different checks.
The MCP interface contract owns names,
arguments and response conventions. The connected server’s tools/list describes
its registered interface. This reference groups authorization rules; it does not
replace that catalogue. /api/mcp-gateway is a separate HTTP integration for
contractor matching, with its own route policies. It is not the /mcp transport.
Transport and identity
Section titled “Transport and identity”The API lifespan starts a stateless Streamable HTTP server with JSON responses.
MCP_ENABLED=false removes the configured mount and discovery routes at startup.
An existing mount outside its running lifespan answers 503. The two protected-
resource metadata locations are public discovery documents:
/.well-known/oauth-protected-resource/mcp and its root form without /mcp.
An absent or rejected bearer receives the transport’s 401 challenge.
| Setting or check | Implemented meaning |
|---|---|
MCP_RESOURCE_URL |
Advertised resource identifier; default https://api.toolora.se/mcp. |
MCP_ISSUER_URL |
Advertised authorization server; default https://app.toolora.se/auth/v1. These defaults are not an observation of deployed settings. |
| Advertised scopes | email, plus openid when MCP_ADVERTISE_OPENID is enabled. These identity scopes are separate from business capabilities such as invoices:read. |
| Token verifier | Delegates to the shared API _verify_jwt path, including GoTrue verification and reconstruction of company memberships. See authentication for signing-key checks and fallbacks. |
| Required transport scopes | The server does not configure required_scopes. Mapping a token’s scope into SDK metadata does not enforce a per-tool business permission. |
| Token resource audience | validate_token_resource=False explicitly disables the SDK’s resource-URL audience check. Toolora uses its existing Supabase token validation; the asymmetric-token path checks aud=authenticated. It does not establish audience binding to the advertised MCP URL. |
| Client identity | Verified token bytes supply client_id; a token without it receives the toolora-session marker. A separate OAuth-only client-ID requirement is not implemented here. |
The MCP authorization specification, 2025-11-25 requires validation that a token was issued for the intended MCP resource. Toolora’s disabled resource-audience check is a concrete difference from that requirement, not evidence of complete protocol compliance. Resolving it needs a separate authentication decision and verification. Selected database reads also forward the incoming bearer rather than obtaining a separate resource-specific token. The implemented data flow is described below; this review does not certify token handling against every protocol requirement.
Common business-call checks
Section titled “Common business-call checks”mcp_access.caller reads the verified identity held by the transport. It requires
an active company, then checks projects:read
for ordinary callers against current role data. It also re-fetches an active,
non-deleted person for that Auth user and company. Company scope comes from this
identity, rather than a tool argument selected by the client.
A person with only projects:read_own cannot enter business tools through this
common gate. There is no universal staff flag requirement in caller; narrower
tools may require one. Platform administrators bypass the common capability
lookup, but still need an active company and a person in it. Further exceptions
are local to the called helper; administrator status does not turn a foreign
project ID into an accessible resource.
flowchart TD B[Bearer request to /mcp] --> V[Shared API token verification] V --> M[Catalogue, schemas, Skill and static UI resources] V --> C[Business caller: company, projects:read, person and budgets] C --> G[Tool-specific capability and audience checks] G --> R[Requested record or continuation scope] R --> O[Read, proposal, technical job or image write] O --> A[Result and selected audit event] G -->|Denied| E[Controlled tool error] R -->|Foreign or missing| E
Tool authorization families
Section titled “Tool authorization families”The registration review covered 40 tools in the inspected default configuration, including two image receivers annotated for app visibility. Runtime feature flags and client presentation can affect the interface shown. The groups below cover the registered families; examples identify their additional rules. Every business tool in these groups uses the common caller gate first, although argument validation can reject a call before that gate runs.
| Tool family | Additional permission and resource conditions | Source owner |
|---|---|---|
Project search and operations reads: find_project, six operations readers, project_journal, completion_readiness |
Search uses the caller’s bearer against project search. Detail readers constrain the project to the caller’s company and non-deleted state before assembling their selected context. An internal visibility mode is not a staff-role check. Completion readiness reads evidence; it does not complete the project. | operations.py, project_depth.py, completion.py |
Overviews: active_projects, field_today, daily_briefing, my_attention, recent_activity, project_history |
Company/person and producer-specific scope; optional sections use narrower capabilities. Examples include salary:read for margins, training:read for certifications, conversations:read for dialogue and time_reports:read for reported time. Missing sections can appear in missing_info rather than refusing the whole overview. |
pulse.py, attention.py, recent_activity.py, project_history.py |
notifications, people_availability |
Notifications select the caller’s person/company. Availability separates ordinary display from absence reasons (schedule:read_absence_details), certifications (training:read) and person links (people:read). |
notifications.py, availability.py |
project_time, project_money, project_dialogue |
Project-scoped calls check company ownership; dialogue can instead start from an authorized conversation ID. Time, salary, invoice and work-order sections have their own capabilities; billing requires invoices:read, and the material aspect also requires work_orders:read. Dialogue requires conversations:read and canonical audience checks before body/attachment reads. |
project_depth.py, communication_documents.py |
customer_context, subcontractor_context |
Customer context adds parties:read, with narrower financial/dialogue sections. Subcontractor context requires staff membership in the selected company as well as project permission; its staff predicate has no administrator override. These are office reads, distinct from portal access. |
relations.py |
quote_customer_flow_readiness, customer_journey_readiness |
Quote readiness requires quotes:read and a quote in the company. Customer journey starts with project scope; invoice-specific reading adds invoices:read. |
quote_readiness.py, customer_journey.py |
business_records |
Staff access or platform-admin exception, then the record kind’s capabilities. Quote/article reads use quotes:read; invoices, purchases and payment events use invoices:read; delivery notes use work_orders:read; accounts/vouchers use finance:gl:read; payroll receipts require both time_reports:read and salary:read. Sections can add billing:read. Parent and child queries retain company scope. |
business_reads.py: RECORDS, SECTIONS, _guard |
search_records, sync_changes |
Search admits only permitted source types and revalidates individual hits. Change reads call the database RPC with the caller’s bearer, not a service-role bearer, then recheck message audiences. See continuation rules below. | discovery.py, changes.py |
document_inbox |
Candidate/intake reads require document_intake:read. Content mode dispatches by source: project files require project/file scope; saved mail-candidate fields require read permission; archived originals require document_intake:review; conversation attachments require dialogue permission/audience; purchase originals require staff or admin, invoices:read and invoice/source ownership. |
document_inbox.py, communication_documents.py, purchase_original.py |
run_document_job, propose_document_review |
Technical document operations require document_intake:operate. Proposals bind candidate, version and source hash. The proposal service additionally checks the effective capability set; the outer administrator bypass alone does not supply a missing operate capability to that check. |
document_inbox.py, agent_proposals.py |
propose_quote_draft, get_quote_draft |
Write requires quotes:write; read accepts quotes:read or write permission. Platform admins receive those codes in this adapter. References stay within the company; editing additionally requires the proposal’s author and current expected revision. Company readers can read other authors’ drafts. |
quote_drafts.py, quote_agent_drafts.py |
invite_user, request_capability, capability_requests |
Invitation proposal requires people:update and role-grant containment, with an explicit platform-admin exception. A capability request records feedback, not a role grant. Reading the request register requires tenant:update. |
access.py, feedback.py, agent_proposals.py |
test_image_upload, receive_image_upload |
Common caller and bounded transfer validation. The test receiver inspects/discards bytes rather than creating business records. App visibility annotations are presentation metadata, not the caller’s authority. | image_upload.py |
attach_quote_image, receive_quote_image |
Opening the picker uses the common gate without looking up the draft. Actual storage requires quote-write authority and an eligible company-bound draft plus validated bytes/path/limits. The app receiver applies the same storage helper. | quote_assets.py, services/quote_assets.py |
server_version |
Common caller gate, then tool-name/argument validation. Returns release metadata, not business authority. | versioning.py |
The matrix identifies enforcing source owners, not a promise that every field in every composite response has been independently certified. The broader interface topic owns tools and response structure at its declared source scope.
Resources, links and continuations
Section titled “Resources, links and continuations”| Entry or continuation | Binding and checks |
|---|---|
| Tool catalogue, contract schema, Skill, prompts and static app HTML | Protected by transport authentication. These handlers do not all invoke the business caller gate. Reading them does not prove project permission; the schema resource first validates that the tool is registered. |
| Project-state resource | toolora://project/{project_id} composes project summary and pending decisions through their ordinary caller/project checks. Both composed calls can produce audit events and budget checks. |
| Binary document resource blocks | Bytes are returned by the authorized content call. Their URI labels the embedded block; it is not a registered reusable download grant. Follow the tool’s returned arguments to read more. |
Ordinary offsets and section next_arguments |
The next request invokes the tool again, including caller, capability and record checks. Offsets are positions, not credentials or immutable snapshots; intervening edits can change a live list. |
| Search cursor | Stored cursor and search session are looked up by company and Auth user; page size and expiry are checked. Current source permissions, record relationships and content fingerprints are revalidated before returning hits. A retained rank does not preserve revoked authority. |
| Change cursor | The RPC uses token/database company context and binds the cursor to company and Auth user, page size, expiry and visibility/source state. Changed visibility or source sets require resynchronization; retained-history expiry has its own reason. Event-page replay follows those rechecks; an existing replacement/resync receipt can be returned earlier. |
| Toolora app deep link | An app URL identifies a destination. The app/API must authorize the subsequent request; possession of the URL grants nothing. Returned signed links or bytes already disclosed are not recalled by a later role change. |
Most privileged readers use explicit service-role filters. find_project, search
index snapshots and sync_changes also use caller-bearer database operations.
Their token company claim can differ from the API’s reconstructed company context
during transitions. The company-context article
owns this distinction; this review does not establish parity during a switch.
Database cursor and RLS behaviour was inspected, not executed here.
Allowed and refused calls
Section titled “Allowed and refused calls”An authenticated caller in company A asks for project_summary of project P.
The transport verifies the token; caller checks active company, project-read
permission, live person and budgets. core.project re-fetches P by ID, company A
and non-deleted state. Only then does the reader build its context, bounded
evidence envelope and audit event.
If P belongs to company B, that lookup returns no record and the tool returns a
[not_found] error. Removing project-read permission instead causes
[missing_capability] before the reader builds project context. A valid token
can still read the catalogue, Skill and schema in that case; the project-state
resource is refused through its composed business checks.
For document originals, an ID is rechecked against its current company, parent and audience before Storage reads. A supplied storage path or arbitrary download URL is not accepted as a replacement for those source IDs. Content pagination re-enters that same reader; purchase PDF bytes are also checked against registered size and hash. Document storage and signed links and conversation audiences describe the adjacent boundaries.
Effects, errors and audit
Section titled “Effects, errors and audit”Read-only and destructive annotations guide the client. They are not server authorization or proof of user confirmation. Read tools can still record audit events, and search/change flows maintain technical cursor state.
Invitation and document-review tools record proposals. Quote-draft tools create or revise a proposal; the separate Toolora confirmation flow creates the native quote. Document jobs perform technical synchronization or enqueue interpretation; they are not merely textual suggestions. Image attachment stores bytes and asset metadata on the draft before any later quote confirmation. Those effects must be distinguished from human confirmation of native business changes. The server cannot infer explicit user intent from an annotation alone.
| Result | Meaning |
|---|---|
HTTP 401 |
Transport bearer missing or rejected. |
HTTP 503 before a running mount |
Transport lifecycle unavailable. |
Tool result with isError |
Controlled tool failure, commonly [auth_required], [no_active_company], [missing_capability], [forbidden], [not_found], [invalid_argument], [conflict], [budget_exhausted] or [unavailable]. These are not a universal HTTP 403/404 mapping. |
| Resource failure | Uses the protocol resource/error path; do not assume the identical tool isError shape or preserved inner message. |
Successful result with found=false |
An empty/absent read within that tool’s contract; not interchangeable with an authorization error. |
Caller budgets default to 1,000 calls per person per UTC day and 60 per minute.
They count MCP tool_invoked audit events. A failed count lookup continues as
zero, so this is a supplementary limit, not a strict atomic quota. Audits record
company/person, client ID, tool, output-section names, response size and selected
metadata rather than copying business payloads. Coverage is not universal:
metadata reads need not emit business events, initialization audit failures are
caught, and a refusal before an instrumented result is not proof of an audit row.
Verification scope
Section titled “Verification scope”The focused selection passed 335 backend tests using synthetic identities, filtering clients and substituted token verification, database/RPC, Storage and external effects. It includes actual local Streamable HTTP calls, capability and foreign-resource refusals, resource composition, search cursor binding, content containment and proposal/image checks. It does not execute live OAuth issuance or database cursor policy.
A separate synthetic transport probe confirmed readable catalogue/Skill/schema with no project-read capability, while the business tool and project-state resource were refused. Registration inspection found the 40 tools classified above. The delivery PR records the selections, substitutions and probe recipe. Earlier API identity evidence remains scoped to its own reviewed revision and was not repeated.
Resource-audience binding, API/database company transitions, live revocation, concurrent quotas and exhaustive flag/client combinations remain unverified or explicit implementation differences. No runtime setting or authorization policy was changed by this source review.