Merge Unified's Asana integration Merge Agent Handler's Asana MCP server

Connect your AI Agents to Asana in minutes

Merge lets you securely connect your agents to Asana and thousands of tools instantly

Start building for free

Read docs

Asana

Learn more about Merge Agent Handler

Available tools

get_attachment

Get attachment details by GID including download URLs and metadata

delete_attachment

Permanently delete an attachment. This action is irreversible. Use list_attachments to find attachment GIDs.

list_attachments

List attachments for task or project with pagination

create_custom_field

Create workspace custom field with type: text, number, date, enum, multi-enum, or people. Use list_workspaces to find workspace GIDs.

get_custom_field

Get custom field details by GID including type, options, and settings

update_custom_field

Update a custom field's name, description, or number precision. Enum options cannot be changed here. Use listcustomfields to find custom field GIDs.

delete_custom_field

Permanently delete a custom field. This action is irreversible. Use listcustomfields to find custom field GIDs.

list_custom_fields

List custom fields in workspace with pagination

create_project

Create project in workspace with team, privacy, view, dates, and members. Use listworkspaces and listteams to find workspace and team GIDs.

get_project

Get complete project details by GID including name, team, members, dates, and settings

update_project

Update project properties including name, notes, color, privacy, dates, and owner. Only fields you supply change. Use list_projects to find project GIDs.

delete_project

Permanently delete a project. This action is irreversible. Use list_projects to find project GIDs.

list_projects

List projects with workspace, team, or archive filtering. Supports pagination

get_project_tasks

Get all tasks in a project with optional field selection and pagination

add_project_members

Add members to project for collaboration and access. Use listprojects and listusers to find project and user GIDs.

remove_project_members

Remove members from project to revoke access. Use listprojects and listusers to find project and user GIDs.

add_custom_field_to_project

Associate custom field with project for task metadata. Use listprojects and listcustom_fields to find the GIDs.

remove_custom_field_from_project

Remove custom field from project to clean up metadata. Use listprojects and listcustom_fields to find the GIDs.

get_custom_fields_from_project

List all custom fields configured on a project with pagination support

search_tasks

Advanced task search with text, assignee, project, date, and custom field filters. Requires Premium. This endpoint cannot paginate: it returns at most one page (limit, max 100) and no cursor. resultstruncated=true means matches were cut off -- narrow the filters and search again. Use listtasks for pageable browsing.

get_task_stories

Get all comments and activity for task including assignments and status changes

get_story

Get story or comment details by GID including text and author

update_story

Edit story or comment text and pinned status. Can only edit own stories. Use gettaskstories to find story GIDs.

delete_story

Delete story or comment. Can only delete own stories. Action is irreversible. Use gettaskstories to find story GIDs.

create_comment

Add a plain-text or HTML comment to a task, optionally pinned. Provide text or htmltext. Use listtasks to find task GIDs.

list_tags

List tags in workspace with optional field selection and pagination

get_task_tags

Get all tags for a task including names and colors

create_tag

Create tag in workspace with name, color, and notes. Use list_workspaces to find workspace GIDs.

get_tag

Get a single tag by GID including name, color, notes, and workspace. Use list_tags to find tag GIDs.

update_tag

Update a tag's name, color, or notes. Only the fields you supply are changed. Use list_tags to find tag GIDs.

delete_tag

Permanently delete a tag. Removes it from every task it is applied to. This action is irreversible. Use list_tags to find tag GIDs.

create_task

Create task in workspace, project, or as subtask with name, assignee, dates, followers, tags, and custom fields. Use listworkspaces or listprojects to find the GIDs.

get_task

Get complete task details by GID including name, assignee, dates, status, followers, tags, and custom fields

update_task

Update task properties including name, assignee, dates, status, and custom fields. Use list_tasks to find task GIDs.

delete_task

Permanently delete a task. This action is irreversible. Use list_tasks to find task GIDs.

list_tasks

List tasks filtered by project, tag, section, usertasklist, or assignee+workspace. Supports date filters and pagination. Use listprojects, listtags, listworkspaces, or getusertasklist (a user's My Tasks list) to find valid GIDs. No tool lists sections: take a section GID from its URL in the Asana UI.

add_task_followers

Add followers to task for notifications about task updates and changes. Use listtasks and listusers to find task and user GIDs.

remove_task_followers

Remove followers from task to stop notifications about updates. Use listtasks and listusers to find task and user GIDs.

get_task_subtasks

Get all subtasks of a parent task with optional field selection

create_task_subtask

Create subtask under parent task with name, assignee, dates, and other properties. Use list_tasks to find the parent task GID.

add_task_tag

Add tag to task for categorization and filtering. Use listtasks and listtags to find task and tag GIDs.

remove_task_tag

Remove tag from task to change categorization. Use listtasks and listtags to find task and tag GIDs.

get_task_dependencies

Get tasks that must complete before this task. Returns up to 30 dependencies

add_task_dependencies

Add dependencies to a task and return the task's resulting dependency list. Asana's write response is empty, so this reads the list back to prove the effect: 2 API calls per invocation. Max 30 dependencies and dependents combined per task. Use list_tasks to find task GIDs.

remove_task_dependencies

Remove dependency relationships from a task and return its remaining dependency list. Asana's write response is empty, so this reads the list back to prove the effect: 2 API calls per invocation. Use gettaskdependencies to see current ones, or list_tasks to find task GIDs.

list_teams

List teams in workspace with optional field selection

get_team

Get team details by GID including name and organization

get_team_members

Get all members of a team with user details. Use listteams to find team GIDs. Pass optfields to get those fields in one request; without it this makes one extra request per member. Members whose lookup fails are returned as a bare {gid} ref and counted in degraded_members.

list_users

List users in workspace with optional team filtering and field selection

get_user

Get user details by GID including name, email, and workspaces

get_current_user

Get current authenticated user details including name, email, and workspaces

get_user_task_list

Get a user's My Tasks list for one workspace and return its GID. Call this first to obtain the GID for the usertasklist filter on listtasks: that filter needs a user-task-list GID, not a user GID. usergid accepts "me" (default), an email, or a GID from listusers; get workspace GIDs from listworkspaces.

validate_credential

Validate Asana credentials. Verifies credentials during setup.

list_workspaces

List all workspaces accessible to the authenticated user

get_workspace

Get workspace details by GID including name and organization status

update_workspace

Update workspace name. Use list_workspaces to find workspace GIDs.

View all tools by creating a free account See more tools

How to set up Merge Agent Handler

In an mcp.json file, add the configuration below, and restart Cursor.

Learn more in the official documentation ↗

1{
2  "mcpServers": {
3    "agent-handler": {
4      "url": "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
5      "headers": {
6        "Authorization": "Bearer yMt*****"
7      }
8    }
9  }
10}
11

Copy Code

Open your Claude Desktop configuration file and add the server configuration below. You'll also need to restart the application for the changes to take effect.

Make sure Claude is using the Node v20+.

Learn more in the official documentation ↗

1{
2  "mcpServers": {
3    "agent-handler": {
4      "command": "npx",
5      "args": [
6        "-y",
7        "mcp-remote@latest",
8        "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
9        "--header",
10        "Authorization: Bearer ${AUTH_TOKEN}"
11      ],
12      "env": {
13        "AUTH_TOKEN": "yMt*****"
14      }
15    }
16  }
17}

Copy Code

Open your Windsurf MCP configuration file and add the server configuration below.
Click on the refresh button in the top right of the Manage MCP server page or in the top right of the chat box in the box icon.

Learn more in the official documentation ↗

1{
2    "mcpServers": {
3      "agent-handler": {
4        "command": "npx",
5        "args": [
6          "-y",
7          "mcp-remote@latest",
8          "https://ah-api.merge.dev/api/v1/tool-packs/<tool-pack-id>/registered-users/<registered-user-id>/mcp",
9          "--header",
10          "Authorization: Bearer ${AUTH_TOKEN}"
11        ],
12        "env": {
13          "AUTH_TOKEN": "<ah-production-access-key>"
14        }
15      }
16    }
17  }

Copy Code

In Command Palette (Cmd+Shift+P on macOS, Ctrl+Shift+P on Windows), run "MCP: Open User Configuration".

You can then add the configuration below and press "start" right under servers. Enter the auth token when prompted.

Learn more in the official documentation ↗

1{
2  "inputs": [
3    {
4      "type": "promptString",
5      "id": "agent-handler-auth",
6      "description": "Agent Handler AUTH_TOKEN", // "yMt*****" when prompt
7      "password": true
8    }
9  ],
10  "servers": {
11    "agent-handler": {
12      "type": "stdio",
13      "command": "npx",
14      "args": [
15        "-y",
16        "mcp-remote@latest",
17        "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
18        "--header",
19        "Authorization: Bearer ${input:agent-handler-auth}"
20      ]
21    }
22  }
23}

Copy Code

FAQs on using Merge's Asana MCP server

How can I use the Asana MCP server?

Here are just a few common use cases:

Sync project milestones with marketing automation: Your agent can monitor key project milestones in Asana and automatically trigger email campaigns or update customer-facing roadmaps in tools like HubSpot or Marketo when major features are completed, keeping customers informed without manual updates

Connect design handoffs to development tracking: Your agent can detect when design tasks are marked complete in Asana, automatically create corresponding development tickets in Jira or Linear with attached Figma links and design specs, and notify the engineering team in Slack to kick off implementation

Bridge financial planning with project execution: Your agent can pull budget and resource allocation data from your ERP system (e.g., NetSuite) and compare it against actual project progress in Asana, then alert finance and project managers in Slack when projects are trending over budget or behind schedule

Balance workload across teams: Your agent can analyze task assignments and due dates across multiple Asana projects to identify team members who are over-capacity, then suggest task reassignments or flag bottlenecks to managers before deadlines are at risk

Track cross-functional project dependencies: Your agent can monitor tasks across different teams' Asana projects (e.g., product, design, engineering, marketing) and alert stakeholders when upstream dependencies are delayed, helping teams proactively adjust timelines

What are popular tools for Asana’s MCP server?

Here are some popular tools across data types:

Projects

<code class="blog_inline-code">list_projects</code>
<code class="blog_inline-code">get_project_tasks</code>
<code class="blog_inline-code">add_project_members</code>
<code class="blog_inline-code">remove_project_members</code>

Tasks

<code class="blog_inline-code">search_tasks</code>
<code class="blog_inline-code">get_task</code>
<code class="blog_inline-code">get_task_subtasks</code>
<code class="blog_inline-code">get_task_tags</code>

Teams

<code class="blog_inline-code">list_teams</code>
<code class="blog_inline-code">get_team</code>
<code class="blog_inline-code">get_team_members</code>

What makes Merge Agent Handler’s Asana MCP server better than alternative Asana MCP servers?

Merge Agent Handler provides infrastructure-level capabilities that go beyond a standalone MCP server implementation.

Here are just a few unique benefits of using Merge Agent Handler’s Asana MCP server:

Enterprise-grade security and DLP: All Asana tool inputs and outputs are scanned by a security gateway with DLP rules that can block, redact, or mask sensitive data before it reaches the agent or third-party API

Managed authentication and credential handling: Merge Agent Handler supports guided user authentication flows and manages credentials securely, removing the need for custom OAuth handling in your agent code

Real-time observability and auditability: Every Asana tool call is logged and fully-searchable, enabling teams to monitor, debug, and audit agent behavior in production

Pre-built and customizable tools: The Asana connector comes with 50+ tools out of the box, and any tool can be easily modified, whether it’s editing a name, description, or schema

Can I set custom security rules for Asana tool calls in Merge Agent Handler?

Yes, Merge Agent Handler allows you to configure custom security and DLP rules that inspect Asana tool inputs and responses. These rules can automatically block or modify tool calls based on your organization’s data governance requirements.

Here are just a few examples:

Block your agents from creating or updating Asana tasks with customer PII like email addresses or phone numbers in task names, descriptions, or comments

Automatically redact salary information or compensation details when your agents retrieve or update Asana tasks in HR or finance projects, so they only see masked versions

Monitor and log whenever your agents attempt to add sensitive financial data like revenue figures or contract values in Asana task custom fields or comments, giving leadership visibility without blocking the action

Block your agents from creating Asana projects or tasks with restricted terms like "pre-acquisition", "unannounced partnership", or embargoed product names in titles or descriptions that could expose confidential business strategy

How can I start using Merge Agent Handler’s Asana MCP server?

Here are the steps to start using Merge Agent Handler's Asana MCP server:

1. Create an Agent Handler account. You can sign up for a free Merge Agent Handler account here.

2. Set up a Tool Pack (a collection of connectors your agent can use). From the dashboard, navigate to Tool Packs, select "Create New Tool Pack," and choose the Asana connector from the list of available connectors. Give your Tool Pack a descriptive name (e.g., "Task Management Pack").

3. Add a Registered User (an identity your agent uses to execute actions). Go to the Registered Users section in the dashboard and select "Create Registered User."

You'll be asked to provide:

Origin User ID: A unique identifier from your system (e.g., a UUID)
Origin User Name: A display name (e.g., "Sarah Johnson")
(Optional) Shared Credential Group: Use this if multiple users need to share the same credentials

Agent Handler will generate a Registered User ID for use in step 4.

4. Gather your configuration details. You'll need these three items:

Tool Pack ID: Available in your Tool Pack's URL or settings page
Registered User ID: Located in the Registered Users section
API Key: Create this from your Agent Handler account settings (usually begins with "cx-")

5. Set up your IDE or AI platform. Add the MCP server configuration to your development environment (Cursor, Claude Desktop, Windsurf, VS Code, etc.) with the Tool Pack ID, Registered User ID, and API Key.

6. Confirm the connection. Launch your AI assistant or agent interface. The Asana tools should appear in your tools/context menu.

7. Begin using Asana tools. Try prompts like "Show me my Asana tasks due this week" or "Create a new Asana project called Q1 Marketing Campaign."