How to integrate Asana MCP with Pydantic AI

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.

Asana logoAsana
Oauth2

Asana is a collaborative work management platform for teams to organize and track projects. It streamlines teamwork, boosts productivity, and keeps everyone aligned on goals.

153 Tools6 Triggers

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

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.

What is the Composio tool router, and how does it fit here?

What is Composio SDK?

Composio's Composio SDK helps agents find the right tools for a task at runtime. You can plug in multiple toolkits (like Gmail, HubSpot, and GitHub), and the agent will identify the relevant app and action to complete multi-step workflows. This can reduce token usage and improve the reliability of tool calls. Read more here: Getting started with Composio SDK

The tool router generates a secure MCP URL that your agents can access to perform actions.

How the Composio SDK works

The Composio SDK follows a three-phase workflow:

  1. Discovery: Searches for tools matching your task and returns relevant toolkits with their details.
  2. Authentication: Checks for active connections. If missing, creates an auth config and returns a connection URL via Auth Link.
  3. Execution: Executes the action using the authenticated connection.

Step-by-step Guide

Step by step09 STEPS
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
2

Getting API Keys for OpenAI and Composio

OpenAI API Key
  • Go to the OpenAI dashboard 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.
  • Navigate to your API settings and generate a new API key.
  • Store this key securely as you'll need it for authentication.
3

Install dependencies

bash
pip install composio pydantic-ai python-dotenv

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
4

Set up environment variables

bash
COMPOSIO_API_KEY=your_composio_api_key_here
USER_ID=your_user_id_here
OPENAI_API_KEY=your_openai_api_key

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
5

Import dependencies

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()
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
6

Create a Tool Router Session

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")
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
7

Initialize the Pydantic AI Agent

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."
    ),
)
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
8

Build the chat interface

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()
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
9

Run the application

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

Complete Code

Here's the complete code to get you started with Asana and Pydantic AI:

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.
TOOLS & TRIGGERS

Supported Tools and Triggers

Every Asana action and event your agent gets out of the box.

Add Followers to Project

Tool to add followers to a project in Asana.

Add Followers to Task

Tool to add followers to a task in Asana.

Add item to portfolio

Add a project (or other supported item) to an Asana portfolio using the native addItem endpoint.

Add Members to Project

Tool to add users to a project in Asana.

Add Project to Task

Tool to add a project to a task in Asana.

Add Supporting Relationship to Goal

Tool to add a supporting goal relationship to a goal.

Add Tag to Task

Tool to add an existing tag to a task in Asana.

Add Task Dependencies

Tool to add dependency relationships to an Asana task.

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.

Add User for Team

Tool to add a user to a team in Asana.

Add User for Workspace

Tool to add a user to a workspace or organization in Asana.

Approve Access Request

Tool to approve an access request in Asana.

Create Access Request

Tool to create an access request in Asana.

Create Allocation

Creates a new allocation.

Create a project

Creates a new Asana project in the specified 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.

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.

Create Attachment for Object

Tool to upload an attachment or link an external resource to a task, project, or project_brief in Asana.

Create Attachment for Task

Tool to upload an attachment to a task.

Create Custom Field

Tool to create a new custom field in a workspace.

Create Enum Option for Custom Field

Tool to create a new enum option for a custom field in Asana.

Create Membership

Tool to create a membership by adding a user or team to a project, goal, or portfolio.

Create Project Brief

Tool to create a project brief for a project.

Create project for team

Tool to create a project in a team.

Create project for workspace

Tool to create a project in a workspace.

Create Project Status Update

Tool to create a new status update on a project.

Create a section in a project

Creates a new SECTION (not a task) in a project.

Create Status Update for Object

Tool to create a status update on a project, portfolio, or goal.

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.

Create a tag

Tool to create a new tag in an Asana workspace.

Create task comment

Adds a new text comment (story) to an existing Asana task, appearing in its activity feed.

Create Team

Tool to create a new team in an Asana workspace.

Delete Allocation

Tool to delete an allocation by its ID.

Delete Attachment

Tool to delete an attachment by its globally unique identifier.

Delete Custom Field

Tool to delete a custom field by its globally unique identifier.

Delete Membership

Tool to delete a membership by its GID.

Delete a project

Delete a project.

Delete Project Brief

Tool to delete a project brief by its GID.

Delete Project Status

Tool to delete a project status by its GID.

Delete a section

Tool to delete a section by its GID.

Delete Status Update

Tool to delete a status update by its GID.

Delete Story

Tool to delete a story by its GID.

Delete a Tag

Tool to delete a specific tag by its GID.

Delete a task

Delete a task.

Duplicate Project

Duplicate a project.

Duplicate Task

Duplicate a task

Get Access Requests

Tool to retrieve access requests for a target object.

Get Allocation

Get an allocation by ID.

Get Allocations

Tool to get multiple allocations.

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.

Get a task

Retrieves full details for a specified task GID accessible by the user; use `opt_fields` to customize returned data.

Get Attachment

Tool to get a single attachment by its globally unique identifier.

Get Audit Log Events

Tool to get audit log events for a workspace.

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`.

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.

Get Custom Field

Tool to get a single custom field by its globally unique identifier.

Get Custom Fields for Workspace

Tool to get all custom fields in a workspace.

Get Custom Types

Tool to get all custom types associated with a project.

Get Events on a Resource

Retrieve events on a resource to monitor changes.

Get Favorites for User

Tool to get a user's favorites within a specified workspace.

Get Goal

Retrieve the full record for a single goal by its GID.

Get Goal Relationships

Tool to retrieve goal relationships.

Get Goals

Tool to retrieve multiple goals.

Get Job

Tool to retrieve a job by its globally unique identifier.

Get Membership

Tool to retrieve a single membership by its ID.

Get Memberships

Tool to retrieve memberships for goals, projects, portfolios, or custom fields.

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.

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`.

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.

Get multiple workspaces

Retrieves all workspaces accessible by the authenticated user, returning an empty list if the user has no accessible workspaces.

Get Portfolio

Retrieve the full record for a single portfolio by its GID.

Get Portfolio Items

Retrieve items in a portfolio.

Get Portfolio Memberships

Tool to retrieve multiple portfolio memberships.

Get Portfolios

Retrieve multiple portfolios.

Get Project Brief

Tool to retrieve a project brief by its GID.

Get Project Membership

Tool to get a project membership by ID.

Get Project Memberships For Project

Tool to get memberships from a specific project.

Get Projects for Task

Tool to get all projects a task is in.

Get Projects for Team

Tool to get a list of projects for a specific team in Asana.

Get Project Status

Tool to retrieve the full record for a single project status by its GID.

Get Project Status Updates

Tool to get status updates for a specific project.

Get Multiple Project Templates

Tool to retrieve multiple project templates.

Get Project Templates for Team

Tool to get a team's project templates in Asana.

Get Reactions on Object

Tool to get reactions with a specific emoji base character on an object.

Get Section

Retrieve the full record for a single section by its GID.

Get sections in a project

Returns compact records for all sections (used to group tasks) in a specified project.

Get Status Update

Tool to retrieve the full record for a single status update by its GID.

Get Status Updates

Retrieve status updates from an object.

Get Stories for Task

Tool to get stories (comments, status updates, etc.

Get Story

Tool to retrieve a story.

Get Tag

Tool to get a single tag by its globally unique identifier.

Get Tags

Get multiple tags in a workspace.

Get Tags for Task

Tool to get all tags associated with a specific task.

Get Tags For Workspace

Tool to get all tags in a specific workspace.

Get Task Attachments

Tool to get the list of attachments for a given task, project, or project_brief.

Get Task Counts For Project

Tool to get task count statistics for a project.

Get tasks for tag

Tool to retrieve tasks associated with a specific Asana tag by tag GID.

Get tasks for user task list

Tool to retrieve tasks from a user task list by user task list GID.

Retrieve tasks for project

Retrieves tasks from a specified Asana project, allowing filtering by completion status and selection of optional fields for detailed responses.

Get tasks from a section

Tool to retrieve tasks that belong to a specific Asana section (column/header) by section GID.

Get Task Subtasks

Tool to retrieve multiple task subtasks from a workspace.

Get Task Templates

Tool to retrieve multiple task templates from a workspace.

Get Team

Tool to retrieve details of a specific team by its GID.

Get Team Membership

Tool to retrieve a complete team membership record by its GID.

Get Team Memberships

Tool to retrieve compact team membership records.

Get Team Memberships for Team

Tool to get memberships from a specific team.

Get Team Memberships For User

Tool to get team memberships for a specific user.

Get Teams for User

Tool to get teams for a specific user in an organization.

Get teams in workspace

Returns the compact records for all teams in the workspace visible to the authorized user.

Get Time Period

Tool to retrieve the full record for a single time period by its GID.

Get Time Periods

Tool to retrieve compact or full representations of time periods.

Get Time Tracking Entries

Tool to get multiple time tracking entries across workspace, tasks, or projects.

Get Time Tracking Entries for Task

Tool to get time tracking entries for a task.

Get Objects via Typeahead

Tool to retrieve objects in a workspace via a typeahead search algorithm.

Get User

Get a user by their ID.

Get User in Workspace

Tool to get a user in a workspace or organization by their GID.

Get Users for Team

Get users in a team.

Get Users in Workspace

Get users in a workspace or organization.

Get User Task List

Tool to get a single user task list by its globally unique identifier.

Get Webhooks

Tool to retrieve multiple webhooks in a workspace.

Get Workspace

Tool to retrieve details of a specific workspace by its GID.

Get Workspace Membership

Tool to retrieve a specific workspace membership by its GID.

Get Workspace Memberships

Tool to retrieve the workspace memberships for a specific workspace.

Get Workspace Memberships For User

Tool to retrieve workspace memberships for a specific user.

Get Workspace Projects

Tool to retrieve the projects associated with a specific workspace.

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.

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.

Instantiate Project Template

Instantiate (create) a real Asana project from a project template, returning the async job record.

Reject access request

Tool to reject an access request.

Remove Follower From Task

Tool to remove one or more followers from a task.

Remove Followers For Project

Tool to remove followers from a project in Asana.

Remove Item from Portfolio

Tool to remove an item (e.

Remove Members from Project

Tool to remove users from a project in Asana.

Remove Project from Task

Tool to remove a project from a task in Asana.

Remove Tag from Task

Tool to remove an existing tag from a task in Asana.

Remove User For Team

Tool to remove a user from a team.

Remove User from Workspace

Tool to remove a user from a workspace or organization.

Search Tasks in Workspace

Tool to search tasks across a workspace with advanced filters.

Set parent for task

Tool to set the parent of a task in Asana.

Submit Parallel Requests (Batch API)

Tool to submit multiple Asana API requests in parallel using the Batch API.

Update Allocation

Tool to update an existing allocation by its ID.

Update a task

Updates attributes of an existing Asana task identified by its task_gid.

Update Custom Field

Tool to update a custom field by its globally unique identifier.

Update Enum Option

Tool to update an enum option for a custom field.

Update a project

Update a project.

Update Project Brief

Tool to update a project brief by its GID.

Update Section

Update a section's name or position within a project.

Update Story

Tool to update a story on a task.

Update Tag

Tool to update an existing tag by its globally unique identifier.

Update a team

Tool to update details of an existing team.

Update User

Update a user's custom fields.

Update User for Workspace

Tool to update a user in a workspace or organization.

Update a webhook

Tool to update an existing Asana webhook's filter configuration.

FAQ

Frequently asked questions

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.

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.

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.

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.

Start with Asana.It takes 30 seconds.

Managed auth, hosted MCP servers, and every Asana tool your agent needs.Free to start.

Start building