ORGONAUT
Login Signup
Docs
Agents and API
MCP reference

MCP reference

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

Plan availability: remote MCP access is available on the business, enterprise, and agency plans. free and team tenants do not expose the MCP transport or OAuth metadata routes.

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

Orgonaut exposes one canonical remote MCP server:

  • /mcp/orgonaut

Example tenant-hosted URL:

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

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

Discovery flow

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

For OAuth-capable clients, the OAuth discovery and consent flow happens before the first MCP session call. 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

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.
  • 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 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.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.profile reads one actor profile, including placement and compensation context when permitted.
  • position.list lists positions in the current live, scenario, or snapshot scope.
  • initiative.list lists initiatives and shows their baseline 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 scenarios with planning metadata and their latest aggregate summary when requested.
  • scenario.delta explains how a scenario differs from its source state using Orgonaut's existing delta model.
  • scenario.history reads scenario lifecycle history, including tasks, lineage, snapshots, and recent activity.

Governed scenario actions

  • 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.

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, but baseline writes, 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 import/integration mutations remain unavailable. 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.
  • 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.

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

Typical first calls

For a live 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.
  5. Call activity.recent with the same scenario_id.

For a governed scenario mutation flow:

  1. Call scenario.action.plan with scenario_id and a natural-language request.
  2. Inspect action.proposal.id, proposal_status, and the returned preview.
  3. Call scenario.action.confirm with the same scenario_id and proposal_id.
  4. Review the returned action_result payload and cited follow-up links.

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.