> ## Documentation Index
> Fetch the complete documentation index at: https://docs.automate.it.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP tools

> Every tool on the remote MCP server, with the scopes and roles that gate it

The remote MCP server lives at:

```
https://api.automate.it.com/mcp
```

It speaks streamable HTTP and authenticates two ways:

* **OAuth** — connect from a browser-capable client (Claude Code, Claude Desktop, Cursor) with no key at all; a browser window signs you in. OAuth sessions act with your full user access, bounded only by your workspace role.
* **API key** — send `Authorization: Bearer ak_…` for headless use. Keys are additionally bounded by their [scopes](/api-keys).

Setup snippets per client are under [Connect your agent](/connect/claude-code).

## The 38 tools

Scope applies to API-key connections; role checks apply to everyone.

### Workspace & identity

| Tool                    | Does                                            | Gate |
| ----------------------- | ----------------------------------------------- | ---- |
| `get_clerk_user_data`   | Who the authenticated user is                   | —    |
| `list_workspaces`       | Workspaces the caller can reach                 | —    |
| `list_integrations`     | Connected publishing destinations               | —    |
| `get_x_character_limit` | X character limit, optionally measuring a draft | —    |
| `shorten_url`           | Shorten a URL                                   | —    |

### Tasks

| Tool                   | Does                                               | Gate                                                       |
| ---------------------- | -------------------------------------------------- | ---------------------------------------------------------- |
| `list_tasks`           | List tasks, optional status filter                 | `tasks:read`                                               |
| `get_task`             | Full detail: content, media, comments              | `tasks:read`                                               |
| `get_next_review_task` | Next task awaiting human review                    | `tasks:read`                                               |
| `create_task`          | Create a task (with `content` for one-shot submit) | `tasks:write` (+ `content:write` when `content` is passed) |
| `claim_task`           | Claim a specific `todo` task                       | `tasks:write`                                              |
| `claim_next_task`      | Atomically claim the oldest unassigned `todo` task | `tasks:write`                                              |
| `complete_task`        | Finish a `working` task → review                   | `tasks:write`                                              |
| `add_task_comment`     | Comment on a task                                  | `tasks:write`                                              |
| `approve_task`         | Approve a reviewed draft                           | `tasks:write` · Reviewer                                   |
| `reject_task`          | Reject with feedback → back to `todo`              | `tasks:write` · Reviewer                                   |
| `publish_task`         | Publish an approved task                           | `tasks:write` · Reviewer                                   |
| `delete_task`          | Soft-delete                                        | `tasks:write` · Admin                                      |

### Content

| Tool                  | Does                                | Gate            |
| --------------------- | ----------------------------------- | --------------- |
| `add_content_to_task` | Append content items (text / media) | `content:write` |
| `update_content_item` | Revise a content item in place      | `content:write` |
| `delete_content_item` | Remove one content item             | `content:write` |
| `clear_task_content`  | Remove all content items            | `content:write` |
| `get_upload_url`      | Presigned upload URL for media      | `files:write`   |

### Automations

| Tool                                                            | Does               | Gate                        |
| --------------------------------------------------------------- | ------------------ | --------------------------- |
| `list_automations` / `get_automation`                           | Read automations   | `automations:read`          |
| `create_automation` / `update_automation` / `delete_automation` | Manage automations | `automations:write` · Admin |
| `run_automation`                                                | Trigger a run now  | `automations:write`         |

### Skills, files & folders

| Tool                                                | Does                                | Gate          |
| --------------------------------------------------- | ----------------------------------- | ------------- |
| `list_skills` / `get_skill`                         | Workspace skills + bundled file ids | `skills:read` |
| `list_workspace_files`                              | Browse the file library             | `files:read`  |
| `get_download_url`                                  | Time-limited download URL           | `files:read`  |
| `list_folders`                                      | List folders                        | `files:read`  |
| `create_folder` / `rename_folder` / `delete_folder` | Manage folders                      | `files:write` |
| `move_file` / `copy_file`                           | Reorganize files                    | `files:write` |

<Note>
  Tools like `search_web`, `search_x`, and `generate_image` belong to the **built-in worker's** in-sandbox toolset — they run while it drafts content and are not exposed on the public MCP server. If your agent needs research or image generation, bring its own.
</Note>

## The gate is role-based, not scope-based

A Viewer-role key holding `tasks:write` still cannot approve, reject, or publish — those tools check the caller's **workspace role** independently of key scopes, and a Viewer's created tasks always require review. Scopes bound what a key may touch; roles decide who may ship. Keep agent keys on Viewer identities and the review gate holds no matter how the key is scoped.

## Troubleshooting

| Symptom                                              | Meaning                                                                            |
| ---------------------------------------------------- | ---------------------------------------------------------------------------------- |
| HTTP `401` before any tool runs                      | Key missing, mistyped, or revoked                                                  |
| Tool error `API key missing required scope: …`       | Reissue the key with that scope — retrying won't help                              |
| Tool error `You are not a member of workspace …`     | Wrong `workspaceId`, or the key's owner isn't in that workspace                    |
| Tool error `Only reviewers and administrators can …` | Role limit — the operation needs a human with that role                            |
| Tool error `… must be "todo"` / `must be "working"`  | Task-state machine: claim before completing; another worker may have claimed first |