> ## Documentation Index
> Fetch the complete documentation index at: https://docs.amps.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Examples
> Agent workflows over the Amps MCP servers. Documentation MCP: write curl from a prompt, validate config, build a webhook handler. Execution MCP coming soon.
Each example below is a workflow you can run in any MCP-aware AI tool with the relevant Amps MCP server installed. Each names the prompt, the calls the agent should make, and the grounded answer to expect.
If your client is not yet wired up, follow the [install guide](/ai-tools/mcp/install).
## Documentation MCP examples
Workflows that exercise the [Documentation MCP](/ai-tools/mcp/documentation): search the docs corpus, query the OpenAPI spec, build something from grounded vocabulary.
### 1. Write the curl for charging a battery overnight
**Prompt:**
> Write the exact curl request to schedule a battery to charge overnight from 22:00 to 05:00 UTC, ramping to 90% on device `device_abc123`. My API key is in `$AMPS_API_KEY`.
**What the agent does:**
1. Calls `search_amps_ai_documentation` with `"charge battery overnight"`. The top result is the cookbook recipe at `guides/cookbook/schedule-charge-later`.
2. Calls `query_docs_filesystem_amps_ai_documentation` with `cat /guides/cookbook/schedule-charge-later.mdx` to read the worked walkthrough.
3. Calls `query_docs_filesystem_amps_ai_documentation` with `rg -C 5 "windowed" /concepts/canonical-actions.mdx` to confirm the `windowed` shape.
**Expected output:**
A complete curl invocation against `POST /battery/device_abc123` with the `windowed` shape: `command: "charge"`, `parameters.target: { value: 90, unit: "percent" }`, `start` and `end` as ISO 8601 timestamps. The response cites the canonical actions page and the cookbook recipe.
### 2. Validate a config against the canonical battery modes
**Prompt:**
> Here is our internal battery profile. Check whether every mode it references is a canonical Amps mode, and flag any that are not:
>
> ```yaml theme={null}
> profiles:
> - name: "winter"
> modes: ["charge", "selfconsumption", "auto.export", "gridcharge"]
> - name: "summer"
> modes: ["auto.balance", "auto.reserve", "discharge"]
> ```
**What the agent does:**
1. Calls `query_docs_filesystem_amps_ai_documentation` with `cat /openapi/openapi.json | jq '.components.schemas.BatteryAction'` to read the canonical action discriminator straight from the spec.
2. Cross-references the modes in the YAML against the `command` enum: `charge`, `discharge`, `idle`, `auto.balance`, `auto.reserve`, `auto.export`.
3. Calls `query_docs_filesystem_amps_ai_documentation` with `rg -C 2 "auto.balance" /concepts/canonical-actions.mdx` to ground the explanation of the closest matches.
**Expected output:**
A table flagging `selfconsumption` (not canonical, suggest `auto.balance`) and `gridcharge` (not canonical, suggest `charge`), and confirming the rest. The response links to the [canonical actions](/concepts/canonical-actions) page so a reviewer can verify.
### 3. Build a webhook receiver
**Prompt:**
> Build a minimal Flask endpoint that receives Amps webhooks, verifies the signature, dedupes on event id, and prints the action ID. Use my `WEBHOOK_SECRET` env var.
**What the agent does:**
1. Calls `search_amps_ai_documentation` with `"webhook signature verification"`. Top results include the webhook security guide and the webhook types reference.
2. Calls `query_docs_filesystem_amps_ai_documentation` with `cat /guides/webhooks/verify-signatures.mdx` to read the verification pattern and the existing Python example.
3. Calls `query_docs_filesystem_amps_ai_documentation` with `cat /reference/webhook-types.mdx` to confirm the `push.completed` payload shape.
**Expected output:**
A Flask app that verifies the HMAC signature, a `processed_events` set guarding idempotency, and a handler that pulls `actionId` and `deviceId` out of the payload. The canonical webhook payload structure is quoted verbatim.
### 4. Find every cookbook recipe that schedules an action ahead of time
**Prompt:**
> Show me every Amps cookbook recipe that schedules an action ahead of time. For each, summarise the request body shape.
**What the agent does:**
1. Calls `query_docs_filesystem_amps_ai_documentation` with `rg -l "\"start\"" /guides/cookbook/` to find recipes carrying a `start` field in their request bodies.
2. Calls `query_docs_filesystem_amps_ai_documentation` with `head -120 /guides/cookbook/schedule-charge-later.mdx /guides/cookbook/discharge-windowed.mdx` to read the matches in one call.
3. Calls `search_amps_ai_documentation` with `"scheduled execution"` to ground the canonical shape distinction.
**Expected output:**
A structured comparison: both schedule-charge-later and discharge-windowed pair `start` with `end` to run inside a window (a cheap-rate charge window and a peak-pricing discharge window respectively). The canonical action body is quoted for each recipe with a link back to the concept page on per-mode execution.
### 5. Add the Documentation MCP to a CI pipeline
For automated checks that do not run inside an interactive AI tool, the MCP endpoint is a JSON-RPC HTTP service. A CI step can call it directly with `curl` and parse responses with `jq`.
**Use case:** fail CI when an internal config file references a mode that is not in the canonical battery action enum.
```bash theme={null}
#!/usr/bin/env bash
set -euo pipefail
# Get the canonical battery commands directly from the Amps OpenAPI spec
# via the MCP query_docs_filesystem tool.
CANONICAL=$(curl -sL -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "query_docs_filesystem_amps_ai_documentation",
"arguments": {
"command": "cat /openapi/openapi.json | jq -r \".components.schemas.BatteryAction.discriminator.mapping | keys[]\""
}
}
}' \
https://docs.amps.ai/mcp \
| sed -n 's/^data: //p' \
| jq -r '.result.content[0].text' \
| awk '/--- stdout ---/{flag=1; next} flag')
# Compare against modes used in our internal config.
USED=$(yq -r '.profiles[].modes[]' config/battery-profiles.yaml | sort -u)
EXTRA=$(comm -23 <(echo "$USED") <(echo "$CANONICAL" | sort -u))
if [[ -n "$EXTRA" ]]; then
echo "Non-canonical battery modes referenced in config:"
echo "$EXTRA"
exit 1
fi
```
The step pulls the canonical battery commands directly from the live OpenAPI spec via the MCP server, diffs them against the modes in your internal config, and fails the build on drift. No SDK install, no static snapshot to keep in sync.
## Execution MCP examples
**Coming soon.** The Execution MCP is in development. Worked examples will land alongside the [`@amps-ai/mcp`](https://www.npmjs.com/package/@amps-ai/mcp) package release.
The pattern, in advance: the agent reads a device with `get_battery`, surfaces a confirmation primitive built from the device's capability declaration, fires `push_battery` on confirm, then `wait_for_action` to surface the lifecycle. See [Self-describing responses](/ai-tools/building-agent-uis/self-describing-responses), [Dynamic UI rendering](/ai-tools/building-agent-uis/dynamic-ui-rendering), and [Confirmation gates](/ai-tools/building-agent-uis/confirmation-gates) for the patterns the worked examples will demonstrate.
## What next
Real, end-to-end recipes the agent can read with a single `cat`.
The vocabulary the MCP servers keep your agent grounded in.
Exact endpoint shapes, the same contract the MCP serves.
Inputs and outputs for every MCP tool, with more call patterns.