> ## Documentation Index
> Fetch the complete documentation index at: https://www.composer.id/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP tools

> The composerID MCP tool family for agents: five tools that mirror the Intent API one for one, the front-door rule and the guardrails around them.

This page documents the tool family an agent uses to call composerID over the Model Context Protocol (MCP). It is for teams wiring a chatbot or an autonomous agent into a workforce decision flow. Each tool restates one Intent API operation as a tool call, so the schemas, scopes and guarantees are the ones the [API reference](/api-reference/overview) documents.

<Info>
  The tool family below is a documented contract: each tool mirrors one Intent API operation and is held to that operation's request and response schemas. composerID does not yet run a hosted MCP server. An agent reaches these tools through the REST operation each one names, served today by the reference sandbox. Separately, the "Connect to MCP" option in the menu on every page of these docs connects an assistant to the Mintlify-hosted documentation server, which searches and reads this documentation. It does not call the Intent API.
</Info>

## The front-door rule

An agent may browse and read the destination system freely. When a decision is required it calls `intent_create`; it never creates records in the destination directly. composerID then mints the Intent ID, plans, preflights and publishes, and the destination system keeps its role as the system of record.

```mermaid theme={"system"}
sequenceDiagram
  participant A as Agent
  participant C as composerID
  participant D as Destination system
  A->>D: Browse and read
  A->>C: intent_create
  C-->>A: intent_id
  A->>C: plan_generate
  A->>C: mapping_preflight
  C-->>A: enrichment gaps, if any
  A->>C: adapter_publish
  C->>D: Idempotent write carrying the Intent ID
  C-->>A: Receipt with external IDs
```

## Tools

<AccordionGroup>
  <Accordion title="intent_create" description="Intent: initialises a record and returns a stable intent_id" icon="fingerprint">
    Mirrors `POST /v1/intent` (scope `intents:write`). Input schema `IntentCreateRequest`: a `payload` object of canonical intent fields such as `channel`, `role_title`, `start_date`, `location` and `quantity`. Output schema `IntentRecord`. The `intent_id` it returns never changes; later amendments bump `intent_version`.
  </Accordion>

  <Accordion title="intent_patch" description="Intent: updates the diagnostics, routing and admin payloads" icon="wrench">
    Mirrors `PATCH /v1/intent/{intent_id}` (scope `intents:write`). Input schema `IntentPatchRequest`; output schema `IntentRecord`. A patch bumps the intent's version.
  </Accordion>

  <Accordion title="plan_generate" description="Routing: applies the Channel Map to identify the target destinations" icon="route">
    Mirrors `POST /v1/plan` (scope `intents:write`). Input schema `PlanGenerateRequest`; output schema `PlanGenerateResponse`.
  </Accordion>

  <Accordion title="mapping_preflight" description="Routing: validates the intent against the destination's requirements and returns enrichment gaps" icon="shield-check">
    Mirrors `POST /v1/preflight` (scope `intents:write`). Input schema `PreflightRequest`; output schema `PreflightResponse`. When the tenant's mandatory fields are not satisfied the REST operation answers `422` with an `enrichment_request`, surfaced before anything is published.
  </Accordion>

  <Accordion title="adapter_publish" description="Execution: idempotent publish that records external IDs and a receipt" icon="send">
    Mirrors `POST /v1/publish` (scope `publish`). Input schema `PublishRequest`; output schema `PublishReceipt`. Publishing is idempotent on `{intent_id}-{intent_version}-{target_system}`: a replayed publish returns the stored receipt with `replayed: true` and never creates a second record in the destination.
  </Accordion>
</AccordionGroup>

## Guardrails

<AccordionGroup>
  <Accordion title="State guardrails" icon="lock">
    Each transition requires a minimum viable intent. Overrides are never silent: they are recorded as explicit events in the intent's timeline.
  </Accordion>

  <Accordion title="Enrichment loop" icon="arrow-right-left">
    If the target system needs fields the intent lacks, emit an `enrichment_request` rather than failing the publish. The gap goes back to the requester through `POST /v1/enrichment-request`, and the answers fill it without a version bump.
  </Accordion>

  <Accordion title="Passthrough with anchors" icon="hash">
    Raw platform calls are allowed through `POST /v1/passthrough` (scope `passthrough`), but every one carries the `intent_id`, the version and a rationale, recorded in the timeline.
  </Accordion>
</AccordionGroup>

## Next steps

<Columns cols={3}>
  <Card title="Authentication" icon="key-round" href="/authentication">
    The scope each tool's REST operation requires.
  </Card>

  <Card title="API reference" icon="code" href="/api-reference/overview">
    The Intent API the tools mirror, generated from its OpenAPI document.
  </Card>

  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Run the sandbox the tools call today.
  </Card>
</Columns>