Skip to main content

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.

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.

​
Documentation MCP examples

Workflows that exercise the Documentation MCP: 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 dev_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/charge-overnight.
  2. Calls query_docs_filesystem_amps_ai_documentation with cat /guides/cookbook/charge-overnight.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/dev_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: 
profiles:
  - name: "winter"
    modes: ["charge", "selfconsumption", "auto.export", "gridcharge"]
  - name: "summer"
    modes: ["auto.balanced", "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.balanced, auto.reserve, auto.export.
  3. Calls query_docs_filesystem_amps_ai_documentation with rg -C 2 "auto.balanced" /concepts/canonical-actions.mdx to ground the explanation of the closest matches.
Expected output: A table flagging selfconsumption (not canonical, suggest auto.balanced) and gridcharge (not canonical, suggest charge), and confirming the rest. The response links to the 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/charge-overnight.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: charge-overnight uses start only (scheduled), discharge-windowed uses start and end (windowed). 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. 
#!/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 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, Dynamic UI rendering, and Confirmation gates for the patterns the worked examples will demonstrate.

​
What next

Cookbook

Real, end-to-end recipes the agent can read with a single cat.

Canonical actions

The vocabulary the MCP servers keep your agent grounded in.

API reference

Exact endpoint shapes, generated from the same OpenAPI the MCP serves.

Tool reference

Inputs and outputs for every MCP tool, with more call patterns.