Tool reference

Two MCP servers, two tool surfaces. The Documentation MCP exposes two read-only tools that ground the agent in the docs corpus. The Execution MCP exposes a per-operation tool surface that mirrors the Amps API.

Documentation MCP tools

Both Documentation MCP tools are read-only. Both are stateless: each call resets the working directory to / and discards shell variables or aliases.

`search_amps_ai_documentation`

Semantic search across every Amps docs page. Returns ranked snippets with titles, page paths, and direct links. Reach for it on conceptual queries where the right page is uncertain.

Input

{
  "query": "string"
}

query is a natural-language question or keyword phrase. Required.

Output

A list of result entries. Each carries a title, a link to the public page, a page path, and a snippet of the matching content with the keyword highlighted.

[
  {
    "title": "Canonical Actions",
    "link": "https://docs.amps.ai/concepts/canonical-actions",
    "page": "concepts/canonical-actions",
    "content": "Direct commands (charge, discharge, idle) are explicit instructions. Auto commands declare intent..."
  },
  {
    "title": "Push battery action",
    "link": "https://docs.amps.ai/api-reference/battery/push-battery-action",
    "page": "api-reference/battery/push-battery-action",
    "content": "Send a command to a battery device..."
  }
]

For full content, follow up with query_docs_filesystem_amps_ai_documentation and cat or head the page path. Append .mdx when reading from the filesystem.

Example calls

Query	Why
`"how does scheduling work"`	Returns the scheduling concept page plus the cookbook overnight-charge recipe.
`"auto.balance behaviour"`	Returns the canonical-actions page and per-mode notes.
`"webhook signature verification"`	Returns the webhooks security page plus Node.js and Python verification snippets.
`"environments sandbox vs live"`	Returns the environments guide and the sandbox testing notes.

`query_docs_filesystem_amps_ai_documentation`

Read-only shell-style access to a virtual filesystem rooted at /. The filesystem holds every published documentation page as .mdx and the OpenAPI spec at /openapi/openapi.json. Reach for it on exact lookups: read a specific page, grep a canonical name, list endpoint paths.

Input

{
  "command": "string"
}

command is a shell-flavoured command string. Required. Supported commands: rg (ripgrep), grep, find, tree, ls, cat, head, tail, stat, wc, sort, uniq, cut, sed, awk, jq. No writes, no network, no process control. --help on any command for usage. Each call is stateless. To run a sequence in one call, chain with &&:

ls /concepts && head -30 /concepts/canonical-actions.mdx

cd does not persist between calls. Use absolute paths.

Output

Plain text. Stdout, stderr, and the exit code, capped at 30KB per call. Beyond the cap, output truncates with a notice. Use targeted commands (rg -C 3 'pattern' /path/file.mdx, head -200) to stay under the limit.

Path-to-URL conversion

Filesystem paths end in .mdx. Public URLs do not. To cite a page in a response, strip the .mdx:

Filesystem path	Public URL
`/quickstart.mdx`	`https://docs.amps.ai/quickstart`
`/concepts/canonical-actions.mdx`	`https://docs.amps.ai/concepts/canonical-actions`
`/api-reference/battery/push-battery-action.mdx`	`https://docs.amps.ai/api-reference/battery/push-battery-action`

Example calls

Command	What it does
`tree / -L 2`	Show the top-level directory layout.
`ls /concepts`	List concept pages.
`cat /concepts/canonical-actions.mdx`	Read the full canonical-actions page.
`head -80 /get-started/quickstart.mdx`	Read the first 80 lines of the quickstart.
`rg -l "auto.balance" /`	List every page mentioning `auto.balance`.
`rg -C 3 "EXECUTION_NOT_SUPPORTED" /`	Show every match with three lines of context.
`cat /openapi/openapi.json \| jq '.paths \| keys'`	List every OpenAPI endpoint path.
`cat /openapi/openapi.json \| jq '.paths."/battery/{deviceId}".post.summary'`	Read a specific endpoint’s summary.
`find /api-reference -name "*.mdx"`	Enumerate API reference pages.
`head -40 /guides/webhooks/verify-signatures.mdx /reference/webhook-types.mdx`	Read multiple pages in one call.

Output cap and how to stay under it

The 30KB cap applies per call. A cat on the OpenAPI spec or a long concept page will truncate. Three patterns that stay safe:

head -N path when you only need the top of a file.
rg -C N "pattern" path when you need only the relevant slice.
jq '.paths | keys' and similar projections when the file is structured.

Combine with && to keep round-trips down. Each call pays the connection cost on its own, so bundling pays off fast.

Execution MCP tools

Coming soon. The Execution MCP is in development and will publish to @amps-ai/mcp on npm. Tool names and shapes below describe the planned surface; treat them as design intent until the package ships.

There is one tool per canonical API operation. The tool name follows the operation’s verb-noun pattern, lowercased and snake-cased.

Per-resource tools

Tool	What it does
`list_battery`	List batteries the authenticated user has registered.
`get_battery`	Fetch one battery’s state and capability declaration.
`push_battery`	Push a canonical action to a battery. Destructive.
`list_ev_charger`, `get_ev_charger`, `push_ev_charger`	Same trio for EV chargers.
`list_hvac`, `get_hvac`, `push_hvac`	Same trio for HVAC.
`list_solar_inverter`, `get_solar_inverter`	Read-only inverter access.
`list_vehicle`, `get_vehicle`	Read-only vehicle access.
`get_action`	Fetch one action’s lifecycle state.
`cancel_action`	Cancel a scheduled or in-flight action. Destructive.

Helper tools

Helpers wrap canonical primitives in shapes the model finds easier to reason about.

Tool	What it does
`wait_for_action`	Polls `get_action` until the action reaches a terminal state (`completed`, `failed`, or `cancelled`). The agent does not have to manage its own loop.
`find_device`	Lookup-by-alias. Saves a `list_*` then filter pass when the user names a device by its label rather than ID.

Filtered out

The 501 /schedules surface is filtered until it ships, so the agent never gets a tool that always fails.

What next

Examples

Concrete workflows that combine the tools above.

Install

Wire either MCP server into your AI tool.

Canonical actions

The vocabulary the tools surface to the model.

Confirmation gates

Why push_* and cancel_action should not free-fire from the model.

Get Started

Concepts

API Reference

Guides

Quick reference

More

Documentation MCP tools

`search_amps_ai_documentation`

Input

Output

Example calls

`query_docs_filesystem_amps_ai_documentation`

Input

Output

Path-to-URL conversion

Example calls

Output cap and how to stay under it

Execution MCP tools

Per-resource tools

Helper tools

Filtered out

What next

Examples

Install

Canonical actions

Confirmation gates

​Documentation MCP tools

​search_amps_ai_documentation

​Input

​Output

​Example calls

​query_docs_filesystem_amps_ai_documentation

​Input

​Output

​Path-to-URL conversion

​Example calls

​Output cap and how to stay under it

​Execution MCP tools

​Per-resource tools

​Helper tools

​Filtered out

​What next

Examples

Install

Canonical actions

Confirmation gates

Documentation MCP tools

`search_amps_ai_documentation`

Input

Output

Example calls

`query_docs_filesystem_amps_ai_documentation`

Input

Output

Path-to-URL conversion

Example calls

Output cap and how to stay under it

Execution MCP tools

Per-resource tools

Helper tools

Filtered out

What next