> ## 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.

# Execution MCP

> Call the Amps API from any LLM agent. Distributed as @amps-ai/mcp on npm. Per-operation tools, helper tools, integrator-key auth with per-user identity. Coming soon.

<Callout icon="clock" color="#ED6D2C">
  **Coming soon.** The Execution MCP is in development and will publish to [`@amps-ai/mcp`](https://www.npmjs.com/package/@amps-ai/mcp) on npm. The package is not yet listed. The patterns in [Building agent UIs](/ai-tools/building-agent-uis/self-describing-responses) work against the [Documentation MCP](/ai-tools/mcp/documentation) and the REST API directly.
</Callout>

The Execution MCP will let an agent call the Amps API on behalf of an authenticated user. Where the [Documentation MCP](/ai-tools/mcp/documentation) grounds the agent in *how* the API works, the Execution MCP grounds the agent in *acting* on the API.

## Distribution

The server will publish as the [`@amps-ai/mcp`](https://www.npmjs.com/package/@amps-ai/mcp) npm package. Install with `npx`, run as a stdio process for local agents (Claude Desktop, Cursor, Windsurf, Continue), or run as a hosted HTTP service for multi-tenant integrations (Vercel AI SDK, custom backends).

```jsonc theme={null}
// Coming soon: stdio installation in any MCP-aware client
{
  "mcpServers": {
    "amps": {
      "command": "npx",
      "args": ["-y", "@amps-ai/mcp"],
      "env": {
        "AMPS_API_KEY": "sk_live_..."
      }
    }
  }
}
```

## Tool surface

One tool per API operation. Per resource:

* `list_battery`, `get_battery`, `push_battery`
* `list_ev_charger`, `get_ev_charger`, `push_ev_charger`
* `list_hvac`, `get_hvac`, `push_hvac`
* `list_solar_inverter`, `get_solar_inverter`
* `list_vehicle`, `get_vehicle`
* `get_action`, `cancel_action`

Plus helper tools that compose canonical primitives:

* `wait_for_action(actionId)` polls `get_action` until terminal state, so the agent does not have to manage its own loop.
* `find_device(query)` saves the agent a list-then-filter dance when the user names a device by alias rather than ID.

The 501 schedules surface is filtered out until [`/schedules`](/concepts/scheduling) ships, so the agent never gets a tool that always fails.

## Auth model

Two layers of identity, one outbound API call.

The integrator (you, the developer wiring the agent) holds the Amps API key. That key sits in the MCP server's environment, never in the model's context. Per-request, your application forwards the end-user's identifier to the MCP server in a header. The MCP server proxies both to the Amps API: the API key as `x-api-key`, the user identity as `x-user-id`. Amps resolves the user against the integrator's account and scopes the call accordingly.

This means the model never sees a credential. The integrator's API key stays server-side. End-users authenticate to your application; your application authenticates to Amps.

For a hosted multi-tenant deployment, run the MCP server over streamable HTTP. One process serves every user. Per-request headers carry per-user identity. For a single-user local agent, run over stdio with a single user identifier baked into env.

## Tool naming hygiene

Operation IDs on the Amps API are designed to read cleanly as MCP tools. `pushBattery` becomes the `push_battery` tool. `cancelAction` becomes `cancel_action`. The agent thinks in canonical verbs that match the docs.

## Cross-link to the patterns

The Execution MCP makes the patterns concrete. Each tool result is a canonical envelope, so:

* A `get_battery` result feeds straight into a `<DeviceStateCard>` component (see [Dynamic UI rendering](/ai-tools/building-agent-uis/dynamic-ui-rendering))
* A `push_battery` 422 returns a capability snapshot the agent can re-derive from (see [Self-describing responses](/ai-tools/building-agent-uis/self-describing-responses))
* A `push_battery` or `cancel_action` call gates behind a confirmation primitive (see [Confirmation gates](/ai-tools/building-agent-uis/confirmation-gates))

## What next

<CardGroup cols={2}>
  <Card title="Documentation MCP" icon="book-open" href="/ai-tools/mcp/documentation">
    The companion surface for grounding an agent in the docs corpus. Live.
  </Card>

  <Card title="Self-describing responses" icon="file-search" href="/ai-tools/building-agent-uis/self-describing-responses">
    The contract the Execution MCP exposes to the model.
  </Card>

  <Card title="Confirmation gates" icon="shield-check" href="/ai-tools/building-agent-uis/confirmation-gates">
    Why destructive tool calls do not free-fire from the model.
  </Card>

  <Card title="Canonical actions" icon="circle-check" href="/concepts/canonical-actions">
    The action shape every push tool will accept.
  </Card>
</CardGroup>

<script
  type="application/ld+json"
  dangerouslySetInnerHTML={{__html: JSON.stringify({
"@context": "https://schema.org",
"@type": "TechArticle",
"headline": "Execution MCP",
"description": "Call the Amps API from any LLM agent. Distributed as @amps-ai/mcp on npm. Coming soon.",
"datePublished": "2026-05-08",
"dateModified": "2026-05-08",
"about": {
"@type": "SoftwareApplication",
"name": "Amps Execution MCP",
"applicationCategory": "DeveloperApplication",
"operatingSystem": "Cross-platform"
}
})}}
/>