Connecting Coding Clients to Asana's V2 server

The V2 MCP server (https://mcp.asana.com/v2/mcp) requires OAuth 2.0 authentication with a registered client ID and client secret. Pre-registration provides better security and gives organizations control over which applications can access their Asana data through app management. This guide shows you how to connect different MCP clients to the V2 server.

Prerequisites

Before connecting any MCP client to Asana's V2 server, you'll need:

1. Create an Asana MCP app

Follow the guide: Integrating with Asana's MCP Server

You'll receive a client ID and client secret - keep these handy for the next step.

2. Make your app credentials available

Configure your credentials as environment variables:

1. Open your shell profile:

nano ~/.zshrc  # or ~/.bashrc for bash

2. Add these lines at the bottom (with your credentials substituted in the appropriate place):

export ASANA_CLIENT_ID="YOUR_CLIENT_ID"
export ASANA_CLIENT_SECRET="YOUR_CLIENT_SECRET"

3. Save and exit.

4. Restart your terminal and IDE for changes to take effect. You can then verify the setup by running echo $ASANA_CLIENT_ID and you should see your client ID printed.

🚧

Additional precautions:

• Use unique credentials per developer (don't share)
• Rotate credentials regularly
• Never commit your credentials to version control
• Monitor which processes can access your environment
• For production or other sensitive environments, we recommend using a secrets management tool like HashiCorp Vault, AWS Secrets Manager, or 1Password CLI

3. Configure your redirect URL

When creating your Asana MCP app, set the OAuth redirect URL in the developer console based on which client you're using:

• Most clients (Cursor, VS Code, Windsurf, Kiro, Codex): http://localhost:3334/oauth/callback
• Claude Code: http://localhost:8080/callback

The redirect URL must match exactly between your Asana app settings and your client configuration.

4. Install Node.js and npm

Most clients require Node.js and npm to run mcp-remote. Download from nodejs.org.

Verify the installation by running node --version and npm --version in your terminal.

What is mcp-remote?

mcp-remote is a community-maintained npm package that acts as a bridge between MCP clients and remote OAuth-protected servers. It handles complete OAuth flows including browser-based authorization.

🚧

mcp-remote is experimental software not officially supported by Asana. The project maintainers describe it as "a working proof-of-concept but should be considered experimental."

Use at your own risk. We provide these instructions based on current community best practices, but:

• This is not production-grade software
• Asana cannot provide support for mcp-remote issues
• Security and reliability are not guaranteed
• The tool may change or break without notice

We strongly recommend using Claude Code, which has native support for pre-configured OAuth credentials and doesn't require third-party tools.

If you choose to use mcp-remote despite these warnings:

• Review the source code yourself
• Understand you are responsible for any security or functionality issues
• Monitor the repository for updates and security advisories

Repository: github.com/jms830/mcp-remote

Claude Code

You can connect Claude Code to Asana's V2 MCP server natively thanks to its support for OAuth pre-registration.

1. Prerequisites

• Claude Code installed (download)
• An Asana MCP app created (create one)
• Your Client ID and Client secret from the Asana developer console

2. Add Asana MCP server to Claude Code

Open your terminal and run:

claude mcp add --transport http \
  --client-id YOUR_CLIENT_ID \
  --client-secret \
  --callback-port 8080 \
  asana https://mcp.asana.com/v2/mcp

• Replace YOUR_CLIENT_ID with your actual Asana Client ID.
• Wait for the prompt: After you hit Enter, Claude Code will ask you to enter you OAuth Client Secret.
• Paste your secret there. It will be hidden as you type and stored securely in your local configuration.

3. Authorize the connection

After running the command:

1. Claude Code will open your browser
2. Sign in to Asana if not already signed in
3. Review the permissions request
4. Click "Allow access"
5. You'll be redirected back to Claude Code

The browser window will close automatically and you'll see a success message in the terminal.

4. Verify the connection

Start Claude Code chat:

claude

Test the Asana connection by asking:

Show me my Asana tasks due this week

If the connection is working, Claude will use the Asana MCP tools to fetch your tasks.

Configuration details

Claude Code stores MCP server configuration in:

• User-level: ~/.claude.json
• Project-level: .mcp.json (in your project directory)

These files contain only non-sensitive configuration metadata (server URLs, transport types, client ID), not your credentials.

Your client secret will be stored securely in your system keychain.

Cursor

Cursor can connect to Asana's V2 MCP server using the mcp-remote proxy tool.

1. Prerequisites

Complete the setup prerequisites before continuing with these client-specific steps.

2. Configure Cursor

1. Open Cursor Settings: Cmd+, (Mac) or Ctrl+, (Windows/Linux)
2. Click "Cursor Settings"
3. Scroll to "Tools & MCP" section
4. Click "+ Add new global MCP server" and add the following configuration:

{
  "mcpServers": {
    "asana": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "https://mcp.asana.com/v2/mcp",
        "3334",
        "--static-oauth-client-info",
        "{\"client_id\": \"${env:ASANA_CLIENT_ID}\", \"client_secret\": \"${env:ASANA_CLIENT_SECRET}\"}"
      ],
      "env": {
        "ASANA_CLIENT_ID": "${env:ASANA_CLIENT_ID}",
        "ASANA_CLIENT_SECRET": "${env:ASANA_CLIENT_SECRET}"
      }
    }
  }
}

3. Authorize the connection

After adding the configuration above, go back to the "Cursor Settings" tab and you will see the newly added asana MCP server, then Cursor will trigger the OAuth flow:

1. Your browser will open to Asana's authorization page
2. Sign in to Asana if not already signed in
3. Review the permissions and click "Allow access"
4. You'll be redirected to localhost:3334 and the browser will show a success message
5. Return to Cursor

Authentication is now complete and tokens are stored in ~/.mcp-auth/.

4. Test the connection

Open a new agent window in Cursor code and ask about your Asana projects, for example: Show my Asana tasks due this week.

References

• Cursor MCP documentation

Codex

Codex can connect to Asana's V2 MCP server using the mcp-remote proxy tool.

1. Prerequisites

Complete the setup prerequisites before continuing with these client-specific steps.

2. Install Codex CLI

Install the Codex command-line interface globally:

npm install -g @openai/codex

Verify installation:

codex --version

3. Initialize Codex MCP

Run the Codex MCP setup command:

codex mcp

This creates the Codex configuration directory and files if they don't already exist.

4. Configure Asana MCP server

Edit the Codex configuration file:

Location: ~/.codex/config.toml

Add the following lines to configure the Asana MCP server and save the file:

[mcp_servers.asana]
command = "npx"
args = [
  "-y",
  "mcp-remote@latest",
  "https://mcp.asana.com/v2/mcp",
  "3334",
  "--static-oauth-client-info",
  "{\"client_id\": \"$ASANA_CLIENT_ID\", \"client_secret\": \"$ASANA_CLIENT_SECRET\"}",
  "--resource",
  "https://mcp.asana.com/v2"
]

env_vars = ["ASANA_CLIENT_ID", "ASANA_CLIENT_SECRET"]

Important notes:

• Codex uses TOML format (not JSON)
• The env_vars array acts as a whitelist, instructing Codex to pull these specific credentials from your environment and pass them securely to the mcp-remote process.

5. Authorize in Codex settings

1. Open Codex settings and navigate to the MCP servers section
2. You should see "Asana" listed as an available server
3. Click to connect or enable the Asana server
4. The OAuth flow will trigger automatically, your browser will open to Asana's authorization page
5. Sign in to Asana if not already signed in and review the permissions and click "Allow access"
6. You'll be redirected to localhost:3334 then return to Codex

The connection is now active and authentication is stored in ~/.mcp-auth/.

6. Test the connection

In Codex, try asking:

Create a task in my Asana project called "Documentation"

References

• Codex MCP documentation

VS Code

VS Code can connect to Asana's V2 MCP server using the mcp-remote proxy tool.

1.Prerequisites

Complete the setup prerequisites before continuing with these client-specific steps.

2. Configure VS Code MCP

1. Open Command Palette: Cmd+Shift+P (Mac) or Ctrl+Shift+P (Windows/Linux)
2. Run the MCP: Open User Configuration command
3. This will open the mcp.json file

Add the following configuration:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "asana-client-id",
      "description": "Enter your Asana MCP App Client ID",
      "password": false
    },
    {
      "type": "promptString",
      "id": "asana-client-secret",
      "description": "Enter your Asana MCP App Client Secret",
      "password": true
    }
  ],
  "servers": {
    "asana": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "https://mcp.asana.com/v2/mcp",
        "3334",
        "--static-oauth-client-info",
        "{\"client_id\": \"${input:asana-client-id}\", \"client_secret\": \"${input:asana-client-secret}\"}",
        "--resource",
        "https://mcp.asana.com/v2"
      ]
    }
  }
}

3. Authorize the connection

After saving the configuration, you'll see a "start" tooltip appear near the asanaserver, click it and VS Code will prompt you to enter your Client ID and Client secret. After entering credentials, the OAuth flow will start.

1. Sign in to Asana if not already signed in
2. Review the permissions and click "Allow access"
3. You'll be redirected to localhost:3334 and the browser will show a success message
4. Return to VS Code

Authentication is now complete and tokens are stored in ~/.mcp-auth/.

4. Test the connection

Open a new chat window in VS Code and ask about your Asana projects, for example: Show my Asana tasks due this week.

References

• VS Code MCP documentation

Windsurf

Windsurf can connect to Asana's V2 MCP server using the mcp-remote proxy tool.

1. Prerequisites

Complete the setup prerequisites before continuing with these client-specific steps.

2. Configure Windsurf MCP

1. Open Command Palette: Cmd+Shift+P (Mac) or Ctrl+Shift+P (Windows/Linux) and run the MCP Marketplace command.
2. On the MCP Marketplace, find the gear icon in right corner of the "Installed MCP" area, this will open the mcp.jsonfile, in that file add the following configuration:

{
  "mcpServers": {
    "asana": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "https://mcp.asana.com/v2/mcp",
        "3334",
        "--static-oauth-client-info",
        "{\"client_id\": \"${env:ASANA_CLIENT_ID}\", \"client_secret\": \"${env:ASANA_CLIENT_SECRET}\"}"
      ],
      "env": {
        "ASANA_CLIENT_ID": "${env:ASANA_CLIENT_ID}",
        "ASANA_CLIENT_SECRET": "${env:ASANA_CLIENT_SECRET}"
      }
    }
  }
}

3. Authorize the connection

After adding the configuration above, go back to the "MCP Marketplace" tab and you will see the newly added asana MCP server, then Windsurf will trigger the OAuth flow:

1. Your browser will open to Asana's authorization page
2. Sign in to Asana if not already signed in
3. Review the permissions and click "Allow access"
4. You'll be redirected to localhost:3334 and the browser will show a success message
5. Return to Windsurf

Authentication is now complete and tokens are stored in ~/.mcp-auth/.

4. Test the connection

Open a new Cascade sidebar chat window in Windsurf and ask about your Asana projects, for example: Show my Asana tasks due this week.

References

• Integrating with Asana's MCP Server

Kiro

Kiro can connect to Asana's V2 MCP server using the mcp-remote proxy tool.

1. Prerequisites

Complete the setup prerequisites before continuing with these client-specific steps.

2. Configure Kiro MCP

Open Command Palette: Cmd+Shift+P (Mac) or Ctrl+Shift+P (Windows/Linux) and run the Kiro: Open MCP Config command, this will open the mcp.jsonfile, in that file add the following configuration:

{
  "mcpServers": {
    "asana": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "https://mcp.asana.com/v2/mcp",
        "3334",
        "--static-oauth-client-info",
        "{\"client_id\": \"${env:ASANA_CLIENT_ID}\", \"client_secret\": \"${env:ASANA_CLIENT_SECRET}\"}"
      ],
      "env": {
        "ASANA_CLIENT_ID": "${env:ASANA_CLIENT_ID}",
        "ASANA_CLIENT_SECRET": "${env:ASANA_CLIENT_SECRET}"
      }
    }
  }
}

3. Authorize the connection

After adding the configuration above and saving it, you will see the OAuth flow triggering in the MCP Logs Output window.

1. Your browser will open to Asana's authorization page
2. Sign in to Asana if not already signed in
3. Review the permissions and click "Allow access"
4. You'll be redirected to localhost:3334 and the browser will show a success message
5. Return to Kiro

Authentication is now complete and tokens are stored in ~/.mcp-auth/.

4. Test the connection

Open a new chat session in Kiro and ask about your Asana projects, for example: Show my Asana tasks due this week.

References

• Kiro MCP documentation

V1 server deprecation

🚧

The V1 Beta MCP server https://mcp.asana.com/sse is deprecated and will shut down on 05/11/2026. Learn more and get migration steps in this changelog post

Some clients such as Replit or Jetbrains doesn't support V2 OAuth pre-registration yet, you can continue using V1 until the deprecation date.

Additional resources

• Integrating with Asana's MCP Server
• MCP Specification
• Asana API Changelog