# Asana — how to use (mcp.ai)

Tool to help teams organize, track, and manage their work.

## Option A — via MCP (recommended)
Remote MCP endpoint (HTTP, streamable): `https://api.mcp.ai/p_asana?ms=1781542560000`
Add it as a custom/remote MCP connector in your client (Claude, Cursor, VS Code…), then authenticate when prompted. Once connected, ask the agent to use the server's tools (e.g. `asana_add_followers_to_task`).

## Option B — via direct REST API
Base URL: `https://api.mcp.ai/api/asana`
Auth: `Authorization: Bearer sk_live_…` — create a workspace API key at https://mcp.ai/settings/api-keys
Discover endpoints: `GET https://api.mcp.ai/api/asana/_endpoints`

### Endpoints
- `POST https://api.mcp.ai/api/asana/add/followers/to/task` — Tool to add followers to a task in asana. use this tool when you need to add one or more users as followers to a specific task. this will notify them of updates to the task.
  - body: { task_gid: string, followers: string[], opt_fields?: string[], opt_pretty?: boolean }
- `POST https://api.mcp.ai/api/asana/add/supporting/relationship` — Tool to add a supporting goal relationship to a goal. use when you want to link a project, task, portfolio, or another goal as a supporting resource to a specific goal in asana.
  - body: { data: object, goal_gid: string, opt_fields?: string[], opt_pretty?: boolean }
- `POST https://api.mcp.ai/api/asana/add/task/to/section` — Adds an existing task to a section, optionally positioning it before or after another task in that section; if no position is specified, the task is added to the end.
  - body: { task_gid: string, section_gid: string, insert_after?: string, insert_before?: string }
- `POST https://api.mcp.ai/api/asana/create/a/project` — Creates a new asana project, requiring either a `workspace` or `team` gid for association, and returns the full project details.
  - body: { data: object, opt_fields?: string[], opt_pretty?: boolean }
- `POST https://api.mcp.ai/api/asana/create/a/tag/in/a/workspace` — Creates a new tag, with properties like name and color defined in the request body, within a specific asana workspace (using `workspace gid`); this tag helps categorize tasks, is confined to the works
  - body: { data: object, opt_fields?: string[], opt_pretty?: boolean, workspace_gid: string }
- `POST https://api.mcp.ai/api/asana/create/a/task` — Creates a new asana task; requires 'workspace', 'parent', or 'projects' for association, and 'followers', 'projects', 'tags' are set only at creation.
  - body: { data: object, opt_fields?: string[], opt_pretty?: boolean }
- `POST https://api.mcp.ai/api/asana/create/allocation` — Creates a new allocation. use when you need to schedule or assign a specific amount of a user's time per week to a task or project within a defined period.
  - body: { notes?: string, end_on: string, start_on: string, project_gid?: string, assignee_gid: string, workspace_gid: string, minutes_per_week: integer }
- `POST https://api.mcp.ai/api/asana/create/attachment/for/task` — Tool to upload an attachment to a task. use when you need to attach a file to a specific task in asana.
  - body: { file_name: string, parent_gid: string, file_content: string, connect_to_app?: boolean, resource_subtype?: string, file_content_type: string }
- `POST https://api.mcp.ai/api/asana/create/custom/field` — Tool to create a new custom field in a workspace. use when you need to define a new field for tracking specific information within asana tasks.
  - body: { data: object, opt_fields?: string[], opt_pretty?: boolean }
- `POST https://api.mcp.ai/api/asana/create/enum/option/for/custom/field` — Tool to create a new enum option for a custom field in asana. use this when you need to add a new selectable option to an existing custom field.
  - body: { data: object, opt_fields?: string[], opt_pretty?: boolean, custom_field_gid: string }
- `POST https://api.mcp.ai/api/asana/create/project/status/update` — Tool to create a new status update on a project. use when you need to communicate the current status, progress, or any blockers related to a specific project.
  - body: { text: string, color: string, title: string, project_gid: string, status_type: string }
- `POST https://api.mcp.ai/api/asana/create/section/in/project` — Creates a new section in a project, optionally positioned relative to an existing section in the same project, and returns the full record of the new section.
  - body: { name: string, project_gid: string, insert_after?: string, insert_before?: string }
- `POST https://api.mcp.ai/api/asana/create/subtask` — Creates a new asana subtask under an existing parent task (`task gid`); `due on` and `due at` are mutually exclusive and cannot be set simultaneously.
  - body: { name: string, notes?: string, due_at?: string, due_on?: string, assignee?: string, task_gid: string, completed?: boolean, followers?: string[] }
- `POST https://api.mcp.ai/api/asana/create/task/comment` — Adds a new text comment (story) to an existing asana task, appearing in its activity feed.
  - body: { text: string, task_id: string }
- `POST https://api.mcp.ai/api/asana/create/team` — Tool to create a new team in an asana workspace. use when you need to establish a new team for collaboration.
  - body: { data: object }
- `POST https://api.mcp.ai/api/asana/delete/allocation` — Tool to delete an allocation by its id. use this when you need to remove a specific resource allocation in asana.
  - body: { opt_pretty?: boolean, allocation_gid: string }
- `POST https://api.mcp.ai/api/asana/delete/attachment` — Tool to delete an attachment by its globally unique identifier. use when you need to remove an existing attachment from asana.
  - body: { opt_pretty?: boolean, attachment_gid: string }
- `POST https://api.mcp.ai/api/asana/delete/custom/field` — Tool to delete a custom field by its globally unique identifier. use when you need to remove an existing custom field from asana.
  - body: { custom_field_gid: string }
- `POST https://api.mcp.ai/api/asana/delete/project` — Delete a project.
  - body: { opt_pretty?: boolean, project_gid: string }
- `POST https://api.mcp.ai/api/asana/delete/tag` — Tool to delete a specific tag by its gid. use when you need to remove an existing tag from asana.
  - body: { tag_gid: string, opt_pretty?: boolean }
- `POST https://api.mcp.ai/api/asana/delete/task` — Delete a task.
  - body: { task_gid: string, opt_pretty?: boolean }
- `POST https://api.mcp.ai/api/asana/duplicate/project` — Duplicate a project.
  - body: { name: string, team?: string, include?: string[], project_gid: string, schedule_dates?: object }
- `POST https://api.mcp.ai/api/asana/duplicate/task` — Duplicate a task
  - body: { name?: string, include?: string[], task_gid: string }
- `POST https://api.mcp.ai/api/asana/get/a/project` — Retrieves a specific asana project by its `project gid`, with an option to include additional fields for comprehensive details using `opt fields`; this action does not return tasks within the project.
  - body: { opt_fields?: string[], opt_pretty?: boolean, project_gid: string }
- `POST https://api.mcp.ai/api/asana/get/a/task` — Retrieves full details for a specified task gid accessible by the user; use `opt fields` to customize returned data.
  - body: { task_gid: string, opt_fields?: string[], opt_pretty?: boolean }
- `POST https://api.mcp.ai/api/asana/get/a/user/task/list` — Retrieves a specific user's task list from asana by its `user task list gid`, optionally returning extended details like name, owner, and workspace if specified in `opt fields`.
  - body: { workspace: string, opt_fields?: string[], opt_pretty?: boolean, user_task_list_gid: string }
- `POST https://api.mcp.ai/api/asana/get/allocation` — Get an allocation by id. use when you need to retrieve the details of a specific allocation.
  - body: { opt_fields?: string[], opt_pretty?: boolean, allocation_gid: string }
- `POST https://api.mcp.ai/api/asana/get/allocations` — Tool to get multiple allocations. use when you need to retrieve a list of allocations, optionally filtered by project, user, or workspace.
  - body: { limit?: integer, offset?: string, parent?: string, assignee?: string, workspace?: string, opt_fields?: string[], opt_pretty?: boolean }
- `POST https://api.mcp.ai/api/asana/get/attachment` — Tool to get a single attachment by its globally unique identifier. use when you need to retrieve details about a specific file attached to a task or project.
  - body: { opt_fields?: string, attachment_gid: string }
- `POST https://api.mcp.ai/api/asana/get/audit/log/events` — Tool to get audit log events for a workspace. use when you need to retrieve a log of actions performed within a specific asana workspace.
  - body: { limit?: integer, end_at?: string, offset?: string, start_at?: string, actor_gid?: string, actor_type?: string, event_type?: string, resource_gid?: string, workspace_gid: string }
- `POST https://api.mcp.ai/api/asana/get/current/user` — Retrieves the authenticated user's full record, including accessible workspaces, often used as an initial call to establish user context for subsequent operations.
- `POST https://api.mcp.ai/api/asana/get/custom/field` — Tool to get a single custom field by its globally unique identifier. use when you need to retrieve the complete metadata and properties of a specific custom field in asana.
  - body: { opt_fields?: string[], opt_pretty?: boolean, custom_field_gid: string }
- `POST https://api.mcp.ai/api/asana/get/custom/fields/for/workspace` — Tool to get all custom fields in a workspace. use when you need to retrieve a list of custom fields associated with a specific workspace.
  - body: { limit?: integer, offset?: string, opt_fields?: string[], opt_pretty?: boolean, workspace_gid: string }
- `POST https://api.mcp.ai/api/asana/get/events` — Retrieve events on a resource to monitor changes. use when you need to track activity or changes related to a specific asana resource like a task, project, or tag.
  - body: { sync?: string, opt_fields?: string[], opt_pretty?: boolean, resource_gid: string }
- `POST https://api.mcp.ai/api/asana/get/goal` — Retrieve the full record for a single goal by its gid.
  - body: { goal_gid: string, opt_fields?: string }
- `POST https://api.mcp.ai/api/asana/get/goal/relationships` — Tool to retrieve goal relationships. use when you need to get the relationships associated with a specific goal in asana.
  - body: { limit?: integer, offset?: string, goal_gid: string, opt_fields?: string[], opt_pretty?: boolean }
- `POST https://api.mcp.ai/api/asana/get/goals` — Tool to retrieve multiple goals. use when you need to get a list of goals, optionally filtered by workspace, team, portfolio, project, time period, or archived status.
  - body: { team?: string, limit?: integer, offset?: string, project?: string, archived?: boolean, portfolio?: string, workspace?: string, opt_fields?: string[], time_period?: string, is_workspace_level?: boolean }
- `POST https://api.mcp.ai/api/asana/get/memberships` — Tool to retrieve memberships for goals, projects, portfolios, or custom fields. use this to find out who has access to a specific asana resource or what resources a specific user/team has access to.
  - body: { limit?: integer, member?: string, offset?: string, parent?: string, opt_fields?: string }
- `POST https://api.mcp.ai/api/asana/get/multiple/projects` — Returns a list of projects, optionally filtered by workspace, team, or archived status, supporting pagination for large datasets.
  - body: { team?: string, limit?: integer, offset?: string, archived?: boolean, workspace?: string, opt_fields?: string[], opt_pretty?: boolean }
- `POST https://api.mcp.ai/api/asana/get/multiple/tasks` — Retrieves a list of tasks, allowing filtering by assignee (requires `workspace`), project, section, `completed since`, and `modified since`; `workspace` also requires `assignee`.
  - body: { limit?: integer, offset?: string, project?: string, section?: string, assignee?: string, workspace?: string, opt_fields?: string[], opt_pretty?: boolean, modified_since?: string, completed_since?: string }
- `POST https://api.mcp.ai/api/asana/get/multiple/users` — Returns a list of users in an asana workspace or organization, optionally filtered by workspace or team gid, with support for pagination and specifying optional fields.
  - body: { team?: string, limit?: integer, offset?: string, workspace?: string, opt_fields?: string[], opt_pretty?: boolean }
- `POST https://api.mcp.ai/api/asana/get/multiple/workspaces` — Retrieves all workspaces accessible by the authenticated user, returning an empty list if the user has no accessible workspaces.
  - body: { limit?: integer, offset?: string, opt_fields?: string[], opt_pretty?: boolean }
- `POST https://api.mcp.ai/api/asana/get/portfolio` — Retrieve the full record for a single portfolio by its gid. use this when you need to get detailed information about a specific portfolio.
  - body: { limit?: integer, offset?: string, opt_fields?: string[], opt_pretty?: boolean, portfolio_gid: string }
- `POST https://api.mcp.ai/api/asana/get/portfolio/items` — Retrieve items in a portfolio. use this to get a list of projects or other portfolios contained within a specific portfolio.
  - body: { limit?: integer, offset?: string, opt_fields?: string[], portfolio_gid: string }
- `POST https://api.mcp.ai/api/asana/get/portfolio/memberships` — Tool to retrieve multiple portfolio memberships. use this tool when you need to list memberships for a specific portfolio, a user within a portfolio, or a user across all portfolios in a workspace.
  - body: { user?: string, limit?: integer, offset?: string, portfolio?: string, workspace?: string, opt_fields?: string[] }
- `POST https://api.mcp.ai/api/asana/get/portfolios` — Retrieve multiple portfolios. use when you need to list portfolios within a specific workspace, optionally filtered by owner.
  - body: { limit?: integer, owner?: string, offset?: string, workspace: string, opt_fields?: string[] }
- `POST https://api.mcp.ai/api/asana/get/project/brief` — Tool to retrieve a project's brief. use when you need to get the detailed explanation (what and why) of a project.
  - body: { opt_fields?: string[], opt_pretty?: boolean, project_brief_gid: string }
- `POST https://api.mcp.ai/api/asana/get/project/memberships` — Tool to retrieve memberships from a project. it can also be used to get memberships for a user across multiple projects or all projects in a workspace.
  - body: { user?: string, limit?: integer, offset?: string, project?: string, workspace?: string, opt_fields?: string[], opt_pretty?: boolean }
- `POST https://api.mcp.ai/api/asana/get/project/status` — Tool to retrieve the full record for a single project status by its gid. use when you need to get the details of a specific project status update.
  - body: { opt_fields?: string[], opt_pretty?: boolean, project_status_gid: string }
- `POST https://api.mcp.ai/api/asana/get/project/status/updates` — Tool to get status updates for a specific project. use when you need to retrieve the latest or historical status reports associated with an asana project.
  - body: { limit?: integer, offset?: string, opt_fields?: string[], opt_pretty?: boolean, project_gid: string }
- `POST https://api.mcp.ai/api/asana/get/project/templates` — Tool to retrieve multiple project templates. use when you need to list available project templates in a workspace or team.
  - body: { limit?: integer, offset?: string, team_gid?: string, opt_fields?: string[], workspace_gid?: string }
- `POST https://api.mcp.ai/api/asana/get/projects/for/team` — Tool to get a list of projects for a specific team in asana. use when you need to retrieve project details associated with a team.
  - body: { limit?: integer, offset?: string, archived?: boolean, team_gid: string, opt_fields?: string[], opt_pretty?: boolean }
- `POST https://api.mcp.ai/api/asana/get/section` — Retrieve the full record for a single section by its gid. use this when you need to get details about a specific section within a project.
  - body: { opt_fields?: string[], opt_pretty?: boolean, section_gid: string }
- `POST https://api.mcp.ai/api/asana/get/sections/in/project` — Returns compact records for all sections (used to group tasks) in a specified project.
  - body: { limit?: integer, offset?: string, project_gid: string }
- `POST https://api.mcp.ai/api/asana/get/status/updates` — Retrieve status updates from an object. use when you need to get the latest or historical status updates for a specific project, portfolio, or goal.
  - body: { limit?: integer, offset?: string, parent: string, opt_fields?: string[] }
- `POST https://api.mcp.ai/api/asana/get/stories/for/task` — Tool to get stories (comments, status updates, etc.) for a task. use when you need to retrieve the history or discussion associated with a specific task.
  - body: { limit?: integer, offset?: string, task_gid: string, opt_fields?: string[] }
- `POST https://api.mcp.ai/api/asana/get/story` — Tool to retrieve a story. use when you need to get the complete record for a single story.
  - body: { story_gid: string, opt_fields?: string[], opt_pretty?: boolean }
- `POST https://api.mcp.ai/api/asana/get/tag` — Tool to get a single tag by its globally unique identifier. use when you need to retrieve detailed information about a specific tag.
  - body: { tag_gid: string, opt_fields?: string[], opt_pretty?: boolean }
- `POST https://api.mcp.ai/api/asana/get/tags` — Get multiple tags in a workspace.
  - body: { limit?: integer, offset?: string, workspace?: string, opt_fields?: string[] }
- `POST https://api.mcp.ai/api/asana/get/task/attachments` — Tool to get the list of attachments for a given task, project, or project brief. use when you need to retrieve files attached to a specific asana object.
  - body: { limit?: integer, offset?: string, opt_fields?: string[], parent_gid: string }
- `POST https://api.mcp.ai/api/asana/get/task/subtasks` — Tool to retrieve multiple task subtasks from a workspace. use when you need to list or find available task subtasks.
  - body: { limit?: integer, offset?: string, task_gid: string, opt_fields?: string[] }
- `POST https://api.mcp.ai/api/asana/get/task/templates` — Tool to retrieve multiple task templates from a workspace. use when you need to list or find available task templates.
  - body: { limit?: integer, offset?: string, opt_fields?: string, project_gid?: string, workspace_gid?: string }
- `POST https://api.mcp.ai/api/asana/get/tasks/from/a/project` — Retrieves tasks from a specified asana project, allowing filtering by completion status and selection of optional fields for detailed responses.
  - body: { limit?: integer, offset?: string, opt_fields?: string[], opt_pretty?: boolean, project_gid: string, completed_since?: string }
- `POST https://api.mcp.ai/api/asana/get/team` — Tool to retrieve details of a specific team by its gid. use when you need to fetch information about a particular team in asana.
  - body: { team_gid: string, opt_fields?: string[], opt_pretty?: boolean }
- `POST https://api.mcp.ai/api/asana/get/team/memberships` — Tool to retrieve compact team membership records. use when you need to list members of a team, teams a user belongs to, or all team memberships in a workspace.
  - body: { team?: string, user?: string, limit?: integer, offset?: string, workspace?: string, opt_fields?: string[], opt_pretty?: boolean }
- `POST https://api.mcp.ai/api/asana/get/teams/in/workspace` — Returns the compact records for all teams in the workspace visible to the authorized user.
  - body: { limit?: integer, offset?: string, workspace_gid: string }
- `POST https://api.mcp.ai/api/asana/get/time/periods` — Tool to retrieve compact or full representations of time periods. use this when you need to fetch information about specific time periods, such as their start and end dates, display names, and parent 
  - body: { limit?: integer, end_on?: string, offset?: string, start_on?: string, opt_fields?: string[], opt_pretty?: boolean, workspace_gid: string }
- `POST https://api.mcp.ai/api/asana/get/typeahead/objects` — Tool to retrieve objects in a workspace via a typeahead search algorithm. use when you need to quickly find objects like tasks, projects, users, etc., based on a search string. this is useful for impl
  - body: { count?: integer, query?: string, opt_fields?: string[], opt_pretty?: boolean, resource_type?: string, workspace_gid: string }
- `POST https://api.mcp.ai/api/asana/get/user` — Get a user by their id.
  - body: { user_gid: string, opt_fields?: string[], opt_pretty?: boolean }
- `POST https://api.mcp.ai/api/asana/get/users/for/team` — Get users in a team.
  - body: { limit?: integer, offset?: string, team_gid: string, opt_fields?: string[], opt_pretty?: boolean }
- `POST https://api.mcp.ai/api/asana/get/users/for/workspace` — Get users in a workspace or organization.
  - body: { limit?: integer, offset?: string, opt_fields?: string[], opt_pretty?: boolean, workspace_gid: string }
- `POST https://api.mcp.ai/api/asana/get/workspace` — Tool to retrieve details of a specific workspace by its gid. use when you need to get information about a particular asana workspace.
  - body: { opt_fields?: string[], opt_pretty?: boolean, workspace_gid: string }
- `POST https://api.mcp.ai/api/asana/get/workspace/memberships` — Tool to retrieve the workspace memberships for a specific workspace. use when you need to list members of a workspace.
  - body: { user?: string, limit?: integer, offset?: string, opt_fields?: string[], workspace_gid: string }
- `POST https://api.mcp.ai/api/asana/get/workspace/projects` — Tool to retrieve the projects associated with a specific workspace. use when you need to list all projects within a given asana workspace.
  - body: { limit?: integer, offset?: string, opt_expand?: string[], opt_fields?: string[], workspace_gid: string }
- `POST https://api.mcp.ai/api/asana/insert/enum/option/for/custom/field` — Tool to reorder an existing enum option or insert a new enum option for a custom field at a specific position. use when you need to manage the order of options in an enum custom field or add a new opt
  - body: { data: object, opt_fields?: string[], opt_pretty?: boolean, custom_field_gid: string }
- `POST https://api.mcp.ai/api/asana/remove/follower/from/task` — Tool to remove one or more followers from a task. use when you need to update the list of users following a specific task.
  - body: { task_gid: string, followers: string[] }
- `POST https://api.mcp.ai/api/asana/submit/parallel/requests` — Tool to submit multiple asana api requests in parallel using the batch api. use when you need to perform several operations efficiently, such as fetching multiple tasks or creating multiple subtasks a
  - body: { data: object }
- `POST https://api.mcp.ai/api/asana/update/a/task` — Updates attributes of an existing asana task identified by its task gid.
  - body: { data: object, task_gid: string, opt_fields?: string[], opt_pretty?: boolean }
- `POST https://api.mcp.ai/api/asana/update/allocation` — Tool to update an existing allocation by its id. use this when you need to modify details like the start date, end date, effort, or assignee for an allocation.
  - body: { data: object, opt_fields?: string[], opt_pretty?: boolean, allocation_gid: string }
- `POST https://api.mcp.ai/api/asana/update/custom/field` — Tool to update a custom field by its globally unique identifier. use when you need to modify properties of an existing custom field in asana.
  - body: { data: object, opt_fields?: string[], opt_pretty?: boolean, custom_field_gid: string }
- `POST https://api.mcp.ai/api/asana/update/enum/option` — Tool to update an enum option for a custom field. use when you need to modify the name, color, or enabled status of an existing enum option.
  - body: { data: object, opt_fields?: string[], opt_pretty?: boolean, enum_option_gid: string }
- `POST https://api.mcp.ai/api/asana/update/project` — Update a project.
  - body: { name?: string, team?: string, color?: string, notes?: string, owner?: string, due_on?: string, public?: boolean, archived?: boolean, due_date?: string, start_on?: string, html_notes?: string, is_template?: boolean, project_gid: string, default_view?: string, custom_fields?: object }
- `POST https://api.mcp.ai/api/asana/update/tag` — Tool to update an existing tag by its globally unique identifier. use when you need to change the name or color of a tag.
  - body: { data: object, tag_gid: string }
- `POST https://api.mcp.ai/api/asana/update/team` — Tool to update details of an existing team. use when you need to change a team's name, description, or organization.
  - body: { name?: string, team_gid: string, opt_fields?: string[], opt_pretty?: boolean, description?: string, organization?: string }

## More
- Page: https://mcp.ai/asana
- Agent spec (llms.txt): https://mcp.ai/asana/llms.txt
- Postman collection: https://mcp.ai/asana/postman.json