From 088bee407058d7d352e8338a2b0ad5d155f8e9f4 Mon Sep 17 00:00:00 2001 From: Bryan Thompson <238056179+bryan-anthropic@users.noreply.github.com> Date: Thu, 6 Aug 2026 15:50:27 -0500 Subject: [PATCH] Migrate Asana plugin to V2 MCP server (#4895) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Migrate Asana plugin to V2 MCP server The V1 beta server (https://mcp.asana.com/sse) is deprecated and shuts down on 2026-08-05. Asana's V2 server (https://mcp.asana.com/v2/mcp) requires each user to register their own Asana OAuth app and does not support Dynamic Client Registration. A plugin manifest cannot carry per-user OAuth credentials, so the bundled MCP server entry is removed in favor of a documented one-time `claude mcp add` setup (per Asana's official Claude Code instructions). - Remove dead V1 sse .mcp.json - Add README with V2 OAuth setup + troubleshooting - Add /asana-setup slash command to guide the one-time setup - Update plugin + marketplace descriptions to reference V2 Co-Authored-By: Claude Opus 4.8 * plugin-dev: stop using deprecated Asana V1 SSE endpoint in examples The Asana V1 SSE server (https://mcp.asana.com/sse) is deprecated and shuts down on 2026-08-05, and Asana V2 is streamable HTTP with manual OAuth — not SSE with automatic (DCR) OAuth. Replace the Asana SSE examples in the mcp-integration skill with neutral placeholders so the tutorial no longer teaches a dead endpoint or implies Asana is a zero-config SSE/OAuth server. Co-Authored-By: Claude Opus 4.8 --------- Co-authored-by: Greg Dardis <86272347+greg-dardis@users.noreply.github.com> Co-authored-by: Claude Opus 4.8 --- .claude-plugin/marketplace.json | 2 +- .../asana/.claude-plugin/plugin.json | 2 +- external_plugins/asana/.mcp.json | 6 -- external_plugins/asana/README.md | 68 +++++++++++++++++++ .../asana/commands/asana-setup.md | 42 ++++++++++++ .../skills/mcp-integration/SKILL.md | 4 +- .../mcp-integration/examples/sse-server.json | 4 -- .../references/authentication.md | 1 - .../references/server-types.md | 5 +- 9 files changed, 116 insertions(+), 18 deletions(-) delete mode 100644 external_plugins/asana/.mcp.json create mode 100644 external_plugins/asana/README.md create mode 100644 external_plugins/asana/commands/asana-setup.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index e6161ced..49082a3b 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -258,7 +258,7 @@ }, { "name": "asana", - "description": "Asana project management integration. Create and manage tasks, search projects, update assignments, track progress, and integrate your development workflow with Asana's work management platform.", + "description": "Asana project management integration. Connects Claude Code to Asana's V2 MCP server to create and manage tasks, search projects, update assignments, and track progress. Requires a one-time Asana OAuth app setup — run /asana-setup after installing.", "category": "productivity", "source": "./external_plugins/asana", "homepage": "https://github.com/anthropics/claude-plugins-public/tree/main/external_plugins/asana" diff --git a/external_plugins/asana/.claude-plugin/plugin.json b/external_plugins/asana/.claude-plugin/plugin.json index 6ea850fb..d8be1edd 100644 --- a/external_plugins/asana/.claude-plugin/plugin.json +++ b/external_plugins/asana/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "asana", - "description": "Asana project management integration. Create and manage tasks, search projects, update assignments, track progress, and integrate your development workflow with Asana's work management platform.", + "description": "Asana project management integration. Connects Claude Code to Asana's V2 MCP server (https://mcp.asana.com/v2/mcp) to create and manage tasks, search projects, update assignments, and track progress. Requires a one-time setup of your own Asana OAuth app — run /asana-setup after installing.", "author": { "name": "Asana" } diff --git a/external_plugins/asana/.mcp.json b/external_plugins/asana/.mcp.json deleted file mode 100644 index 9a84bccf..00000000 --- a/external_plugins/asana/.mcp.json +++ /dev/null @@ -1,6 +0,0 @@ -{ - "asana": { - "type": "sse", - "url": "https://mcp.asana.com/sse" - } -} diff --git a/external_plugins/asana/README.md b/external_plugins/asana/README.md new file mode 100644 index 00000000..ed7129c0 --- /dev/null +++ b/external_plugins/asana/README.md @@ -0,0 +1,68 @@ +# Asana + +[Asana](https://asana.com) is a work management platform for tasks, projects, and goals. This plugin connects Claude Code to Asana's **V2 MCP server** so you can create and manage tasks, search projects, update assignments, and track progress directly from your terminal. + +> **Migrating from V1?** The V1 beta server (`https://mcp.asana.com/sse`) is deprecated and shuts down on **Wed 5 Aug 2026**. The V2 server requires each user to bring their own Asana OAuth app — Dynamic Client Registration is **not** supported on V2, so there is no zero-config connect. Follow the setup below (or run `/asana-setup`). + +## Setup + +You only need to do this once. The fastest path is to run **`/asana-setup`** inside Claude Code and follow the printed steps, or do it manually: + +### 1. Create an Asana OAuth app + +1. Go to the [Asana developer console](https://app.asana.com/0/my-apps). +2. Create a new app. +3. Under **OAuth**, add this exact **Redirect URL**: + + ``` + http://localhost:8080/callback + ``` + + (This is Claude Code's local OAuth callback. It is `localhost` by design — Claude Code runs on your machine and catches the authorization code on a local listener. It must match the `--callback-port` you use below.) +4. Copy your **Client ID** and **Client Secret**. + +### 2. Add the Asana V2 server to Claude Code + +Run this in your terminal (not inside a Claude prompt — the secret is entered at a hidden prompt): + +```bash +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 the Client ID from step 1. +- `--client-secret` with no value makes Claude Code prompt for the secret and store it securely in your OS keychain (never on disk). +- `--callback-port 8080` must match the port in the redirect URL you registered. + +### 3. Authenticate and verify + +1. The next time the `asana` server is used, Claude Code opens your browser for Asana consent. Approve it. +2. Confirm the connection: + + ``` + /mcp + ``` + + You should see `asana` listed as **connected**. +3. Try it: ask Claude Code to "list my Asana workspaces" or "show my assigned tasks." + +## Example usage + +Ask Claude Code to: + +- "Create an Asana task in the Backend project titled 'Fix login bug' assigned to me." +- "What are my Asana tasks due this week?" +- "Search Asana for projects about onboarding." + +## Troubleshooting + +- **`invalid_redirect_uri`** — the redirect URL in your Asana app must be exactly `http://localhost:8080/callback`, and the `--callback-port` must be `8080`. If you use a different port, register `http://localhost:/callback` to match. +- **`invalid_client`** — double-check the Client ID and re-enter the Client Secret (`claude mcp remove asana`, then re-run the add command). +- **Auth server / DCR errors** — V2 does not support Dynamic Client Registration; you must supply a pre-registered `--client-id` and `--client-secret` as shown above. + +## Documentation + +- [Integrating with Asana's MCP server](https://developers.asana.com/docs/integrating-with-asanas-mcp-server) +- [Connecting MCP clients to Asana's V2 server (Claude Code)](https://developers.asana.com/docs/connecting-mcp-clients-to-asanas-v2-server) diff --git a/external_plugins/asana/commands/asana-setup.md b/external_plugins/asana/commands/asana-setup.md new file mode 100644 index 00000000..ce0940c1 --- /dev/null +++ b/external_plugins/asana/commands/asana-setup.md @@ -0,0 +1,42 @@ +--- +description: Set up the Asana V2 MCP server connection (one-time OAuth app + claude mcp add) +argument-hint: "[client_id]" +--- + +The user wants to connect Claude Code to Asana's V2 MCP server. Guide them through the one-time setup below. Do NOT run `claude mcp add` yourself — the `--client-secret` prompt needs a real terminal (a hidden TTY prompt), so the user must run it in their own terminal. + +Their Asana OAuth Client ID (if provided): `$1` + +Print these steps clearly, substituting the Client ID into the command if `$1` is non-empty (otherwise leave the `YOUR_CLIENT_ID` placeholder): + +## Step 1 — Create an Asana OAuth app (one time) + +1. Open the Asana developer console: https://app.asana.com/0/my-apps +2. Create a new app. +3. Under **OAuth**, add this exact **Redirect URL**: + ``` + http://localhost:8080/callback + ``` +4. Copy the **Client ID** and **Client Secret**. + +Note: `localhost` is correct — Claude Code is a local client and catches the OAuth callback on your own machine. Asana's V2 server does not support Dynamic Client Registration, so you must bring your own client_id + client_secret. + +## Step 2 — Add the server (run this in YOUR terminal) + +```bash +claude mcp add --transport http \ + --client-id YOUR_CLIENT_ID --client-secret \ + --callback-port 8080 \ + asana https://mcp.asana.com/v2/mcp +``` + +- `--client-secret` (no value) triggers a hidden prompt; paste the Client Secret there. It is stored in your OS keychain. +- The port in `--callback-port` must match the `http://localhost:8080/callback` redirect you registered. + +## Step 3 — Authenticate & verify + +1. On first use, Claude Code opens your browser for Asana consent — approve it. +2. Run `/mcp` and confirm `asana` shows as **connected**. +3. Test it: ask "list my Asana workspaces". + +After printing the steps, offer to help troubleshoot if they hit `invalid_redirect_uri` (redirect/port mismatch) or `invalid_client` (wrong id/secret). diff --git a/plugins/plugin-dev/skills/mcp-integration/SKILL.md b/plugins/plugin-dev/skills/mcp-integration/SKILL.md index aee6c05e..1a77a654 100644 --- a/plugins/plugin-dev/skills/mcp-integration/SKILL.md +++ b/plugins/plugin-dev/skills/mcp-integration/SKILL.md @@ -99,9 +99,9 @@ Connect to hosted MCP servers with OAuth support. Best for cloud services. **Configuration:** ```json { - "asana": { + "hosted-service": { "type": "sse", - "url": "https://mcp.asana.com/sse" + "url": "https://mcp.example.com/sse" } } ``` diff --git a/plugins/plugin-dev/skills/mcp-integration/examples/sse-server.json b/plugins/plugin-dev/skills/mcp-integration/examples/sse-server.json index e6ec71c6..628a6937 100644 --- a/plugins/plugin-dev/skills/mcp-integration/examples/sse-server.json +++ b/plugins/plugin-dev/skills/mcp-integration/examples/sse-server.json @@ -1,9 +1,5 @@ { "_comment": "Example SSE MCP server configuration for hosted cloud services", - "asana": { - "type": "sse", - "url": "https://mcp.asana.com/sse" - }, "github": { "type": "sse", "url": "https://mcp.github.com/sse" diff --git a/plugins/plugin-dev/skills/mcp-integration/references/authentication.md b/plugins/plugin-dev/skills/mcp-integration/references/authentication.md index 1d4ff384..41aa21c4 100644 --- a/plugins/plugin-dev/skills/mcp-integration/references/authentication.md +++ b/plugins/plugin-dev/skills/mcp-integration/references/authentication.md @@ -35,7 +35,6 @@ No additional auth configuration needed! Claude Code handles everything. ### Supported Services **Known OAuth-enabled MCP servers:** -- Asana: `https://mcp.asana.com/sse` - GitHub (when available) - Google services (when available) - Custom OAuth servers diff --git a/plugins/plugin-dev/skills/mcp-integration/references/server-types.md b/plugins/plugin-dev/skills/mcp-integration/references/server-types.md index 45289533..d2e48be8 100644 --- a/plugins/plugin-dev/skills/mcp-integration/references/server-types.md +++ b/plugins/plugin-dev/skills/mcp-integration/references/server-types.md @@ -143,9 +143,9 @@ Connect to hosted MCP servers via HTTP with server-sent events for streaming. Be **OAuth (Automatic):** ```json { - "asana": { + "hosted-service": { "type": "sse", - "url": "https://mcp.asana.com/sse" + "url": "https://mcp.example.com/sse" } } ``` @@ -172,7 +172,6 @@ Claude Code handles OAuth flow: ### Use Cases **Official Services:** -- Asana: `https://mcp.asana.com/sse` - GitHub: `https://mcp.github.com/sse` - Other hosted MCP servers