Asana Tasks & Projects
Lets an agent work in Asana: find workspaces, projects, sections and people, search and read tasks with their comments, create and update tasks, move them between sections, and post comments. Curated from Asana's official OpenAPI specification.
Connect this API to an AI agent Browse all specs
What you can do with Asana Tasks & Projects via MCP
Every endpoint below becomes a governed tool your AI agent (Claude, ChatGPT, or a customer-facing VX agent) can call — with scoped permissions, sandbox testing, and audit logs.
| Method | Path | Operation | Description |
|---|---|---|---|
| GET | /users/{user_gid} |
getUser | Get a user (use `me` for the token's own user and workspaces) |
| GET | /workspaces |
getWorkspaces | List the workspaces you belong to |
| GET | /workspaces/{workspace_gid}/users |
getUsersForWorkspace | List the people in a workspace (for assigning) |
| GET | /projects |
getProjects | List projects in a workspace or team |
| GET | /projects/{project_gid}/sections |
getSectionsForProject | List the sections (columns) of a project |
| GET | /tasks |
getTasks | List tasks by project, section, or assignee in a workspace |
| POST | /tasks |
createTask | Create a task in a project or workspace |
| GET | /projects/{project_gid}/tasks |
getTasksForProject | List the tasks in a project |
| GET | /workspaces/{workspace_gid}/tasks/search |
searchTasksInWorkspace | Search tasks in a workspace by text, assignee, due date or status |
| GET | /tasks/{task_gid} |
getTask | Get one task with its details |
| PUT | /tasks/{task_gid} |
updateTask | Update a task (name, notes, assignee, due date, completed) |
| GET | /tasks/{task_gid}/stories |
getTaskComments | List a task's comments and activity |
| POST | /tasks/{task_gid}/stories |
addTaskComment | Post a comment on a task |
| POST | /sections/{section_gid}/addTask |
addTaskToSection | Move a task into a section of a project |
Authentication
personalAccessToken
Bearer token — sent as Authorization: Bearer <token>
Send an Asana personal access token (or an OAuth access token) as Authorization: Bearer <token>.
How to get a credential
- Sign in to Asana and open the developer console: https://app.asana.com/0/my-apps.
- Under Personal access tokens, click Create new token.
- Name it (for example
VX Agents), agree to the terms and click Create token. - Copy the token (it is shown once). It acts as your user: the agent sees and changes everything you can. Use a dedicated member account to limit access.
Permissions used
Personal access tokens carry the user's full access. OAuth apps need these scopes:
| Scope | Operations |
|---|---|
users:read, workspaces:read |
getUser, getWorkspaces, getUsersForWorkspace |
projects:read |
getProjects, getSectionsForProject |
tasks:read |
getTasks, getTasksForProject, searchTasksInWorkspace, getTask |
stories:read |
getTaskComments |
tasks:write |
createTask, updateTask, addTaskToSection |
stories:write |
addTaskComment |
Common errors
- 401 Unauthorized: token missing, revoked or mistyped. Create a new token and include the
Bearerprefix. - 403 Forbidden: the user cannot access that workspace, project or task, or task search needs a paid (Premium+) workspace.
- 400 Bad Request: missing
workspaceorprojectwhen creating a task, or an invalid gid / date. Dates areYYYY-MM-DD. - 402 Payment Required: the feature (e.g. searchTasksInWorkspace) needs a paid plan.
- 429 Too Many Requests: Asana rate limit (150 requests/minute on free plans); wait for
Retry-After.
Store the token as a VX Agents credential (Bearer token) for this spec; never paste it into chat.
Usage guide
Setup
- Credential: an Asana personal access token (app.asana.com/0/my-apps > Create new token) as a Bearer token. The agent acts as that user.
- Worth pinning:
workspace/workspace_gid(fromgetWorkspacesorgetUserwithuser_gid=me) and theprojectyou work in most.
Find work
getUser(user_gid=me) for your gid and workspaces;getUsersForWorkspaceto find someone's gid to assign to.getProjects(workspace,archived=false) thengetSectionsForProjectto see a board's columns.- Tasks:
getTasksForProjectfor one project,getTaskswithassignee=me+workspacefor "my tasks", orsearchTasksInWorkspace(text,assignee.any,projects.any,due_on.before,completed=false; paid workspaces only). - Add
opt_fields=name,assignee.name,due_on,completed,memberships.section.name,permalink_urlto get useful fields; by default onlygidandnamecome back. getTaskandgetTaskComments(comments are stories withresource_subtype=comment_added) before acting.
Change tasks
createTaskwith{"data": {"name": "...", "projects": ["<project_gid>"], "assignee": "<user_gid>", "due_on": "2026-10-20", "notes": "..."}}(giveworkspaceinstead ofprojectsfor a private task).updateTaskwith{"data": {...}}, e.g.completed: true, a newassigneeordue_on.addTaskToSectionwith{"data": {"task": "<task_gid>"}}to move a task to another column.addTaskCommentwith{"data": {"text": "..."}}(orhtml_textwrapped in<body>).
Confirm before writing: show the user the new task, the changed fields, the target section, or the comment text, and wait for approval before createTask, updateTask, addTaskToSection or addTaskComment. Assignments and comments notify people.
Good to know
- Every write body is wrapped in
{"data": {...}}; ids are stringgids. due_onisYYYY-MM-DD;due_atis an ISO 8601 timestamp. Use one, not both.- Lists page with
limit(max 100) andoffsetfromnext_page.offset. completed_since=nowongetTasksForProjectreturns only incomplete tasks.- 429 means rate limited: wait
Retry-Afterseconds.
How to use this spec
- Create a free VX Agents account (sandbox tools included).
- Open the marketplace and connect “Asana Tasks & Projects” to an agent.
- Expose it as an MCP server for Claude/ChatGPT, or chat with it directly.