> For the complete documentation index, see [llms.txt](https://docs.adaptria.locaria.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.adaptria.locaria.com/mcp-server/recipes.md).

# Recipes

These worked examples show how an internal AI agent can chain Adaptria tools to complete common operational tasks. Each step maps to a single tool call. The MCP server runs under your OAuth session, so an agent can only call tools your account is permitted to use.

> RFQ creation and quote accept/decline are **client actions** and are not covered here; they are performed via the Client API or the portal. The recipes below focus on internal operations.

***

## Recipe 1: Track a project through to delivery

Use this flow when an agent needs to check the status of a project and retrieve its deliverables.

1. **`list_projects`**: list accessible projects. Filter by `status` or `search` to narrow results. Capture the project `id`.
2. **`get_project`**: fetch full project details including current status, associated services and timeline.
3. **`list_jobs`** (with the project): see the individual jobs that make up the project.
4. **`get_project_deliverables`**: retrieve the final delivery files, links and metadata once the project reaches the delivery stage.

> To review or add feedback, use **`list_project_feedback`** and **`submit_project_feedback`** after step 2.

***

## Recipe 2: Create a project directly

Use this flow when an internal agent seeds work without going through the RFQ and quote cycle.

1. Gather the catalogue IDs the project references: **`list_companies`**, **`list_services`**, then **`list_languages`** or **`list_target_markets`**.
2. *(Optional)* **`upload_file`**: attach source assets and keep the returned file IDs.
3. **`create_project`**: submit a project that lands in **Draft** status for a project manager to enrich and action.

> `create_project` supports an idempotency key, so retries from an external system are safe.

***

## Recipe 3: Monitor jobs and update status

Use this flow when an internal agent needs to inspect the jobs inside a project and move them through their lifecycle.

1. **`list_jobs`** or **`list_job_management`**: find jobs by project or status.
2. **`get_job`** or **`get_job_management`**: inspect a single job, including its current status and delivery artefacts.
3. **`update_job_status`**: move a job to a target lifecycle status (e.g. `approved`, `rejected`, `cancelled`).

***

## Recipe 4: Get notified with webhooks

Use this flow to let an agent's backend react to events instead of polling.

1. **`register_webhook`**: subscribe a URL and company scope. Store the signing secret returned once at registration.
2. **`get_webhook`**: confirm the registration.
3. **`delete_webhook`**: remove a subscription when it is no longer needed.

> The agent reacts to delivered events (RFQ, quote, job and project updates) rather than re-listing resources on a timer.

***

## Recipe 5: Reconcile finance

Use this flow when an internal agent needs to review outstanding finance positions.

1. **`list_receivables`** or **`list_payables`**: pull the outstanding finance positions.
2. **`list_invoices`** (filter via **`get_invoice_filters`**): find the invoices of interest.
3. **`get_invoice`** then **`download_invoice_pdf`**: inspect and export a single invoice.

***

## Recipe 6: Answer "what is the status of X?"

Use this flow for open-ended questions where the agent needs to find an entity first, then drill in.

1. **`global_search`**: resolve a name or reference to concrete entities (RFQs, quotes, projects, clients).
2. Route to the matching getter: **`get_rfq`**, **`get_quote`**, **`get_project`** or **`get_client`**.
3. Summarise the current status back to the user.