Docs contents
MCP server
Manage your AgentOS workspace from Claude Code, Claude Desktop, Cursor or any MCP client: agents, runs, approvals, schedules, evals and more.
AgentOS runs a remote MCP server over the Streamable HTTP transport. Connect it once and your assistant can answer "which agents failed this week, and why?", invoke a hosted agent, decide a pending approval or put an agent on a schedule, with the same permissions you have in the dashboard.
https://agentos-ai.dev/api/mcp
Choose a key
The server authenticates every request with a bearer key in the Authorization header. Two key types work:
| Key | Acts as | Workspace |
|---|---|---|
Workspace key (aos_ws_…) | An admin of its workspace, except that it cannot invite or remove members | Bound to the key. The workspace argument is ignored. |
Personal key (aos_user_…) | You, with your own role | Any workspace you belong to. Every tool call must pass a workspace argument: the slug or the ID. |
Agent keys (aos_agent_…) are rejected: they are for reporting and invoking one agent. See Authentication & keys for where to generate each key.
With a personal key, call workspaces_list first. It returns every workspace you belong to, with its slug and your role, so the assistant knows what to pass as workspace. Or name the workspace in your instructions: "use the workspace acme".
Connect a client
Replace aos_user_... with your key. A workspace key (aos_ws_...) goes in the same place.
claude mcp add --transport http agentos https://agentos-ai.dev/api/mcp \
--header "Authorization: Bearer aos_user_..."
The server is added for you, in the current project. Pass --scope user to use it in every project.
A missing, malformed, revoked or expired key is answered with 401. A key for a suspended workspace is answered with 403.
What you can do
The server exposes one tool per action, grouped by the part of the workspace it touches. Every tool describes its own parameters to the client, and the control plane reference lists them all.
| Area | Tools |
|---|---|
| Workspaces | workspaces_list, workspaces_create |
| Agents and folders | agents_list, agents_get, agents_create, agents_update, agents_set_status, agents_delete, folders_list, folders_create, folders_delete |
| Runs | fleet_health, runs_list, runs_get, runs_get_events, runs_invoke, runs_cancel |
| Approvals | approvals_list, approvals_decide |
| Schedules | schedules_get, schedules_upsert, schedules_delete |
| Evals | evals_list_cases, evals_create_case, evals_delete_case, evals_run_case, evals_get_run |
| Reports | reports_list, reports_get, reports_generate, reports_delete |
| Alerts | alerts_list, alerts_create, alerts_update, alerts_delete |
| Tools and integrations | tools_list_builtin, tools_list_workspace, tools_list_composio, tools_create_workspace, tools_delete_workspace, integrations_list |
| Knowledge and memory | resources_list, resources_create, resources_delete, conversations_list, conversations_get, conversations_delete |
| Marketplace | marketplace_list_templates, marketplace_install_template |
| Keys, members and notifications | api_keys_list, api_keys_create, api_keys_revoke, members_list, members_invite, members_remove, notifications_list, notifications_mark_read |
Some things to ask once it is connected:
- "Which of my agents need attention this week?" (
fleet_health, thenruns_listandruns_get_eventson the failures) - "Show me what is waiting for approval, and approve the reply to Acme." (
approvals_list,approvals_decide) - "Run the support-reply agent on this email and show me the draft." (
runs_invoke) - "Run Email Triage every day at 07:00, Lisbon time." (
schedules_upsert)
Only hosted agents can be invoked, and not while paused or archived. runs_invoke and evals_run_case wait for the run to finish, up to 5 minutes.
Create a workspace
workspaces_create takes a name and a slug and makes you the new workspace's owner. It needs a personal key, and it is only available over MCP.
Roles and limits
- Your role applies. With a personal key, each call runs with your current role in that workspace. Removing you from a workspace takes effect on your next call.
- Members see their agents. A member sees only the agents they created or whose folders they have been granted, and changes them only with a manage grant. Anything else answers as not found.
- Owner or admin only. Creating, updating and deleting alert rules, deleting reports and conversations, revoking a workspace key, and inviting or removing members. Inviting and removing members also needs a personal key: a workspace key is refused.
- Plan limits. Tools that run an agent or a model (
runs_invoke,evals_run_case,reports_generate) count toward the plan's run rate. A workspace with no subscription cannot run agents. Alert rules and period reports need a paid plan. - Audited. Inviting or removing a member, creating or revoking a key, deleting an agent, changing its status or its tools are recorded in the workspace audit log, with the key that made the call.
Approvals still apply
Connecting an assistant does not bypass your approval rules. A tool marked Approval required pauses the run before the call, whether the run was started from the dashboard, a schedule or runs_invoke, and waits for a person. You can decide it with approvals_decide (owners, admins and members), or on the Approvals page.
Changes proposed by the Operator assistant in the dashboard can only be approved in the dashboard.
The same tools over HTTP
Every tool except workspaces_create is also a plain JSON endpoint, for scripts and services that do not speak MCP:
curl -X POST https://agentos-ai.dev/api/v1/rpc/fleet_health \
-H "Authorization: Bearer aos_ws_..." \
-H "Content-Type: application/json" \
-d '{ "days": 7 }'
The same keys, schemas and role checks apply. The TypeScript and Python SDKs wrap these endpoints; see the control plane.
Security
- Prefer a personal key for your own assistant. It carries your own role and stops working in a workspace the moment you leave it. A workspace key acts as an admin, so keep it for shared automation.
- Keep keys out of files you commit. In Claude Code, the default scope keeps the server private to you; in Cursor, read the key from an environment variable.
- Revoke a key in Backoffice → API Keys as soon as you stop using it or suspect it leaked. It is rejected from its next request.
- Your assistant can do anything your key allows, including deleting agents. Review what it proposes before you let it act, and keep Approval required on the tools that reach the outside world.