Management MCP - Agentheya

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

Call account.create — no authentication required. You receive an owner_id, a management_key, and a payment_link.
Open the payment_link in a browser to complete the initial Pro subscription. Agent creation is blocked until payment is confirmed.
Authenticate subsequent calls by sending the management key as a Bearer token and passing owner_id as a tool argument:
Authorization: Bearer sk_mgmt_...
Call agent.create to create an agent. Configure it with config.set and file.upload.
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) 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

// 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_..."

​Getting started

​Authentication

​Tools

​account.create

​agent.create

​agent.list

​agent.delete

​schema.get

​config.get

​config.set

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

​patch.set_fields

​patch.add_item

​patch.update_item

​patch.remove_item

​patch.reorder_items

​List-style resources

​Schedules

​IM Channels

​Email Endpoints

​Webhooks

​Handoff

​Delegates

​Inbox

​Subscribers

​Emails (sent/received log)

​Activity (per-query trace log)

​A2A

​file.list

​file.upload

​file.delete

​billing.list_plans

​account.create_checkout

​account.get_status

​key.create

​key.list

​key.revoke

​Agent lifecycle

​Example workflow