Let your coding agent create, configure, integrate, and diagnose HeroUI Agents.
Connect your coding agent to https://agent-mcp.heroui.pro/mcp using Streamable HTTP. Sign in to HeroUI Agents, select workspaces, and approve the permissions your client requests. Your current workspace is selected initially; additional workspaces require your selection.
This server manages HeroUI Agents. MCP servers you connect to an Agent provide tools that the hosted Agent calls during conversations. They are configured separately.
codex mcp add heroui-agents --url https://agent-mcp.heroui.pro/mcp
codex mcp login heroui-agents --scopes workspaces:read,usage:read,agents:read,agents:write,knowledge:read,knowledge:write,mcp_servers:read,mcp_servers:write,users:read,conversations:read,runs:read,api_keys:create,auth_tokens:create,offline_accessThe browser opens HeroUI Agents sign-in and consent. Approve only the workspaces and permissions needed for your task. The example requests api_keys:create and auth_tokens:create so a workspace owner can authorize an integration key during setup; omit them when reusing a key already configured on your server. Codex MCP documentation.
claude mcp add --transport http heroui-agents https://agent-mcp.heroui.pro/mcpOpen /mcp in Claude Code and authenticate the server. Claude Code MCP documentation.
Add this entry to .cursor/mcp.json, then connect through Cursor's MCP settings:
{
"mcpServers": {
"heroui-agents": {
"url": "https://agent-mcp.heroui.pro/mcp"
}
}
}Headless clients can use an existing Agents workspace key with explicit permissions:
Authorization: Bearer he_...For Codex, read the key from the environment:
codex mcp add heroui-agents --url https://agent-mcp.heroui.pro/mcp --bearer-token-env-var HEROUI_AGENT_API_KEYFor Cursor, add "headers": {"Authorization": "Bearer ${env:HEROUI_AGENT_API_KEY}"} to the entry. Populate the environment through your secret manager. Never commit the key. HeroUI Pro personal and CI/CD tokens do not authenticate this server.
Tools use typed inputs and outputs. Every Agent operation requires agent_id; creation requires workspace_id.
| Tools | Use |
|---|---|
get_connection, list_workspaces, get_workspace_usage | Inspect permissions, choose a workspace, and check limits. |
list_agents, get_agent, create_agent, update_agent, archive_agent, restore_agent | Manage the stored Agent configuration. |
Knowledge tools and create_knowledge_upload | Add URLs or authorize local uploads; inspect document readiness. |
list_mcp_servers, get_mcp_server, create_mcp_server, update_mcp_server, delete_mcp_server, discover_mcp_tools, refresh_mcp_server | Configure third-party tool connections and inspect discovery errors. |
| Webhook configuration and delivery tools | Configure events, test delivery, inspect outcomes, and retry failures. |
| User, conversation, message, and run tools | Diagnose persisted activity from the embedded app. |
create_integration_key | Create an owner-authorized key restricted to auth_tokens:create. |
search_docs, get_docs | Retrieve current Agents integration guidance. |
The API reference supplies the operation contracts and permissions used by these tools. API errors preserve their name, message, request ID, and retry timing. A saved MCP connection can still have an error; a knowledge document with processing status is not yet searchable.
OAuth uses Authorization Code with PKCE S256, a resource-bound 15-minute access token, and rotating refresh tokens lasting up to 30 days when you approve “Stay connected between sessions” (offline_access). The MCP exchanges its token for a separate API token lasting at most 60 seconds. Workspace membership and owner permissions are checked when operations execute.
Inspect and revoke grants in Connected apps. Revocation applies to existing access tokens and exchanged API tokens. Keys are revoked separately in API keys.
Existing workspace keys keep their permissions. Grant new management permissions explicitly. API/MCP setup and read operations have no separate usage charge; existing product limits and usage charges apply.
Install the optional public skill to teach your coding agent the complete workflow.