MCP Tools Reference

The Asana V2 MCP server exposes a set of tools that allow AI assistants to read from and write to your Asana workspace. This page describes the tools, what they do, and when to use them. Availability and tool versions can vary by client and rollout. Use tools/list in your connected client to see which tools are available to your session.

🚧

This list changes over time. Tools may be added, updated, or deprecated as the tool set evolves. Always use the tools/list MCP command in your client to get the current tool schemas. Subscribe to the developer changelog for update notifications.

How to use this reference

Tools are grouped into three categories:

  • Read tools return data from your workspace without making any changes.
  • Write tools create, modify, or delete data in your workspace.
  • Interactive tools display task search results or let you review a task or project before creating it. Availability depends on whether the client supports interactive apps.

Access and permissions: MCP apps in Asana do not use permission scopes. When a user authorizes an MCP client, the token automatically requests full access to all available tools. Once authorized, a tool cannot access projects, tasks, or data that the authenticated user does not already have permission to view in Asana.

Read tools

ToolDescriptionExample prompts
search_objectsSearches tasks, projects, project templates, portfolios, goals, teams, users, tags, custom fields, and AI Teammates by name. Use this first when you do not know an object's GID. Use resource_type: project_template to find project templates, goal to find goals, agent for AI Teammates, or actor for humans and AI Teammates together."Find the onboarding project template" / "Find the AI Teammate named Triage Bot"
get_taskReturns task details, including assignee, dates, custom fields, projects, dependencies, followers, parent, and section memberships. Comments and subtasks are included by default and can be excluded with include_comments or include_subtasks. Use comment_limit to control the number of comments returned."Show me the details of this task" / "What are the subtasks on the Website Redesign task?"
get_task_storiesReturns the activity feed for one task or multiple tasks, including comments and system activity such as assignments, completion, and date changes. Use task_id for a single task or task_ids for a batch. Pagination with offset is available only for a single task. Additional filters and sorting depend on the schema returned by tools/list."What changed on this task?" / "Summarize activity across these tasks"
get_tasksLists tasks by project, section, tag, user task list, or workspace and assignee. Supports modification and completion date filters, pagination, and opt_fields. Use completed_since: now for incomplete tasks."List all incomplete tasks in the Marketing project" / "Show me tasks assigned to me that were modified this week"
get_my_tasksReturns tasks assigned to the authenticated user. Supports pagination and completed_since. Use completed_since: now for incomplete tasks, omit it for all tasks, or provide a timestamp to include tasks completed since that time."What tasks do I have?" / "Show me my incomplete tasks"
get_notificationsLists Inbox notifications for the authenticated user in the workspace. Includes who triggered each notification and the related work objects. Supports pagination; request opt_fields: story.text for the underlying comment or activity text. Available when notification tools are enabled for your session; check tools/list."What needs my attention in Inbox?" / "What happened while I was away?"
search_tasksAdvanced task search with full-text and complex filters. Searches task names, descriptions, and comments. Supports filtering by assignee, due date, creation date, project, section, tag, and custom fields. Available on Premium accounts only; use get_tasks for non-Premium workspaces."Find all overdue tasks assigned to me" / "Search for tasks mentioning 'API redesign' due this month"
get_projectReturns project details, including owner, members, current status, task counts, and optionally sections. A null task count or sections value means the data could not be retrieved, rather than zero tasks or no sections."Show me the details of the Product Launch project" / "What sections does Sprint 12 have?"
get_projectsLists projects in the workspace, optionally filtered by team or archive status. Returns task counts by default; use opt_fields for other fields such as owner or members. Use search_objects to find projects by name. Null task counts mean counts could not be retrieved."List all active projects" / "Show me projects for the Engineering team"
get_portfolioReturns details for a portfolio by GID. Use opt_fields to request additional fields, and get_items_for_portfolio to list its contents."Show me the details of the Q4 portfolio"
get_portfoliosReturns a list of portfolios owned by the authenticated user in the current workspace."What portfolios do I own?" / "List all my portfolios"
get_items_for_portfolioReturns the items inside a portfolio, including projects and goals with their names and IDs."What projects are in the Company Goals portfolio?" / "List the items in this portfolio"
get_status_overviewReturns an aggregated status report for one or more projects or portfolios based on keyword search. Includes project details, current status updates, task summaries, and flagged blockers. This tool handles its own search internally — do not chain other search tools before calling it."Give me a status overview of the Rebrand initiative" / "What's the current status of Q2 planning?"
get_attachmentsReturns attachments for a task, project, or project brief. Includes file names, download URLs, and view URLs."What files are attached to this task?" / "Show me the attachments on the Design Spec project"
get_userReturns details for a user by GID, email address, or the string "me". Returns name, email, and workspace memberships. When called without a user identifier, returns the authenticated user."Who am I authenticated as?"
get_meReturns the name, email, and workspace memberships of the currently authenticated user. Use when you need specific details about the authenticated user rather than just their GID."What account am I logged in as?" / "Show me my user details"
get_usersLists users in the workspace, optionally filtered by team membership. Returns GID, name, and email by default; use opt_fields to request additional fields."Who is on the Engineering team?" / "List users in the workspace"
get_teamsReturns a list of teams in the workspace. Optionally filter to only teams a specific user belongs to."List all teams in the workspace" / "What teams is this user a member of?"
get_agentReturns the full record for a single AI Teammate agent by GID. Includes name, description, behavior guidance, workspace, and photo. Use get_workspace_agents first to discover agent GIDs, then call this tool for full details on a specific agent."Show me the details of this AI Teammate" / "What does the Triage Bot agent do?"
get_workspace_agentsReturns a list of AI Teammate agents configured in the workspace. Each record includes GID, name, resource type, and resource subtype. Use this to discover available AI Teammates before fetching full details with get_agent. Supports pagination. Note: this returns AI Teammates only — not human users. Use get_users for people."What AI Teammates are configured in this workspace?" / "List all available agents"
get_tableReturns a single table by GID. Set include_custom_field_settings to also return the table's custom field schema as a paginated custom_field_settings object; use custom_field_settings_limit and custom_field_settings_offset to page through it."Show me the details of this table" / "What fields does the Vendors table have?"
get_tablesLists tables in the workspace. Supports pagination with limit and offset, and opt_fields for additional fields."List all tables in the workspace"
get_recordReturns a single record by GID. Includes the record's comments by default as a paginated comments object; set include_comments to false to omit them. Use comment_limit to control how many comments are returned and comment_offset to page through the rest."Show me the details of this record" / "What comments are on this record?"
get_recordsLists the records in a table. Requires the table GID. Supports modified_since filtering, sorting by created_at, and pagination."List all records in the Vendors table" / "Show records modified since last Monday"
search_recordsSearches records across a workspace. Requires at least one filter besides sort options. Filter by name text, tables (tables_any, tables_not, tables_all), teams, followers, creation date, and custom fields."Find records named 'Acme' in the Vendors table" / "Search for records created this week"

Write tools

ToolDescriptionExample prompts
create_tasksCreates one or more tasks immediately, with up to 50 tasks per call. Each task needs a project, parent task, or workspace and assignee context. Use default_project and default_assignee to share defaults across tasks. Supports sections, dates, descriptions, followers, and custom fields. Returns created tasks, failures, and a summary. Use an available task preview tool when the user asks to review before creating."Create tasks for each item in this list" / "Add three subtasks to this parent task"
create_projectCreates a project immediately, optionally with sections and tasks in those sections. If no team is provided, the server chooses a default team. Returns the project and results for section and task creation. Use an available project preview tool when the user asks to review before creating."Create a project for the Q4 launch with Backlog and In Progress sections" / "Set up a new project for the design team"
create_task_from_templateLists a project's task templates when only project_id is provided, or starts creating a task from a template GID or an exact template name within that project. Name matching ignores case and requires one exact match. Creation is asynchronous."Show the task templates in this project" / "Create a task from the Bug Report template"
create_project_from_templateStarts creating a project from a project template. Find templates by name with search_objects and resource_type: project_template. Supports a project name, team, privacy, requested dates, and role assignments. Pass the desired team explicitly; omitting it does not inherit the template's team. Creation is asynchronous."Create an onboarding project from our standard template"
update_projectUpdates project details, dates, owner, appearance, privacy, archive status, project custom-field values, sections, members, and custom-field settings for tasks. Adding members, making the project public, or changing default access requires explicit user confirmation. For those access changes, call without confirmation first to review the effects, then retry with confirmation after approval. Reports partial failures; some changes may still apply."Archive the completed launch project" / "Add a Review section to this project"
update_tasksUpdates one or more tasks, with up to 50 tasks per call. Supports names, assignees, dates, descriptions, completion, parent tasks, dependencies, dependents, project membership, followers, and custom fields. Reports successes and failures separately. A failed task may still have some changes applied."Mark these tasks as complete" / "Move these tasks to the Launch project"
update_notificationsMarks one or more of the authenticated user's Inbox notifications as read or unread. Pass notification GIDs from get_notifications and set is_read to true for read or false for unread. Available when notification tools are enabled for your session; check tools/list."Mark these notifications as read" / "Mark this notification as unread"
delete_taskDeletes a task and any subtasks that are not also members of another project. Use care when deleting tasks."Delete this duplicate task"
add_commentAdds a task comment using exactly one of text or html_text. Supports mentions and pinned comments. Use for discussion, feedback, or context. Asana automatically logs actions such as assignments and status changes."Add a comment saying the design files are ready for review" / "Post a summary of today's decisions to this task"
create_project_status_updatePosts a status update to a project or portfolio. Requires a title, a color (green, yellow, red, blue, or complete), and exactly one of text or html_text."Post a green status update to the Q3 Roadmap project saying we are on track" / "Mark the Product Launch portfolio as at risk"
create_tableCreates a table in the workspace. Requires a name. Optionally pass custom_field_settings to set the table's initial custom field schema, using existing custom field GIDs or inline definitions for new fields. The table is created first, then each field is added in order. The table is still created if some fields fail, so check failed in the response."Create a Vendors table with a Status field and a Contract value field"
update_tableRenames a table and/or adds or removes individual custom fields from its schema. At least one of name, add_custom_fields, or remove_custom_fields is required. Each change affects only the fields it names; the schema is never replaced as a whole."Rename this table to Approved Vendors" / "Add a Renewal date field to this table"
create_recordsCreates up to 50 records in one call. Each record requires a name and a table, and supports custom field values for fields already on the table. Returns created records, failures, and a summary."Add these vendors as records in the Vendors table"
update_recordsUpdates up to 50 records in one call. Each item requires a record GID plus a name and/or custom_fields. Items with neither are skipped. Reports successes and failures separately."Rename this record" / "Set the status of these records to Approved"
delete_recordPermanently deletes a record. This cannot be undone through this tool."Delete this duplicate record"
add_record_commentAdds a comment to a record using exactly one of text or html_text. Supports pinned comments with is_pinned."Comment on this record that the contract was signed"

Interactive tools

These tools display interactive search results or a draft for review before creation in clients that support interactive apps. Use tools/list to check the available preview tools and their schemas. Other clients can use the standard read and write tools.

ToolDescriptionExample prompts
create_task_previewDrafts a task for review before creation. Supports project and section selection, subtasks, rich text descriptions, and editing after creation."Let me review a follow-up task before creating it" / "Preview a task with two subtasks"
create_project_previewDrafts a project plan with sections and tasks for review before creation. Supports subtasks, rich text task descriptions, and editing after creation."Preview a project plan for our Q4 launch" / "Let me approve the website redesign plan before creating it"
search_tasks_previewSearches tasks and displays results in an interactive UI. Supports text search, assignees, project, due and start date ranges, and completion status."Show me a visual list of tasks due this week" / "Find incomplete tasks assigned to me"

Tips for developers

  • Migrating from V1? Tool names in V2 no longer use the asana_ prefix. Task creation and updates use create_tasks and update_tasks. Many tools that previously required a workspaceGid parameter no longer do, because workspace scope is set at authorization time. Review the V2 changelog post for the full list of what was renamed, consolidated, and dropped.
  • Use tools/list for current schemas. Tool parameters may change over time. The authoritative source for parameter names, types, and constraints is the tools/list MCP command, not this page.
  • Check batch results. Task creation, task updates, project creation with sections and tasks, project updates, record creation, record updates, table creation, and table updates can partially succeed. Inspect failures before retrying so you do not repeat changes that already succeeded.
  • Tokens are workspace-scoped. When you authorize an MCP session, you select a specific workspace. All tool calls in that session are scoped to that workspace. To work across multiple workspaces, you need separate sessions.
  • MCP tokens do not work with the Asana REST API. Tokens issued for MCP apps are valid only for the MCP server. For standard API access, create a separate app and authenticate through the standard OAuth flow.
  • App visibility can be limited to specific workspaces for private apps. In the Asana developer console under "Manage distribution", you can control which workspaces' users are allowed to see your app.

Related resources


Did this page help you?