Asana MCP V2 Setup: OAuth Registration and Workspace Access
Use Asana's V2 MCP endpoint with OAuth, verify that your client has the required app registration, and check one known project before permitting task changes. Most setup failures become easier to diagnose once you separate registration, workspace distribution, and user permissions.
Use Asana's V2 MCP endpoint with OAuth, verify that your client has the required app registration, and check one known project before permitting task changes. Most setup failures become easier to diagnose once you separate registration, workspace distribution, and user permissions.
Table of contents
- Which Asana endpoint should you use?
- When do you need an OAuth app?
- How do you connect VS Code?
- How do you verify workspace and task access?
- How do you fix authorization failures?
- How do you control the first write?
Which Asana endpoint should you use?
Use https://mcp.asana.com/v2/mcp with a client that supports Streamable HTTP and OAuth. Asana's documentation identifies this as the V2 server. Older instructions using the beta /sse address should not be your starting point for a new connection. Source: Asana MCP overview.
Decide which client you are configuring before following a tutorial. A managed Asana connector can handle registration details that a coding client asks you to supply. That difference explains why a coworker may connect through a button while your editor requests a client ID.
Use the Asana server listing to identify the official service, then follow the current vendor guide for your client. This article uses VS Code as a concrete path because its registration and callback requirements can be checked explicitly.
Our recommendation is to resolve authorization before experimenting with task automation. Start with one workspace and one known project. A connection that can read the wrong workspace is not a successful setup, even if it returns plausible tasks and no error.
When do you need an OAuth app?
You need a pre-registered MCP application when your client does not supply a managed integration. Asana V2 does not support dynamic client registration. Its developer integration flow provides a client ID and secret, callback configuration, and workspace distribution settings. Source: integration guide.
Prepare the registration as a separate step:
- Open the Asana developer console and create the appropriate MCP app.
- Configure the callback addresses required by your chosen client.
- Select the workspaces allowed to use the app.
- Store its client secret in the client's supported secure credential flow.
- Keep a record of the app owner and intended use, without copying secrets into shared notes.
Do not confuse a client secret with a user's access token. The application identifies the integration; the browser authorization flow establishes which user's access it receives. Asana's OAuth documentation explains the authorization and token exchange involved.
Use an individually attributable registration where your team's policy requires it. Sharing a secret through chat makes later revocation and debugging harder: nobody can tell which machine still has the old value. Keep credentials out of source control and avoid embedding them in commands that will be copied into tickets.
How do you connect VS Code?
Register both documented VS Code callback URLs, add the V2 server using HTTP transport, and enter client credentials through the OAuth setup prompts. The callback addresses documented by Asana are:
http://127.0.0.1:33418/
https://vscode.dev/redirect
The trailing slash on the loopback URL matters. Copy both values exactly into your app registration. Then open VS Code's Command Palette, choose MCP: Add Server, select HTTP, enter https://mcp.asana.com/v2/mcp, and name the connection asana. Supply the registered client ID and secret when prompted, then complete the browser authorization. Source: coding-client instructions.
When you return to VS Code, confirm the server is enabled in the workspace where you intend to use it. A global entry and a workspace entry can coexist, so inspect which one the active conversation is using before adding another duplicate.
For a different editor, use its own instructions rather than transplanting this callback pair. The Cursor guide can help locate Cursor's configuration, but Asana's client-specific OAuth directions determine the authentication fields. Config Validator checks JSON structure; it cannot validate registered callbacks or authorize a workspace.
How do you verify workspace and task access?
Ask for one known project and one known task, then compare the identifiers with Asana itself. Begin with reads and require the assistant to name the workspace it searched. This is more useful than a broad “show my work” prompt that can combine unrelated teams.
Use a request such as: “Find the project named MCP Connection Check in the workspace I specify. Show its identifier and one existing task's title, identifier, and completion state. Do not create, assign, update, or complete tasks.” Prepare that project yourself so the expected answer is known.
Asana recommends retrieving the current tools and parameters through tools/list, rather than relying on an old hardcoded inventory. Source: MCP overview.
| Check | Evidence you want | What failure suggests |
|---|---|---|
| Correct workspace | Expected name and identifier | Account or distribution mismatch |
| Known project | Exact project identifier | User access or query scope |
| Known task | Matching title and status | Filters, permissions, or wrong target |
| No mutations | No proposed write executed | Approval controls need attention |
A missing task is not automatically an authorization error. Ask which filters were applied before widening access or replacing credentials.
How do you fix authorization failures?
Start with the exact failure: callback mismatch, unavailable workspace, invalid scope, or expired authentication. Each points to a different configuration boundary. Recreating the entire app should be a last step after you have identified which boundary failed.
For callback errors, compare the actual redirect with the registered value character for character. For an unavailable workspace, inspect app distribution and whether the intended workspace was selected. For a stale session, reconnect through the client rather than pasting an access token into a permanent file.
Asana documents access tokens with a one-hour lifetime and a refresh flow; it also states that MCP app tokens are not ordinary Asana API tokens. Source: integration guide. A tool working initially and failing later therefore calls for checking refresh behavior, not assuming the user's project was deleted.
The OAuth reference is the place to check authorization flow details. Preserve a sanitized error message, client version, callback URL, and timestamp when escalating a problem. Never include the secret or token in that record.
If the client rejects the configuration before opening a browser, use Config Doctor to check the client-side structure first. Authentication cannot repair malformed JSON.
How do you control the first write?
Create one temporary task in the verified project only after reviewing the proposed fields. Name the project identifier, title, assignee, and due-date behavior explicitly. Avoid starting with bulk reassignment or schedule changes, because a wrong workspace can turn a simple test into a team-wide interruption.
Ask the assistant to show its planned operation, then approve that single action. Open the created task in Asana and compare the fields. Clean up only that test item after verification; do not ask for a broad “remove all test tasks” action when you have one known identifier.
Asana's permission model follows the authorizing user's access, and client app management can block an integration. Source: access management. A prompt saying “read only” should therefore be treated as a workflow instruction, not a guarantee that the token has lost write authority.
For everyday use, separate reporting from execution. Generate a proposed task list first, check ownership and dates, and then approve a small batch. This keeps the connection useful while preserving the distinction between the assistant understanding your request and your team accepting the consequences.