> ## Documentation Index
> Fetch the complete documentation index at: https://agentheya.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Management MCP

> Programmatically create, configure, and manage Agentheya agents using the Management MCP server.

The Management MCP server lets AI agents and automated systems create and manage Agentheya accounts and agents without using the web dashboard.

**Endpoints — three surfaces, one backend:**

| Use case                                                 | Endpoint                                          |
| -------------------------------------------------------- | ------------------------------------------------- |
| MCP-compatible AI agents (Claude, Cursor, custom)        | `manage.agentheya.com/mcp`                        |
| Plain HTTP / curl / SDK codegen / webhooks / dashboards  | `POST manage.agentheya.com/v1/manage/{tool_name}` |
| OpenAPI 3.1 spec for SDK generators, Swagger UI, Postman | `GET manage.agentheya.com/openapi.json`           |

All three reuse the same auth, the same rate limits, the same input validation, and the same handlers. Pick whichever fits your client. AI agents typically use MCP (tool discovery is built in via `tools/list`); humans and scripts typically use the REST endpoint or generate a typed SDK from the OpenAPI spec.

> **Tool namespacing (breaking change, May 2026).** Every tool name is now `namespace.verb`. Old → new examples: `create_schedule` → `schedule.create`, `list_invocation_keys` → `key.list`, `set_section_fields` → `patch.set_fields`, `list_a2a_tasks` → `a2a.list_tasks`. Update any scripts that hardcoded the old names. The full list grouped by namespace is below; the live source of truth is `manage.agentheya.com/openapi.json`.

> **Don't know which tool to call?** Use `meta.find_tool` first. It scores your natural-language task against every tool's tags + summary and returns the top 5 matches with their schemas. Saves shoving all 50 tool defs into context.

***

## Getting started

1. **Call `account.create`** — no authentication required. You receive an `owner_id`, a `management_key`, and a `payment_link`.
2. **Open the `payment_link` in a browser** to complete the initial Pro subscription. Agent creation is blocked until payment is confirmed.
3. **Authenticate subsequent calls** by sending the management key as a Bearer token and passing `owner_id` as a tool argument:
   ```http theme={null}
   Authorization: Bearer sk_mgmt_...
   ```
4. **Call `agent.create`** to create an agent. Configure it with `config.set` and `file.upload`.
5. **Create invocation API keys** with `key.create` so subscribers or systems can call the agent.

***

## Authentication

| Tool                 | Auth required                                          |
| -------------------- | ------------------------------------------------------ |
| `account.create`     | None                                                   |
| `schema.get`         | None                                                   |
| `billing.list_plans` | None                                                   |
| All others           | Management key (Bearer) + matching `owner_id` argument |

Management keys start with `sk_mgmt_`. Per-agent owner keys (`sk_ah_`) generated from the dashboard also work for tools that target the specific agent they were issued for.

***

## Tools

### `account.create`

Creates a new Agentheya account. Returns credentials and an initial payment link.

**Arguments:** none

**Returns:**

| Field                 | Description                                                                                             |
| --------------------- | ------------------------------------------------------------------------------------------------------- |
| `owner_id`            | Your account identifier — pass this on every subsequent call                                            |
| `management_key`      | Bearer token for authentication — shown only once, store securely                                       |
| `payment_link`        | Stripe checkout URL for the Pro plan (lowest credits option). Open in a browser to activate the account |
| `payment_description` | Human-readable description of the plan and price                                                        |
| `message`             | Next-step instructions                                                                                  |

Agent creation is blocked until payment through `payment_link` (or `account.create_checkout`) is completed.

***

### `agent.create`

Creates a new agent under the authenticated account.

**Arguments:**

| Field            | Type              | Description                                                                                                                                                                                                                |
| ---------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `owner_id`       | string            | Your account owner ID                                                                                                                                                                                                      |
| `contact_email`  | string            | **Required.** Email address of the account owner. The Stripe payment link is sent here if the account is not yet subscribed. Also stored as the account contact address (replaces the placeholder set by `account.create`) |
| `preferred_name` | string (optional) | Desired agent name (letters, numbers, hyphens, underscores; 4–64 chars). Generated if omitted                                                                                                                              |

**Returns:** `agent_id`, `agent_name`, `status: "design"`, and a setup message.

The agent starts in `"design"` state and cannot receive queries until configured and subscribed. If `preferred_name` is taken, the response returns `error: "name_taken"` — try a variation.

**If the account has no active subscription**, the call returns `error: "payment_required"` along with a `payment_link` and `payment_description`. The payment link is also emailed to `contact_email` so the account owner can complete payment without the AI agent having to relay the URL.

**Requires:** an active subscription (payment must have been completed).

***

### `agent.list`

Lists all agents on this account.

**Arguments:** `owner_id`

**Returns:** array of agents, each with `agent_id`, `agent_name`, `account_status`, `visibility`, and `created_at`.

***

### `agent.delete`

Deletes an agent. The agent stops responding immediately; its data is retained (recoverable) for a retention window.

**Arguments:** `owner_id`, `agent_id`

***

### `schema.get`

Returns the JSON Schema for one or all configuration sections. Call this before `config.set` to verify field names and types.

**Arguments:**

| Field     | Type              | Description                                                |
| --------- | ----------------- | ---------------------------------------------------------- |
| `section` | string (optional) | Section name. If omitted, returns schemas for all sections |

**No authentication required.**

Available sections: `purpose`, `rules`, `examples`, `details`, `public_details`, `policy_tos`, `policy_privacy`, `policy_refund`, `data_internal`, `data_public`, `pricing`, `connectors`, `skills`, `tools`, `plugins`, `hooks`, `widgets`, `langfuse`, `memory_schema`, `weaviate`, `builtin_tools`, `monitoring`

You can also fetch any schema over plain HTTP without an MCP transport:

```
GET https://agentheya.com/api/manage-mcp/schema           # lists every section
GET https://agentheya.com/api/manage-mcp/schema/{section} # returns one section's JSON Schema
```

The HTTP endpoint is unauthenticated and CDN-cached for 60 s.

***

### `config.get`

Reads the current configuration for a section.

**Arguments:** `owner_id`, `agent_id`, `section`

***

### `config.set`

Writes a complete section payload. **First-write-only**: once a section already has content, this returns `error: "overwrite_refused"` and you must switch to a patch tool (see below). The exception is `section: "details"`, which still merges so partial `agent_name` renames work.

The payload is validated against the section's JSON Schema (see `schema.get`) before writing — invalid payloads leave the existing config unchanged.

**Arguments:**

| Field      | Type   | Description                   |
| ---------- | ------ | ----------------------------- |
| `owner_id` | string |                               |
| `agent_id` | string |                               |
| `section`  | string | Section to write              |
| `data`     | object | Configuration for the section |

To rename the agent, include `agent_name` in `data` when `section = "details"`.

***

### Patch tools (surgical edits to non-empty sections)

Use these instead of `config.set` once a section has content. Each op validates the resulting payload against the section's JSON Schema before persisting; invalid patches are refused and leave the existing config unchanged.

#### `patch.set_fields`

Merge a partial object into an OBJECT section. Only the fields you supply are changed; every other field is preserved.

**Arguments:** `owner_id`, `agent_id`, `section`, `fields` (partial map)

#### `patch.add_item`

Append (or prepend) one item to an array. For top-level array sections (rules, examples, skills, tools, hooks, plugins) leave `array_field` blank. For nested arrays (e.g. `connectors.connectors`, `pricing.tiers`) set `array_field`.

**Arguments:** `owner_id`, `agent_id`, `section`, `array_field?`, `item`, `position?` (`"start"` | `"end"`)

#### `patch.update_item`

Find an array item where `match_key === match_value` and merge `fields` into it.

**Arguments:** `owner_id`, `agent_id`, `section`, `array_field?`, `match_key`, `match_value`, `fields`

#### `patch.remove_item`

Delete an array item by key=value. Returns error if no match.

**Arguments:** `owner_id`, `agent_id`, `section`, `array_field?`, `match_key`, `match_value`

#### `patch.reorder_items`

Reorder an array by a list of key values. Items whose key value is missing from the list are appended at the end unchanged (so you can't accidentally drop items).

**Arguments:** `owner_id`, `agent_id`, `section`, `array_field?`, `match_key`, `order` (array of values)

***

### List-style resources

Tools that read or modify list-style resources (schedules, channels, keys, etc.). Reads accept `limit` (default 50, cap 200) + `offset` pagination.

#### Schedules

* `schedule.list` — active scheduled / cron runs on this agent
* `schedule.list_runs` — history of a specific schedule
* `schedule.create` — new schedule (friendly picker or 5-field cron); `agent_notes` is the per-fire trigger message
* `schedule.delete` — remove a schedule by id

#### IM Channels

* `im.list` — bound Telegram/WhatsApp/Slack/Discord channels (secrets stripped)
* `im.create` — shell row for a provider; secrets (bot tokens, OAuth) still set via the dashboard
* `im.remove`

#### Email Endpoints

* `email_trigger.list` — inbound addresses + allowlist
* `email_trigger.create` — auto-generates an `ah-<agent-prefix>-<rand>@inbound.agentheya.com` address
* `email_trigger.remove`

#### Webhooks

* `webhook.list` — inbound webhook endpoints
* `webhook.create` — auto-generates a webhook path + URL
* `webhook.remove`

#### Handoff

* `handoff.list` — human-handoff destinations (destination strings stripped — they're PII)
* `handoff.create` — kinds: `email` / `telegram` / `owner_inbox` / `agent`; for `agent` pass `sibling_agent_id` or `target_agent_url + target_agent_api_key`
* `handoff.remove`

#### Delegates

* `delegate.list` — sibling/external agent routing targets (API keys stripped)
* `delegate.create` — `target_kind: "sibling"` (pass `sibling_agent_id`) or `"external"` (pass `target_agent_url` + `target_agent_api_key`)
* `delegate.remove`

#### Inbox

* `inbox.list` — chat sessions across every channel (compact rows)
* `inbox.get` — full session including its messages

#### Subscribers

* `user.list` — accounts registered to this agent (credentials are never returned)
* `user.get`
* `user.set_tier` — `no_settings` | `solo` | `pro`
* `user.set_blocked` — block/unblock with optional reason

#### Emails (sent/received log)

* `email.list`

#### Activity (per-query trace log)

* `activity.list` — per-query usage: tokens, cost, and timing

#### A2A

* `a2a.list_tasks` — read-only; task state is created and updated via the agent's A2A endpoint at `a2a.agentheya.com/agent/{agent_id}`

Some setup is done through the dashboard rather than MCP — cron/mode rewrites of existing schedules, and provider secret setters for IM channels (Telegram bot token registration, OAuth flows for Slack/Discord/Facebook/Instagram). Create the channel shell via `im.create`, then finish setup in the dashboard.

***

### `file.list`

Lists data files an agent has been given.

**Arguments:** `owner_id`, `agent_id`, `scope` (`"internal"` or `"public"`)

* `"internal"` — private knowledge (text-based; only the agent sees it)
* `"public"` — documents subscribers may be shown

***

### `file.upload`

Uploads a data file and queues it for indexing. The file becomes searchable once ingestion completes.

**Arguments:**

| Field              | Type                              | Description                                               |
| ------------------ | --------------------------------- | --------------------------------------------------------- |
| `owner_id`         | string                            |                                                           |
| `agent_id`         | string                            |                                                           |
| `scope`            | `"internal"` \| `"public"`        |                                                           |
| `filename`         | string                            | File name with extension, e.g. `"policies.md"`            |
| `content`          | string                            | UTF-8 text, or base64 if `content_encoding` is `"base64"` |
| `content_encoding` | `"utf8"` \| `"base64"` (optional) | Defaults to `"utf8"`                                      |

Per-plan size and format limits apply.

***

### `file.delete`

Removes a data file and de-indexes it from the agent's search index.

**Arguments:** `owner_id`, `agent_id`, `scope`, `filename`

***

### `billing.list_plans`

Returns all available subscription tiers and their credit/price options.

**No authentication required.**

Use the returned `id` and `credits_per_month` values with `account.create_checkout`.

***

### `account.create_checkout`

Generates a Stripe payment link for a chosen plan. The URL must be opened in a browser by the account owner. After successful payment, the subscription activates within a few minutes.

**Arguments:**

| Field               | Type                      | Description                                                              |
| ------------------- | ------------------------- | ------------------------------------------------------------------------ |
| `owner_id`          | string                    |                                                                          |
| `plan_id`           | string                    | Plan ID from `billing.list_plans` (e.g. `"solo"`, `"pro"`, `"business"`) |
| `credits_per_month` | integer                   | Must exactly match one of the options in the chosen plan                 |
| `billing_period`    | `"monthly"` \| `"yearly"` | Yearly billing includes a 20% discount                                   |

**Returns:** `checkout_url`, `plan`, `credits_per_month`, `billing_period`, `price_description`

***

### `account.get_status`

Returns subscription plan, credits remaining, and per-agent status.

**Arguments:**

| Field      | Type              | Description                                                           |
| ---------- | ----------------- | --------------------------------------------------------------------- |
| `owner_id` | string            |                                                                       |
| `agent_id` | string (optional) | Filter to a specific agent. If omitted, returns status for all agents |

***

### `key.create`

Generates a per-agent API key (`sk_ah_...`) for subscribers or systems to call the agent. The key is shown only once.

**Arguments:** `owner_id`, `agent_id`, `label` (optional)

**Returns:** `api_key`, `key_id`, `key_display`, `label`

Maximum 20 active keys per agent.

> **A2A use case:** Keys created here are the Bearer credentials used by external AI agents to call your agent via its A2A endpoint at `https://a2a.agentheya.com/agent/{agent_id}`. This is the programmatic alternative to creating keys manually in the dashboard. See [Agent-to-Agent (A2A)](/a2a) for the full A2A integration guide.

***

### `key.list`

Lists active per-agent API keys (display strings only — full keys are not stored).

**Arguments:** `owner_id`, `agent_id`

***

### `key.revoke`

Permanently revokes a per-agent API key.

**Arguments:** `owner_id`, `agent_id`, `key_id` (numeric ID from `key.list`)

***

## Agent lifecycle

```
create_account → pay payment_link → create_agent → configure_agent → active
                                                   ↓
                                            upload_file (optional)
                                                   ↓
                                    create_invocation_api_key
```

| `account_status` | Meaning                                              |
| ---------------- | ---------------------------------------------------- |
| `"design"`       | Created, not yet subscribed — cannot receive queries |
| `"active"`       | Subscription paid — responding to queries            |
| `"suspended"`    | Payment failed                                       |

***

## Example workflow

```json theme={null}
// 1. Create account
{ "tool": "account.create", "contact_email": "owner@example.com" }
// → owner_id, management_key, payment_link

// 2. Human opens payment_link → subscription activates

// 3. Create agent (contact_email is required)
{ "tool": "agent.create", "owner_id": "...", "preferred_name": "my-support-bot" }
// → agent_id: "abc1234567"

// 4. Configure it
{
  "tool": "config.set",
  "owner_id": "...", "agent_id": "abc1234567",
  "section": "purpose",
  "data": { "overview": "Customer support for Acme Inc." }
}

// 5. Check status
{ "tool": "account.get_status", "owner_id": "..." }

// 6. Create an API key for your app
{ "tool": "key.create", "owner_id": "...", "agent_id": "abc1234567", "label": "production" }
// → api_key: "sk_ah_..."
```