MCP reference

Use this page as the canonical reference for Orgonaut's remote MCP surface.

Plan availability: authenticated account MCP access is available on every plan, including trials, so an organisation saved from a guest draft can connect straight away. Anonymous guest modelling on the agent endpoint does not require a plan. Tenant-hosted OAuth metadata is plan-gated. Shared-host metadata, when enabled, is public and does not itself grant tenant access.

Use Connect MCP clients for OAuth and bearer-token setup, and use API reference for REST endpoints and OpenAPI contracts. /docs/api does not describe the MCP tool catalog.

What MCP is for

Orgonaut's MCP server is the agent-oriented semantic surface for the product.

In V1 it is:

• tenant-scoped
• read-first with governed scenario action planning and confirmation
• designed for org review, scenario review, settings review, operational status checks, and approved scenario-scoped change workflows

Canonical endpoint

The canonical authenticated MCP endpoint is:

• /mcp/orgonaut

Example tenant-hosted URL:

• https://acme.orgonaut.co/mcp/orgonaut

Shared-host OAuth for every MCP-entitled organisation uses https://app.orgonaut.co/mcp/orgonaut. Consent binds each connection to one explicitly selected organisation. The tools, resources, prompts and permission checks are the same; ambient web organisation/scenario selections do not change the connection. See Connect MCP clients for availability and OAuth setup.

For OAuth-capable clients, the matching metadata endpoints are:

• https://acme.orgonaut.co/.well-known/oauth-protected-resource/mcp/orgonaut
• https://acme.orgonaut.co/.well-known/oauth-authorization-server/mcp/orgonaut

The canonical OAuth transport scope is:

• mcp:use

Each connection can make up to 120 MCP requests per minute. Over the limit, the server returns HTTP 429 with a Retry-After header; plan request quotas still apply.

Agent entry point and guest tools

https://app.orgonaut.co/mcp/orgonaut-agent combines a core subset of the account catalog with guest tools: 40 tools, listed on a single tools/list page. Some MCP hosts load only a limited number of tools, so these detail and operations tools are only on the full account server: business.capability.detail, ai.solution.deployments, transformation.case.readiness, department.profile, initiative.list, team.velocity, scenario.timeline, scenario.history, tenant.settings, reference.list and operations.status. initialize, tools/list and catalog discovery work anonymously. Each tool declares its authentication requirements; account tools keep mcp:use OAuth and tenant permissions. Account tool calls without valid credentials return an MCP authentication challenge; resources containing account data require OAuth. The exact agent resource has protected metadata at /.well-known/oauth-protected-resource/mcp/orgonaut-agent, using the existing shared issuer and S256 consent flow. Tokens remain bound to that exact resource.

Start with orgspec_guide when you are unsure of the OrgSpec format. Guest writes return the new revision, a summary, a scenario index and the IDs they changed; they never echo the whole model. Read the model with get_guest_organisation.

findings point out structural gaps the user can fill in: people not placed in any unit, people with more than one primary placement, empty teams, teams or departments without a lead, leads not placed in their own unit, several top-level units, people reporting to more than one manager, managers with more than eight direct reports, and fewer people represented than an estimated headcount. Each finding has a code, a severity (warning or info), up to 20 record ids and a suggested question to ask. Findings describe the records, not people's performance.

Guest tool failures are ordinary tool results with isError: true. The text names what to fix, and structuredContent.error carries a stable code (orgspec_invalid, invalid_arguments, not_found, conflict, invalid_request, rate_limited, draft_claimed), a retryable flag and, where useful, a hint. OrgSpec failures list up to 20 field paths, such as $.placements[0].actor, with allowed values for enum fields. After a draft is saved to an account, its guest_key stops working and the error says to connect that account instead.

To retry an edit safely after a timeout, send the same request_id again. If the first call already applied, the result comes back with replayed: true and applied_revision instead of a conflict. Use a new request_id for every new edit. create_guest_organisation is not replayed: a repeated create makes a second temporary draft, which simply expires.

Guest limits apply per assistant user when the host sends an anonymised user ID (ChatGPT's openai/subject), with per-IP and service-wide backstops. The defaults are 120 calls per minute and 10 new drafts per hour per user, and 10 claim links per hour per draft. Only successful drafts count toward the hourly limit, so correcting a rejected document does not use it up. Over a limit, tool calls return an in-band rate_limited error with retry_after seconds and a Retry-After header.

Guest updates can overwrite or remove existing temporary records, so update_guest_organisation declares readOnlyHint: false and destructiveHint: true. MCP clients can use these hints when requesting approval; the server still validates the private guest key, current revision and resulting model before applying an edit. These hints do not guarantee a client approval prompt.

Guest tools own only capability-protected temporary data and cannot read or edit an account tenant. They are unavailable on bearer-authenticated connections. Draft contents are encrypted at rest. The normal defaults are 7 days, 1,000 records per model, 512 KiB per model and 5 guest scenarios; deployments can adjust limits. Live discovery is authoritative for schemas and available tools.

Discovery flow

MCP-capable agents discover the live catalog from the server itself.

For the original authenticated endpoint, OAuth discovery and consent precede the first MCP session call. The mixed agent endpoint permits anonymous discovery and guest calls before account consent. After authentication, the normal sequence is:

1. Call initialize.
2. Call tools/list.
3. Call resources/list.
4. Call resources/templates/list.
5. Call prompts/list.

If you are evaluating a third-party agent builder, this is the key distinction: builders that support remote MCP should discover the catalog from the Orgonaut server directly, while builders that only ingest OpenAPI should use /docs/api instead.

Some MCP clients only surface tools in their UI even when they can authenticate successfully. For those clients, start with capability.list and capability.explain, then use org.review.guide or scenario.review.guide when the prompt catalog is not shown.

Tools

Tool discovery declares whether each operation reads or changes stored data, whether it can make destructive changes, and whether it can contact an external service. Read tools do not change organisation records. Action planning can contact an AI provider and save a proposal, while confirmation can update or archive scenario records. Required inputs are marked in each tool's schema; discover record IDs before calling tools that require them.

Discovery and tool-only compatibility

• capability.list lists the shared Orgonaut capability catalog and maps each capability to the MCP tools, resources, and prompts that implement it.
• capability.explain explains one capability key, tool name, prompt name, or resource URI and shows the mapped MCP surfaces for that capability.
• business.capability.list browses capability states and canonical IDs in Live or a scenario, with permission-filtered measures and costs.

Capability transformation review

• business.capability.detail reads one capability's state, source-to-target delta, measures, mapped Work, matched solution deployments, evidence, and completeness findings.
• ai.solution.list browses governed AI solutions, versions and contextual deployments.
• ai.solution.deployments reads one governed AI solution and its deployments in Live or a selected scenario. Pricing is returned only with the separate case-cost permission.
• transformation.case.list browses cases using each case's persisted source and target contexts.
• transformation.case.readiness reads deterministic readiness, scope, and permission-filtered client-safe economics for one case.

These catalog and detail tools are read-only. They cannot change capability assessments, deployments, assumptions, economics authorization, recommendations, approval, or publication state.

Studio lists support page and per_page (maximum 100, default 50). Follow the returned pagination before claiming completeness. Cost and workforce permissions still apply.

Review guidance

• org.review.guide returns the same review guidance as org-review, but as a read-only tool payload for tool-only clients.
• scenario.review.guide returns the same review guidance as scenario-review, but as a read-only tool payload for tool-only clients.

Org model and structure

• org.summary returns tenant-wide Live Baseline or scenario totals for headcount, FTE, monthly cost, and velocity.
• org.unit.tree returns an org-unit tree or subtree as a nested, machine-usable structure.
• org.unit.metrics returns roll-up headcount, FTE, cost, and velocity metrics for a specific org unit.
• org.team.roster returns a team's active roster, placement context, and positions when available.
• entity.resolve resolves teams, departments, actors, or scenarios by name in the current tenant scope.
• department.list lists departments in the current live, scenario, or snapshot scope.
• team.list searches teams in Live or one explicit scenario, returning canonical IDs and matching counts.
• team.summary reads one team summary, including staffing, org path, and metrics when permitted.
• department.profile reads one department summary and direct roster in the current scope.
• actor.list searches and paginates actors in Live or one explicit scenario; use actor.profile for permitted placement and pay details.
• actor.profile reads one actor profile, including placement and compensation context when permitted. primary_team is the team of the current primary placement (where the person works); seat is the position they hold and the team or department that owns it. seat_team_differs and seat_note flag someone working in one team while holding another team's seat, for example after a scenario move that keeps the original seat.
• position.list lists positions in the current live, scenario, or snapshot scope.
• initiative.list lists initiatives and shows their Live and target scenario relationships.
• team.velocity reads selected sprint velocity and recent sprint history for a team.
• transfer.impact estimates read-only headcount changes if a stated number of people moved between two teams or departments.

Scenario and history review

• scenario.list returns active scenarios with planning metadata and their latest aggregate summary when requested. Archived scenarios and baseline snapshots are omitted unless you pass status: "archived".
• scenario.delta explains how a scenario differs from its source state using Orgonaut's existing delta model.
• scenario.timeline shows a scenario's headcount, FTE, people cost and agent cost against its source, and the difference, on several dates. Without dates it returns the yearly path from today to the year after the last dated change (at most five years); pass up to 12 comma-separated YYYY-MM-DD dates to choose your own, and compare: "baseline" to compare against the Live baseline. Future dates are projected from dated placements, pay and approved deployments. Money is monthly, in minor currency units. Archived scenarios and snapshots return an error; use scenario.delta for them.
• scenario.history reads scenario lifecycle history, including tasks, lineage, snapshots, and recent activity.

Governed scenario actions

• scenario.create creates a planning scenario as a copy of Live, or of another planning scenario with source_scenario_id. Live never changes. The copy builds in the background, so check scenario.list until it is no longer initialising. An optional request_id makes retries return the same scenario. Needs scenarios.create.
• scenario.change.preview stages an exact change from IDs you already have, without an AI call: move_person (actor_id, to_org_unit_id, optional allocation_pct) or create_team (name, optional parent_org_unit_id and purpose). It returns the same proposal as scenario.action.plan and applies only through scenario.action.confirm.
• scenario.action.plan drafts a governed scenario action proposal from a natural-language request and returns the same proposal envelope Astro uses in-product.
• scenario.action.confirm confirms and executes one previously staged governed scenario action proposal by proposal_id.
• scenario.import.preview validates an OrgSpec document (orgspec object) for import into a mutable planning scenario, counts its records and lists structural findings. It returns a preview_id that expires after 30 minutes. Needs imports.manage.
• scenario.import.confirm starts the approved import through the normal import pipeline. Calling it again with the same preview_id reports progress and never imports twice. Records that match by OrgSpec source identity are updated, others are added, and nothing is deleted.

These tools preserve explicit confirmation. They can stage scenario-scoped actor, placement, compensation, cost-event, team, department, org-unit, position, initiative, and scenario lifecycle changes, and import into planning scenarios. Live Baseline writes, imports into Live, scenario promotion, snapshot restore, tenant taxonomy/settings changes (department types, team types, sprint periods, role types, currencies, AI pricing), tenant admin mutations, token management, and integration mutations remain unavailable. Read-only connections cannot use any of them. Tenant settings and operational mutations remain unavailable over MCP even when the same status can be read through tenant.settings or operations.status.

Settings and operations

• tenant.settings reads tenant member, invitation, token, and AI model cost settings state.
• reference.list browses tenant department, team and role types. Department/team reads require their domain read permissions; role types require settings.manage. Taxonomy writes remain unavailable.
• operations.status reads BambooHR integration health, recent import runs, and export availability.
• activity.recent returns recent activity statements with classifications, narratives, and referenced entities.

Resources

• orgonaut://baseline/summary returns the tenant-wide Live Baseline summary.
• orgonaut://tenant/settings returns a tenant settings snapshot for members, invitations, tokens, and AI costs.
• orgonaut://operations/status returns BambooHR, import, and export availability status.
• orgonaut://scenarios/{scenarioId}/summary returns a tenant-scoped scenario summary.
• orgonaut://scenarios/{scenarioId}/delta returns a tenant-scoped scenario delta payload.
• orgonaut://scenarios/{scenarioId}/history returns a tenant-scoped scenario history payload.

Cost, velocity, and pay redaction

Read tools return cost, velocity, and pay fields only when the caller holds the matching permission. Orgonaut checks both your member role and the scopes on the access token in use, so a token created without costs.read never receives cost data, even if your role would allow it.

• Without costs.read: monthly cost, people cost, and agent cost values and deltas are removed from team.summary, department.profile, actor.profile, position.list, scenario.list, scenario.delta, scenario.timeline, scenario.history, tenant.settings, and the matching resources. org.summary and org.unit.metrics require costs.read and refuse the call without it. activity.recent hides the change text for compensation and cost statements and strips salary, rate, cost, and budget fields from other changes.
• Without org-metrics.read: velocity values and deltas are removed from the same payloads.

Redacted responses include a limitations list that says what was left out. To give an agent headcount and structure only, create its token without costs.read.

Prompts

• org-review guides a client through reviewing the current live org or a scenario.
• scenario-review guides a client through analysing one scenario against its source state.

Response metadata

Tool and resource responses include structured metadata so agents can reason about freshness, provenance, and scope. Common fields include:

• request_id
• tool_version or resource_version
• capability_ids
• baseline or scenario_id
• as_of when applicable
• computed_at when applicable

Governed action tools also include:

• ai_run_id
• proposal_id
• proposal_status
• confirmation_required

Errors

Every tool reports a failure as a normal tool result with isError: true, so the agent can read the reason and correct its next call. The text says what went wrong and what to do next. structuredContent.error carries:

• code: a stable value such as invalid_arguments, not_found, forbidden, unsupported, conflict, orgspec_invalid, rate_limited or tool_error
• message and, where useful, hint
• retryable: true only when repeating the same call later can succeed
• request_id on account tools, for support

forbidden means the member's role or the token's scopes do not allow the call; retrying will not help. JSON-RPC protocol errors are reserved for malformed requests, unknown tools and failed resource reads, and always echo the request's id.

Typical first calls

For a Live Baseline organisational review:

1. Call capability.list if your client only shows tools or if you need the mapped capability catalog first.
2. Call org.review.guide when the prompt catalog is hidden and you want the review flow as a tool response.
3. Call org.summary.
4. Call entity.resolve if you need canonical ids first.
5. Call org.unit.tree.
6. Call org.unit.metrics for the nodes that matter most.
7. Call activity.recent.
8. Call tenant.settings or operations.status when you need tenant setup or operational context.

For a scenario review:

1. Call scenario.review.guide when the prompt catalog is hidden and you want the review flow as a tool response.
2. Call scenario.list.
3. Call scenario.history.
4. Call scenario.delta, then scenario.timeline to see how the difference develops over the coming years.
5. Call activity.recent with the same scenario_id.

For a governed scenario mutation flow:

1. If you need a new sandbox, call scenario.create with a name and a request_id, then call scenario.list until it is no longer initialising.
2. Call scenario.change.preview for an exact move or new team, or scenario.action.plan with scenario_id and a natural-language request.
3. Inspect action.proposal.id, proposal_status, and the returned preview.
4. Call scenario.action.confirm with the same scenario_id and proposal_id.
5. Review the returned action_result payload and cited follow-up links.

To import an OrgSpec document into a planning scenario:

1. Call scenario.import.preview with scenario_id and the document as orgspec. Fix any orgspec_invalid field errors and preview again.
2. Show the user the record counts and findings.
3. After they approve, call scenario.import.confirm with the preview_id. Call it again to check progress until the run is completed or failed.
4. Call scenario.delta to review what changed.

Imports into Live are not available over MCP; use the Imports page in Orgonaut.

Validation checklist

If you want to verify that an environment's MCP surface is working correctly:

1. Confirm the tenant-hosted OAuth metadata endpoints resolve successfully.
2. Connect a client and confirm initialize returns the Orgonaut server name and version.
3. Confirm tools/list, resources/list, resources/templates/list, and prompts/list all return populated results.
4. Call capability.list and confirm the compatibility note plus grouped capabilities are returned.
5. Call org.summary and scenario.list successfully.
6. Call scenario.action.plan and verify that scenario-scoped proposals return a proposal_id and explicit confirmation state.
7. Call tenant.settings or operations.status to confirm the broader admin and operational surfaces are reachable.

Related docs

• Connect MCP clients
• ChatGPT custom app setup
• API reference