# How to integrate Asana MCP with Pydantic AI

```json
{
  "title": "How to integrate Asana MCP with Pydantic AI",
  "toolkit": "Asana",
  "toolkit_slug": "asana",
  "framework": "Pydantic AI",
  "framework_slug": "pydantic-ai",
  "url": "https://composio.dev/toolkits/asana/framework/pydantic-ai",
  "markdown_url": "https://composio.dev/toolkits/asana/framework/pydantic-ai.md",
  "updated_at": "2026-05-12T10:01:57.041Z"
}
```

## Introduction

This guide walks you through connecting Asana to Pydantic AI using the Composio tool router. By the end, you'll have a working Asana agent that can create a new project for q3 goals, add followers to the product launch task, attach a file to today's meeting notes task through natural language commands.
This guide will help you understand how to give your Pydantic AI agent real control over a Asana account through Composio's Asana MCP server.
Before we dive in, let's take a quick look at the key ideas and tools involved.

## Also integrate Asana with

- [ChatGPT](https://composio.dev/toolkits/asana/framework/chatgpt)
- [OpenAI Agents SDK](https://composio.dev/toolkits/asana/framework/open-ai-agents-sdk)
- [Claude Agent SDK](https://composio.dev/toolkits/asana/framework/claude-agents-sdk)
- [Claude Code](https://composio.dev/toolkits/asana/framework/claude-code)
- [Claude Cowork](https://composio.dev/toolkits/asana/framework/claude-cowork)
- [Codex](https://composio.dev/toolkits/asana/framework/codex)
- [Cursor](https://composio.dev/toolkits/asana/framework/cursor)
- [VS Code](https://composio.dev/toolkits/asana/framework/vscode)
- [OpenCode](https://composio.dev/toolkits/asana/framework/opencode)
- [OpenClaw](https://composio.dev/toolkits/asana/framework/openclaw)
- [Hermes](https://composio.dev/toolkits/asana/framework/hermes-agent)
- [CLI](https://composio.dev/toolkits/asana/framework/cli)
- [Google ADK](https://composio.dev/toolkits/asana/framework/google-adk)
- [LangChain](https://composio.dev/toolkits/asana/framework/langchain)
- [Vercel AI SDK](https://composio.dev/toolkits/asana/framework/ai-sdk)
- [Mastra AI](https://composio.dev/toolkits/asana/framework/mastra-ai)
- [LlamaIndex](https://composio.dev/toolkits/asana/framework/llama-index)
- [CrewAI](https://composio.dev/toolkits/asana/framework/crew-ai)

## TL;DR

Here's what you'll learn:
- How to set up your Composio API key and User ID
- How to create a Composio Tool Router session for Asana
- How to attach an MCP Server to a Pydantic AI agent
- How to stream responses and maintain chat history
- How to build a simple REPL-style chat interface to test your Asana workflows

## What is Pydantic AI?

Pydantic AI is a Python framework for building AI agents with strong typing and validation. It leverages Pydantic's data validation capabilities to create robust, type-safe AI applications.
Key features include:
- Type Safety: Built on Pydantic for automatic data validation
- MCP Support: Native support for Model Context Protocol servers
- Streaming: Built-in support for streaming responses
- Async First: Designed for async/await patterns

## What is the Asana MCP server, and what's possible with it?

The Asana MCP server is an implementation of the Model Context Protocol that connects your AI agent and assistants like Claude, Cursor, etc directly to your Asana account. It provides structured and secure access to your Asana workspace, so your agent can perform actions like creating tasks, managing projects, tagging work, assigning followers, and attaching files on your behalf.
- Automated task creation and updates: Let your agent create new tasks with specific details, add tasks to projects or sections, and update them as work progresses.
- Collaborator and follower management: Easily add users as followers to tasks, ensuring that the right people stay informed and engaged with project updates.
- Project and workspace organization: Create new projects, define custom fields, and set up tags to keep your Asana workspace organized and tailored to your team's workflow.
- File and attachment handling: Allow your agent to upload and attach important files directly to tasks, making sure all documentation stays in the right context.
- Goal and resource linking: Link tasks, projects, or portfolios to goals, or add supporting relationships to help your team track progress and dependencies more effectively.

## Supported Tools

| Tool slug | Name | Description |
|---|---|---|
| `ASANA_ADD_FOLLOWERS_TO_PROJECT` | Add Followers to Project | Tool to add followers to a project in Asana. Use this tool when you need to add one or more users as followers to a specific project. Followers will receive notifications when tasks are added to the project. |
| `ASANA_ADD_FOLLOWERS_TO_TASK` | 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. |
| `ASANA_ADD_ITEM_TO_PORTFOLIO` | Add item to portfolio | Add a project (or other supported item) to an Asana portfolio using the native addItem endpoint. Use when a workflow needs to attach a newly created project to a portfolio without using ASANA_SUBMIT_PARALLEL_REQUESTS. |
| `ASANA_ADD_MEMBERS_TO_PROJECT` | Add Members to Project | Tool to add users to a project in Asana. Use this tool when you need to add one or more users as members to a specific project. Members can view and contribute to the project. |
| `ASANA_ADD_PROJECT_FOR_TASK` | Add Project to Task | Tool to add a project to a task in Asana. Use when you need to associate a task with a project. Optionally position the task within the project using insert_before, insert_after, or section parameters. |
| `ASANA_ADD_SUPPORTING_RELATIONSHIP` | Add Supporting Relationship to Goal | 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. |
| `ASANA_ADD_TAG_TO_TASK` | Add Tag to Task | Tool to add an existing tag to a task in Asana. Use when you need to add a tag for prioritization, routing, or automation workflows. Tags cannot be added via Update Task, so this dedicated endpoint is required. |
| `ASANA_ADD_TASK_DEPENDENCIES` | Add Task Dependencies | Tool to add dependency relationships to an Asana task. Use when you need to mark one or more tasks as prerequisites (dependencies) for another task, ensuring the dependency tasks must be completed first. |
| `ASANA_ADD_TASK_TO_SECTION` | 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. |
| `ASANA_ADD_USER_TO_TEAM` | Add User for Team | Tool to add a user to a team in Asana. Use this when you need to add a user to a specific team by providing their user GID, email, or "me" for the current user. |
| `ASANA_ADD_USER_TO_WORKSPACE` | Add User for Workspace | Tool to add a user to a workspace or organization in Asana. Use this when you need to add a user to a specific workspace by providing their user GID, email, or "me" for the current user. |
| `ASANA_APPROVE_ACCESS_REQUEST` | Approve Access Request | Tool to approve an access request in Asana. Use when you need to grant access to a resource that requires approval workflow. |
| `ASANA_CREATE_ACCESS_REQUEST` | Create Access Request | Tool to create an access request in Asana. Use when you need to request access to a project or portfolio that you don't currently have access to. |
| `ASANA_CREATE_ALLOCATION` | 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. |
| `ASANA_CREATE_A_PROJECT` | Create a project | Creates a new Asana project in the specified workspace. Requires a `workspace` GID, and additionally a `team` GID if the workspace is an organization. |
| `ASANA_CREATE_A_TAG_IN_A_WORKSPACE` | 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 workspace, and is not automatically applied to tasks. |
| `ASANA_CREATE_A_TASK` | Create task in asana with specific details | Creates a new Asana task; requires 'workspace', 'parent', or 'projects' for association, and 'followers', 'projects', 'tags' are set only at creation. |
| `ASANA_CREATE_ATTACHMENT_FOR_OBJECT` | Create Attachment for Object | Tool to upload an attachment or link an external resource to a task, project, or project_brief in Asana. Use when you need to attach a file or external URL to any Asana object. |
| `ASANA_CREATE_ATTACHMENT_FOR_TASK` | 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. |
| `ASANA_CREATE_CUSTOM_FIELD` | 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. |
| `ASANA_CREATE_ENUM_OPTION_FOR_CUSTOM_FIELD` | 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. |
| `ASANA_CREATE_MEMBERSHIP` | Create Membership | Tool to create a membership by adding a user or team to a project, goal, or portfolio. Use when you need to grant access to an Asana resource. |
| `ASANA_CREATE_PROJECT_BRIEF` | Create Project Brief | Tool to create a project brief for a project. Use when you need to add a detailed explanation (what and why) to a project. |
| `ASANA_CREATE_PROJECT_FOR_TEAM` | Create project for team | Tool to create a project in a team. Use when you need to create a new project within a specific Asana team. |
| `ASANA_CREATE_PROJECT_FOR_WORKSPACE` | Create project for workspace | Tool to create a project in a workspace. Use when you need to create a new project within a specific Asana workspace. Note: The team field is required when creating projects in workspaces. |
| `ASANA_CREATE_PROJECT_STATUS_UPDATE` | 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. |
| `ASANA_CREATE_SECTION_IN_PROJECT` | Create a section in a project | Creates a new SECTION (not a task) in a project. Sections are organizational containers within a project used to group and categorize tasks (e.g., 'To Do', 'In Progress', 'Done', 'Backlog'). The new section can be optionally positioned relative to an existing section in the same project. IMPORTANT: This action creates SECTIONS only. Do NOT use this action to create tasks. To create a task, use the ASANA_CREATE_A_TASK action instead. Task-related fields like 'assignee', 'notes', 'due_date', 'description' are NOT supported by this action. |
| `ASANA_CREATE_STATUS_FOR_OBJECT` | Create Status Update for Object | Tool to create a status update on a project, portfolio, or goal. Use when you need to communicate progress, blockers, or current state to all followers of an object. |
| `ASANA_CREATE_SUBTASK` | 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. |
| `ASANA_CREATE_TAG` | Create a tag | Tool to create a new tag in an Asana workspace. Use when you need to create a tag for categorizing tasks. Tags help organize and filter tasks across projects but are not automatically applied to any tasks. |
| `ASANA_CREATE_TASK_COMMENT` | Create task comment | Adds a new text comment (story) to an existing Asana task, appearing in its activity feed. |
| `ASANA_CREATE_TEAM` | Create Team | Tool to create a new team in an Asana workspace. Use when you need to establish a new team for collaboration. |
| `ASANA_DELETE_ALLOCATION` | Delete Allocation | Tool to delete an allocation by its ID. Use this when you need to remove a specific resource allocation in Asana. |
| `ASANA_DELETE_ATTACHMENT` | Delete Attachment | Tool to delete an attachment by its globally unique identifier. Use when you need to remove an existing attachment from Asana. |
| `ASANA_DELETE_CUSTOM_FIELD` | 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. |
| `ASANA_DELETE_MEMBERSHIP` | Delete Membership | Tool to delete a membership by its GID. Use this when you need to remove a user or team's access to a project, portfolio, goal, or custom field in Asana. |
| `ASANA_DELETE_PROJECT` | Delete a project | Delete a project. |
| `ASANA_DELETE_PROJECT_BRIEF` | Delete Project Brief | Tool to delete a project brief by its GID. Use when you need to remove a project brief from Asana. Note: This requires the project_brief_gid (not the project_gid). |
| `ASANA_DELETE_PROJECT_STATUS` | Delete Project Status | Tool to delete a project status by its GID. Use when you need to remove a specific project status update from Asana. |
| `ASANA_DELETE_SECTION` | Delete a section | Tool to delete a section by its GID. Use when you need to permanently remove a section from a project. |
| `ASANA_DELETE_STATUS_UPDATE` | Delete Status Update | Tool to delete a status update by its GID. Use when you need to remove a specific status update from Asana. |
| `ASANA_DELETE_STORY` | Delete Story | Tool to delete a story by its GID. Use when you need to remove a story from Asana. |
| `ASANA_DELETE_TAG` | Delete a Tag | Tool to delete a specific tag by its GID. Use when you need to remove an existing tag from Asana. |
| `ASANA_DELETE_TASK` | Delete a task | Delete a task. |
| `ASANA_DUPLICATE_PROJECT` | Duplicate Project | Duplicate a project. |
| `ASANA_DUPLICATE_TASK` | Duplicate Task | Duplicate a task |
| `ASANA_GET_ACCESS_REQUESTS` | Get Access Requests | Tool to retrieve access requests for a target object. Use when you need to get pending access requests for a specific resource like a project or portfolio. |
| `ASANA_GET_ALLOCATION` | Get Allocation | Get an allocation by ID. Use when you need to retrieve the details of a specific allocation. |
| `ASANA_GET_ALLOCATIONS` | Get Allocations | Tool to get multiple allocations. Requires either 'parent' (project GID) OR both 'assignee' AND 'workspace' together. |
| `ASANA_GET_A_PROJECT` | 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. |
| `ASANA_GET_A_TASK` | Get a task | Retrieves full details for a specified task GID accessible by the user; use `opt_fields` to customize returned data. |
| `ASANA_GET_ATTACHMENT` | 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. |
| `ASANA_GET_AUDIT_LOG_EVENTS` | 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. |
| `ASANA_GET_A_USER_TASK_LIST` | 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`. |
| `ASANA_GET_CURRENT_USER` | 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. |
| `ASANA_GET_CUSTOM_FIELD` | 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. |
| `ASANA_GET_CUSTOM_FIELDS_FOR_WORKSPACE` | 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. |
| `ASANA_GET_CUSTOM_TYPES` | Get Custom Types | Tool to get all custom types associated with a project. Use when you need to retrieve custom types that extend Asana objects for categorization purposes. |
| `ASANA_GET_EVENTS` | Get Events on a Resource | 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. |
| `ASANA_GET_FAVORITES_FOR_USER` | Get Favorites for User | Tool to get a user's favorites within a specified workspace. Returns favorites ordered as they appear in the user's Asana sidebar. |
| `ASANA_GET_GOAL` | Get Goal | Retrieve the full record for a single goal by its GID. |
| `ASANA_GET_GOAL_RELATIONSHIPS` | Get Goal Relationships | Tool to retrieve goal relationships. Use when you need to get the relationships associated with a specific goal in Asana. |
| `ASANA_GET_GOALS` | Get Goals | Tool to retrieve multiple goals. Requires exactly one scope parameter (workspace, team, portfolio, or project) to be specified. Can be optionally filtered by time period or archived status. |
| `ASANA_GET_JOB` | Get Job | Tool to retrieve a job by its globally unique identifier. Use when you need to check the status of asynchronous operations like task duplication, project instantiation, or exports. |
| `ASANA_GET_MEMBERSHIP` | Get Membership | Tool to retrieve a single membership by its ID. Use this when you need to get details about a specific membership relationship between a user/team and a goal, project, portfolio, or custom field. |
| `ASANA_GET_MEMBERSHIPS` | 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. |
| `ASANA_GET_MULTIPLE_PROJECTS` | Get multiple projects | Returns a list of projects filtered by workspace or team (one required), with optional archived status filter, supporting pagination for large datasets. |
| `ASANA_GET_MULTIPLE_TASKS` | 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`. |
| `ASANA_GET_MULTIPLE_USERS` | 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. |
| `ASANA_GET_MULTIPLE_WORKSPACES` | Get multiple workspaces | Retrieves all workspaces accessible by the authenticated user, returning an empty list if the user has no accessible workspaces. |
| `ASANA_GET_PORTFOLIO` | 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. |
| `ASANA_GET_PORTFOLIO_ITEMS` | Get Portfolio Items | Retrieve items in a portfolio. Use this to get a list of projects or other portfolios contained within a specific portfolio. |
| `ASANA_GET_PORTFOLIO_MEMBERSHIPS` | 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. |
| `ASANA_GET_PORTFOLIOS` | Get Portfolios | Retrieve multiple portfolios. Use when you need to list portfolios within a specific workspace, optionally filtered by owner. |
| `ASANA_GET_PROJECT_BRIEF` | Get Project Brief | Tool to retrieve a project brief by its GID. Use when you need to get the detailed explanation (what and why) of a project. Note: Requires the project_brief_gid (not the project_gid). First call 'Get a project' with opt_fields=['project_brief'] to obtain the project_brief_gid. |
| `ASANA_GET_PROJECT_MEMBERSHIP` | Get Project Membership | Tool to get a project membership by ID. Use when you need to retrieve details of a specific project membership. |
| `ASANA_GET_PROJECT_MEMBERSHIPS` | Get Project Memberships For Project | Tool to get memberships from a specific project. Use when you need to see who has access to a project and their permission levels. |
| `ASANA_GET_PROJECTS_FOR_TASK` | Get Projects for Task | Tool to get all projects a task is in. Use when you need to retrieve project associations for a specific task. |
| `ASANA_GET_PROJECTS_FOR_TEAM` | 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. |
| `ASANA_GET_PROJECT_STATUS` | 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. |
| `ASANA_GET_PROJECT_STATUS_UPDATES` | 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. |
| `ASANA_GET_PROJECT_TEMPLATES` | Get Multiple Project Templates | Tool to retrieve multiple project templates. Use when you need to list available project templates in a workspace or team. |
| `ASANA_GET_PROJECT_TEMPLATES_FOR_TEAM` | Get Project Templates for Team | Tool to get a team's project templates in Asana. Use when you need to retrieve project templates associated with a specific team. |
| `ASANA_GET_REACTIONS_ON_OBJECT` | Get Reactions on Object | Tool to get reactions with a specific emoji base character on an object. Use when you need to retrieve user reactions (emoji responses) on a status update or story. |
| `ASANA_GET_SECTION` | 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. |
| `ASANA_GET_SECTIONS_IN_PROJECT` | Get sections in a project | Returns compact records for all sections (used to group tasks) in a specified project. |
| `ASANA_GET_STATUS` | Get Status Update | Tool to retrieve the full record for a single status update by its GID. Use when you need to get the details of a specific status update. |
| `ASANA_GET_STATUS_UPDATES` | 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. |
| `ASANA_GET_STORIES_FOR_TASK` | 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. |
| `ASANA_GET_STORY` | Get Story | Tool to retrieve a story. Use when you need to get the complete record for a single story. |
| `ASANA_GET_TAG` | 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. |
| `ASANA_GET_TAGS` | Get Tags | Get multiple tags in a workspace. |
| `ASANA_GET_TAGS_FOR_TASK` | Get Tags for Task | Tool to get all tags associated with a specific task. Use when you need to retrieve tags for categorization, filtering, or understanding task organization. |
| `ASANA_GET_TAGS_FOR_WORKSPACE` | Get Tags For Workspace | Tool to get all tags in a specific workspace. Use when you need to retrieve tags for categorizing tasks within a workspace. |
| `ASANA_GET_TASK_ATTACHMENTS` | 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. |
| `ASANA_GET_TASK_COUNTS_FOR_PROJECT` | Get Task Counts For Project | Tool to get task count statistics for a project. Use when you need to retrieve the number of tasks, completed tasks, incomplete tasks, and milestone counts for a specific Asana project. Note that all fields are excluded by default - you must specify them in opt_fields to get any data. |
| `ASANA_GET_TASKS_FOR_TAG` | Get tasks for tag | Tool to retrieve tasks associated with a specific Asana tag by tag GID. Use when you need to list all tasks that have been tagged with a particular label. |
| `ASANA_GET_TASKS_FOR_USER_TASK_LIST` | Get tasks for user task list | Tool to retrieve tasks from a user task list by user task list GID. Use when you need to list tasks assigned to a specific user's task list. |
| `ASANA_GET_TASKS_FROM_A_PROJECT` | Retrieve tasks for project | Retrieves tasks from a specified Asana project, allowing filtering by completion status and selection of optional fields for detailed responses. |
| `ASANA_GET_TASKS_FROM_SECTION` | Get tasks from a section | Tool to retrieve tasks that belong to a specific Asana section (column/header) by section GID. Use when you need to list tasks within a particular section, such as for agenda or carryover workflows. Board view only feature. |
| `ASANA_GET_TASK_SUBTASKS` | Get Task Subtasks | Tool to retrieve multiple task subtasks from a workspace. Use when you need to list or find available task subtasks. |
| `ASANA_GET_TASK_TEMPLATES` | Get Task Templates | Tool to retrieve multiple task templates from a workspace. Use when you need to list or find available task templates. |
| `ASANA_GET_TEAM` | 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. |
| `ASANA_GET_TEAM_MEMBERSHIP` | Get Team Membership | Tool to retrieve a complete team membership record by its GID. Use when you need to fetch details about a specific team membership in Asana. |
| `ASANA_GET_TEAM_MEMBERSHIPS` | 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. |
| `ASANA_GET_TEAM_MEMBERSHIPS_FOR_TEAM` | Get Team Memberships for Team | Tool to get memberships from a specific team. Use when you need to retrieve the list of users who are members of a particular team, including their membership details such as admin status and guest status. |
| `ASANA_GET_TEAM_MEMBERSHIPS_FOR_USER` | Get Team Memberships For User | Tool to get team memberships for a specific user. Use when you need to retrieve all teams that a user belongs to within a workspace. |
| `ASANA_GET_TEAMS_FOR_USER` | Get Teams for User | Tool to get teams for a specific user in an organization. Returns the team records for all teams in the organization or workspace to which the given user is assigned. |
| `ASANA_GET_TEAMS_IN_WORKSPACE` | Get teams in workspace | Returns the compact records for all teams in the workspace visible to the authorized user. |
| `ASANA_GET_TIME_PERIOD` | Get Time Period | Tool to retrieve the full record for a single time period by its GID. Use when you need to fetch detailed information about a specific time period, including its start/end dates, display name, and parent period. |
| `ASANA_GET_TIME_PERIODS` | 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 periods. |
| `ASANA_GET_TIME_TRACKING_ENTRIES` | Get Time Tracking Entries | Tool to get multiple time tracking entries across workspace, tasks, or projects. Use when you need to retrieve time tracking information for filtering by workspace, task, portfolio, user, or date range. |
| `ASANA_GET_TIME_TRACKING_ENTRIES_FOR_TASK` | Get Time Tracking Entries for Task | Tool to get time tracking entries for a task. Use when you need to retrieve time tracking information recorded on a specific task. |
| `ASANA_GET_TYPEAHEAD_OBJECTS` | Get Objects via Typeahead | 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 implementing auto-completion features. |
| `ASANA_GET_USER` | Get User | Get a user by their ID. |
| `ASANA_GET_USER_FOR_WORKSPACE` | Get User in Workspace | Tool to get a user in a workspace or organization by their GID. Use when you need to retrieve details about a specific user within a workspace context. |
| `ASANA_GET_USERS_FOR_TEAM` | Get Users for Team | Get users in a team. |
| `ASANA_GET_USERS_FOR_WORKSPACE` | Get Users in Workspace | Get users in a workspace or organization. |
| `ASANA_GET_USER_TASK_LIST` | Get User Task List | Tool to get a single user task list by its globally unique identifier. Use when you need to retrieve information about a specific user's My Tasks list. |
| `ASANA_GET_WEBHOOKS` | Get Webhooks | Tool to retrieve multiple webhooks in a workspace. Use when you need to list all webhooks for a workspace or filter webhooks by a specific resource. |
| `ASANA_GET_WORKSPACE` | 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. |
| `ASANA_GET_WORKSPACE_MEMBERSHIP` | Get Workspace Membership | Tool to retrieve a specific workspace membership by its GID. Use when you need to get details about a user's membership in a workspace. |
| `ASANA_GET_WORKSPACE_MEMBERSHIPS` | Get Workspace Memberships | Tool to retrieve the workspace memberships for a specific workspace. Use when you need to list members of a workspace. |
| `ASANA_GET_WORKSPACE_MEMBERSHIPS_FOR_USER` | Get Workspace Memberships For User | Tool to retrieve workspace memberships for a specific user. Use when you need to list all workspaces a user is a member of. |
| `ASANA_GET_WORKSPACE_PROJECTS` | 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. |
| `ASANA_INSERT_ENUM_OPTION_FOR_CUSTOM_FIELD` | Reorder Enum Option for Custom Field | Tool to reorder an existing enum option within a custom field by moving it before or after another specified enum option. Use when you need to change the order/position of options in an enum or multi_enum custom field. Note: To create new enum options, use 'Create Enum Option for Custom Field' action instead. |
| `ASANA_INSERT_SECTION_FOR_PROJECT` | Move or Insert Section in Project | Tool to move or reorder an existing section within a project by repositioning it before or after another section. Use when you need to change the position/order of sections in a project. Note: This action moves existing sections only. To create new sections, use 'Create Section in Project' action instead. |
| `ASANA_INSTANTIATE_PROJECT_TEMPLATE` | Instantiate Project Template | Instantiate (create) a real Asana project from a project template, returning the async job record. Use when you need to create a new project from a template with specific date and role assignments. |
| `ASANA_REJECT_ACCESS_REQUEST` | Reject access request | Tool to reject an access request. Use when you need to deny a user's request for access to a project or resource. |
| `ASANA_REMOVE_FOLLOWER_FROM_TASK` | 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. |
| `ASANA_REMOVE_FOLLOWERS_FOR_PROJECT` | Remove Followers For Project | Tool to remove followers from a project in Asana. Use when you need to remove one or more users as followers from a specific project. |
| `ASANA_REMOVE_ITEM_FROM_PORTFOLIO` | Remove Item from Portfolio | Tool to remove an item (e.g., a project) from an Asana portfolio. Use to undo/cleanup portfolio membership, support moves between portfolios, or enforce portfolio hygiene. |
| `ASANA_REMOVE_MEMBERS_FOR_PROJECT` | Remove Members from Project | Tool to remove users from a project in Asana. Use this tool when you need to remove one or more users as members from a specific project. |
| `ASANA_REMOVE_PROJECT_FROM_TASK` | Remove Project from Task | Tool to remove a project from a task in Asana. Use this when you need to disassociate a task from a specific project. |
| `ASANA_REMOVE_TAG_FROM_TASK` | Remove Tag from Task | Tool to remove an existing tag from a task in Asana. Use this tool when you need to detach a tag from a specific task for cleanup or retagging automation. |
| `ASANA_REMOVE_USER_FOR_TEAM` | Remove User For Team | Tool to remove a user from a team. Use when you need to revoke team membership for a specific user. |
| `ASANA_REMOVE_USER_FOR_WORKSPACE` | Remove User from Workspace | Tool to remove a user from a workspace or organization. Use when you need to revoke a user's access to a specific workspace. |
| `ASANA_SEARCH_TASKS_IN_WORKSPACE` | Search Tasks in Workspace | Tool to search tasks across a workspace with advanced filters. Use when performing complex queries such as overdue tasks, by project or custom field, for reporting or automation. |
| `ASANA_SET_PARENT_FOR_TASK` | Set parent for task | Tool to set the parent of a task in Asana. Use when you need to make a task a subtask of another task or remove the parent relationship. |
| `ASANA_SUBMIT_PARALLEL_REQUESTS` | Submit Parallel Requests (Batch API) | 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 at once. |
| `ASANA_UPDATE_ALLOCATION` | 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. |
| `ASANA_UPDATE_A_TASK` | Update a task | Updates attributes of an existing Asana task identified by its task_gid. |
| `ASANA_UPDATE_CUSTOM_FIELD` | 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. |
| `ASANA_UPDATE_ENUM_OPTION` | 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. |
| `ASANA_UPDATE_PROJECT` | Update a project | Update a project. |
| `ASANA_UPDATE_PROJECT_BRIEF` | Update Project Brief | Tool to update a project brief by its GID. Use when you need to modify the content/description of a project brief. Note: Requires the project_brief_gid (not the project_gid). First call 'Get a project' with opt_fields=['project_brief'] to obtain the project_brief_gid. |
| `ASANA_UPDATE_SECTION` | Update Section | Update a section's name or position within a project. Use when you need to rename a section or reorder sections by specifying insert_before or insert_after. |
| `ASANA_UPDATE_STORY` | Update Story | Tool to update a story on a task. Use when you need to modify the text, html_text, or pin status of an existing story. Only comment stories can have text/html_text updated, and only comment and attachment stories can be pinned. |
| `ASANA_UPDATE_TAG` | 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. |
| `ASANA_UPDATE_TEAM` | Update a team | Tool to update details of an existing team. Use when you need to change a team's name, description, or organization. |
| `ASANA_UPDATE_USER` | Update User | Update a user's custom fields. Note: Asana's API has very limited user update capabilities - most user properties are read-only and managed by users themselves. |
| `ASANA_UPDATE_USER_FOR_WORKSPACE` | Update User for Workspace | Tool to update a user in a workspace or organization. Use when you need to modify user-specific custom field values for a workspace. |
| `ASANA_UPDATE_WEBHOOK` | Update a webhook | Tool to update an existing Asana webhook's filter configuration. Use when you need to modify which events trigger webhook notifications. |

## Supported Triggers

| Trigger slug | Name | Description |
|---|---|---|
| `ASANA_TASK_ATTACHMENT_ADDED` | Attachment Added to Task | Triggers when an attachment is added to a task. |
| `ASANA_TASK_COMMENT_ADDED` | New Comment on Task | Triggers when a comment is added to a task in a project. |
| `ASANA_TASK_CREATED` | New Task Created | Triggers when a new task is created in a project. |
| `ASANA_TASK_MOVED_TO_SECTION` | Task Moved to Section | Triggers when a task is moved to a section in a project. |
| `ASANA_TASK_TAG_ADDED` | Tag Added to Task | Triggers when a tag is added to a task. Note: Asana's event structure is inverted for tag events — the resource is the task and the parent is the tag. So parent.gid gives the tag GID. |
| `ASANA_TASK_UPDATED` | Task Updated | Triggers when a task is updated in a project. |

## Creating MCP Server - Stand-alone vs Composio SDK

The Asana MCP server is an implementation of the Model Context Protocol that connects your AI agent to Asana. It provides structured and secure access so your agent can perform Asana operations on your behalf through a secure, permission-based interface.
With Composio's managed implementation, you don't have to create your own developer app. For production, if you're building an end product, we recommend using your own credentials. The managed server helps you prototype fast and go from 0-1 faster.

## Step-by-step Guide

### 1. Prerequisites

Before starting, make sure you have:
- Python 3.9 or higher
- A Composio account with an active API key
- Basic familiarity with Python and async programming

### 1. Getting API Keys for OpenAI and Composio

OpenAI API Key
- Go to the [OpenAI dashboard](https://platform.openai.com/settings/organization/api-keys) and create an API key. You'll need credits to use the models, or you can connect to another model provider.
- Keep the API key safe.
Composio API Key
- Log in to the [Composio dashboard](https://dashboard.composio.dev?utm_source=toolkits&utm_medium=framework_docs).
- Navigate to your API settings and generate a new API key.
- Store this key securely as you'll need it for authentication.

### 2. Install dependencies

Install the required libraries.
What's happening:
- composio connects your agent to external SaaS tools like Asana
- pydantic-ai lets you create structured AI agents with tool support
- python-dotenv loads your environment variables securely from a .env file
```bash
pip install composio pydantic-ai python-dotenv
```

### 3. Set up environment variables

Create a .env file in your project root.
What's happening:
- COMPOSIO_API_KEY authenticates your agent to Composio's API
- USER_ID associates your session with your account for secure tool access
- OPENAI_API_KEY to access OpenAI LLMs
```bash
COMPOSIO_API_KEY=your_composio_api_key_here
USER_ID=your_user_id_here
OPENAI_API_KEY=your_openai_api_key
```

### 4. Import dependencies

What's happening:
- We load environment variables and import required modules
- Composio manages connections to Asana
- MCPServerStreamableHTTP connects to the Asana MCP server endpoint
- Agent from Pydantic AI lets you define and run the AI assistant
```python
import asyncio
import os
from dotenv import load_dotenv
from composio import Composio
from pydantic_ai import Agent
from pydantic_ai.mcp import MCPServerStreamableHTTP

load_dotenv()
```

### 5. Create a Tool Router Session

What's happening:
- We're creating a Tool Router session that gives your agent access to Asana tools
- The create method takes the user ID and specifies which toolkits should be available
- The returned session.mcp.url is the MCP server URL that your agent will use
```python
async def main():
    api_key = os.getenv("COMPOSIO_API_KEY")
    user_id = os.getenv("USER_ID")
    if not api_key or not user_id:
        raise RuntimeError("Set COMPOSIO_API_KEY and USER_ID in your environment")

    # Create a Composio Tool Router session for Asana
    composio = Composio(api_key=api_key)
    session = composio.create(
        user_id=user_id,
        toolkits=["asana"],
    )
    url = session.mcp.url
    if not url:
        raise ValueError("Composio session did not return an MCP URL")
```

### 6. Initialize the Pydantic AI Agent

What's happening:
- The MCP client connects to the Asana endpoint
- The agent uses GPT-5 to interpret user commands and perform Asana operations
- The instructions field defines the agent's role and behavior
```python
# Attach the MCP server to a Pydantic AI Agent
asana_mcp = MCPServerStreamableHTTP(url, headers={"x-api-key": COMPOSIO_API_KEY})
agent = Agent(
    "openai:gpt-5",
    toolsets=[asana_mcp],
    instructions=(
        "You are a Asana assistant. Use Asana tools to help users "
        "with their requests. Ask clarifying questions when needed."
    ),
)
```

### 7. Build the chat interface

What's happening:
- The agent reads input from the terminal and streams its response
- Asana API calls happen automatically under the hood
- The model keeps conversation history to maintain context across turns
```python
# Simple REPL with message history
history = []
print("Chat started! Type 'exit' or 'quit' to end.\n")
print("Try asking the agent to help you with Asana.\n")

while True:
    user_input = input("You: ").strip()
    if user_input.lower() in {"exit", "quit", "bye"}:
        print("\nGoodbye!")
        break
    if not user_input:
        continue

    print("\nAgent is thinking...\n", flush=True)

    async with agent.run_stream(user_input, message_history=history) as stream_result:
        collected_text = ""
        async for chunk in stream_result.stream_output():
            text_piece = None
            if isinstance(chunk, str):
                text_piece = chunk
            elif hasattr(chunk, "delta") and isinstance(chunk.delta, str):
                text_piece = chunk.delta
            elif hasattr(chunk, "text"):
                text_piece = chunk.text
            if text_piece:
                collected_text += text_piece
        result = stream_result

    print(f"Agent: {collected_text}\n")
    history = result.all_messages()
```

### 8. Run the application

What's happening:
- The asyncio loop launches the agent and keeps it running until you exit
```python
if __name__ == "__main__":
    asyncio.run(main())
```

## Complete Code

```python
import asyncio
import os
from dotenv import load_dotenv
from composio import Composio
from pydantic_ai import Agent
from pydantic_ai.mcp import MCPServerStreamableHTTP

load_dotenv()

async def main():
    api_key = os.getenv("COMPOSIO_API_KEY")
    user_id = os.getenv("USER_ID")
    if not api_key or not user_id:
        raise RuntimeError("Set COMPOSIO_API_KEY and USER_ID in your environment")

    # Create a Composio Tool Router session for Asana
    composio = Composio(api_key=api_key)
    session = composio.create(
        user_id=user_id,
        toolkits=["asana"],
    )
    url = session.mcp.url
    if not url:
        raise ValueError("Composio session did not return an MCP URL")

    # Attach the MCP server to a Pydantic AI Agent
    asana_mcp = MCPServerStreamableHTTP(url, headers={"x-api-key": COMPOSIO_API_KEY})
    agent = Agent(
        "openai:gpt-5",
        toolsets=[asana_mcp],
        instructions=(
            "You are a Asana assistant. Use Asana tools to help users "
            "with their requests. Ask clarifying questions when needed."
        ),
    )

    # Simple REPL with message history
    history = []
    print("Chat started! Type 'exit' or 'quit' to end.\n")
    print("Try asking the agent to help you with Asana.\n")

    while True:
        user_input = input("You: ").strip()
        if user_input.lower() in {"exit", "quit", "bye"}:
            print("\nGoodbye!")
            break
        if not user_input:
            continue

        print("\nAgent is thinking...\n", flush=True)

        async with agent.run_stream(user_input, message_history=history) as stream_result:
            collected_text = ""
            async for chunk in stream_result.stream_output():
                text_piece = None
                if isinstance(chunk, str):
                    text_piece = chunk
                elif hasattr(chunk, "delta") and isinstance(chunk.delta, str):
                    text_piece = chunk.delta
                elif hasattr(chunk, "text"):
                    text_piece = chunk.text
                if text_piece:
                    collected_text += text_piece
            result = stream_result

        print(f"Agent: {collected_text}\n")
        history = result.all_messages()

if __name__ == "__main__":
    asyncio.run(main())
```

## Conclusion

You've built a Pydantic AI agent that can interact with Asana through Composio's Tool Router. With this setup, your agent can perform real Asana actions through natural language.
You can extend this further by:
- Adding other toolkits like Gmail, HubSpot, or Salesforce
- Building a web-based chat interface around this agent
- Using multiple MCP endpoints to enable cross-app workflows (for example, Gmail + Asana for workflow automation)
This architecture makes your AI agent "agent-native", able to securely use APIs in a unified, composable way without custom integrations.

## How to build Asana MCP Agent with another framework

- [ChatGPT](https://composio.dev/toolkits/asana/framework/chatgpt)
- [OpenAI Agents SDK](https://composio.dev/toolkits/asana/framework/open-ai-agents-sdk)
- [Claude Agent SDK](https://composio.dev/toolkits/asana/framework/claude-agents-sdk)
- [Claude Code](https://composio.dev/toolkits/asana/framework/claude-code)
- [Claude Cowork](https://composio.dev/toolkits/asana/framework/claude-cowork)
- [Codex](https://composio.dev/toolkits/asana/framework/codex)
- [Cursor](https://composio.dev/toolkits/asana/framework/cursor)
- [VS Code](https://composio.dev/toolkits/asana/framework/vscode)
- [OpenCode](https://composio.dev/toolkits/asana/framework/opencode)
- [OpenClaw](https://composio.dev/toolkits/asana/framework/openclaw)
- [Hermes](https://composio.dev/toolkits/asana/framework/hermes-agent)
- [CLI](https://composio.dev/toolkits/asana/framework/cli)
- [Google ADK](https://composio.dev/toolkits/asana/framework/google-adk)
- [LangChain](https://composio.dev/toolkits/asana/framework/langchain)
- [Vercel AI SDK](https://composio.dev/toolkits/asana/framework/ai-sdk)
- [Mastra AI](https://composio.dev/toolkits/asana/framework/mastra-ai)
- [LlamaIndex](https://composio.dev/toolkits/asana/framework/llama-index)
- [CrewAI](https://composio.dev/toolkits/asana/framework/crew-ai)

## Related Toolkits

- [Google Sheets](https://composio.dev/toolkits/googlesheets) - Google Sheets is a cloud-based spreadsheet tool for real-time collaboration and data analysis. It lets teams work together from anywhere, updating information instantly.
- [Notion](https://composio.dev/toolkits/notion) - Notion is a collaborative workspace for notes, docs, wikis, and tasks. It streamlines team knowledge, project tracking, and workflow customization in one place.
- [Airtable](https://composio.dev/toolkits/airtable) - Airtable combines the flexibility of spreadsheets with the power of a database for easy project and data management. Teams use Airtable to organize, track, and collaborate with custom views and automations.
- [Google Tasks](https://composio.dev/toolkits/googletasks) - Google Tasks is a to-do list and task management tool integrated into Gmail and Google Calendar. It helps you organize, track, and complete tasks across your Google ecosystem.
- [Linear](https://composio.dev/toolkits/linear) - Linear is a modern issue tracking and project planning tool for fast-moving teams. It helps streamline workflows, organize projects, and boost productivity.
- [Jira](https://composio.dev/toolkits/jira) - Jira is Atlassian’s platform for bug tracking, issue tracking, and agile project management. It helps teams organize work, prioritize tasks, and deliver projects efficiently.
- [Clickup](https://composio.dev/toolkits/clickup) - ClickUp is an all-in-one productivity platform for managing tasks, docs, goals, and team collaboration. It streamlines project workflows so teams can work smarter and stay organized in one place.
- [Monday](https://composio.dev/toolkits/monday) - Monday.com is a customizable work management platform for project planning and collaboration. It helps teams organize tasks, automate workflows, and track progress in real time.
- [Addressfinder](https://composio.dev/toolkits/addressfinder) - Addressfinder is a data quality platform for verifying addresses, emails, and phone numbers. It helps you ensure accurate customer and contact data every time.
- [Agiled](https://composio.dev/toolkits/agiled) - Agiled is an all-in-one business management platform for CRM, projects, and finance. It helps you streamline workflows, consolidate client data, and manage business processes in one place.
- [Ascora](https://composio.dev/toolkits/ascora) - Ascora is a cloud-based field service management platform for service businesses. It streamlines scheduling, invoicing, and customer operations in one place.
- [Basecamp](https://composio.dev/toolkits/basecamp) - Basecamp is a project management and team collaboration tool by 37signals. It helps teams organize tasks, share files, and communicate efficiently in one place.
- [Beeminder](https://composio.dev/toolkits/beeminder) - Beeminder is an online goal-tracking platform that uses monetary pledges to keep you motivated. Stay accountable and hit your targets with real financial incentives.
- [Boxhero](https://composio.dev/toolkits/boxhero) - Boxhero is a cloud-based inventory management platform for SMBs, offering real-time updates, barcode scanning, and team collaboration. It helps businesses streamline stock tracking and analytics for smarter inventory decisions.
- [Breathe HR](https://composio.dev/toolkits/breathehr) - Breathe HR is cloud-based HR software for SMEs to manage employee data, absences, and performance. It simplifies HR admin, making it easy to keep employee records accurate and up to date.
- [Breeze](https://composio.dev/toolkits/breeze) - Breeze is a project management platform designed to help teams plan, track, and collaborate on projects. It streamlines workflows and keeps everyone on the same page.
- [Bugherd](https://composio.dev/toolkits/bugherd) - Bugherd is a visual feedback and bug tracking tool for websites. It helps teams and clients report website issues directly on live sites for faster fixes.
- [Canny](https://composio.dev/toolkits/canny) - Canny is a platform for managing customer feedback and feature requests. It helps teams prioritize product decisions based on real user insights.
- [Chmeetings](https://composio.dev/toolkits/chmeetings) - Chmeetings is a church management platform for events, members, donations, and volunteers. It streamlines church operations and improves community engagement.
- [ClickSend](https://composio.dev/toolkits/clicksend) - ClickSend is a cloud-based SMS and email marketing platform for businesses. It streamlines communication by enabling quick message delivery and contact management.

## Frequently Asked Questions

### What are the differences in Tool Router MCP and Asana MCP?

With a standalone Asana MCP server, the agents and LLMs can only access a fixed set of Asana tools tied to that server. However, with the Composio Tool Router, agents can dynamically load tools from Asana and many other apps based on the task at hand, all through a single MCP endpoint.

### Can I use Tool Router MCP with Pydantic AI?

Yes, you can. Pydantic AI fully supports MCP integration. You get structured tool calling, message history handling, and model orchestration while Tool Router takes care of discovering and serving the right Asana tools.

### Can I manage the permissions and scopes for Asana while using Tool Router?

Yes, absolutely. You can configure which Asana scopes and actions are allowed when connecting your account to Composio. You can also bring your own OAuth credentials or API configuration so you keep full control over what the agent can do.

### How safe is my data with Composio Tool Router?

All sensitive data such as tokens, keys, and configuration is fully encrypted at rest and in transit. Composio is SOC 2 Type 2 compliant and follows strict security practices so your Asana data and credentials are handled as safely as possible.

---
[See all toolkits](https://composio.dev/toolkits) · [Composio docs](https://docs.composio.dev/llms.txt)