Workspace MCP: Advanced

This page covers what comes after the basic setup in Workspace MCP — rate limits, running multiple clients at once, the differences between inbound and outbound MCP, troubleshooting, and security.

Table of Contents

• Inbound vs Outbound MCP
• Authentication & Token Scoping
• Rate Limits
• Multi-Client Setup
• Plan Gating
• Tool Catalog Details
• Outbound MCP: the MCP Client connector
• Troubleshooting
• Security Best Practices

Inbound vs Outbound MCP

Taskade uses MCP in two directions. Knowing which is which unlocks the right integration pattern.

Authentication & Token Scoping

The inbound MCP server (@taskade/mcp-server) authenticates with a Personal Access Token via the TASKADE_API_KEY environment variable.

A personal access token is account-wide, not workspace-scoped. There is no scope
or workspace selector when you create one: the token can reach everything its owning
account can reach, in every workspace that account belongs to. Treat it as a password
for the whole account, and never hand one to a third party expecting it to be confined
to one workspace. If you need per-workspace boundaries, use a separate Taskade account
that is only a member of that workspace — or the hosted server's OAuth flow.

Token best practices

• One token per client or use case. This buys you revocation and audit isolation — you can kill the token a single integration uses, and last_accessed_at tells you whether it is still in use — but it does not reduce what that token can reach.
• Rotate every 90 days. Regenerate and update all client configs.
• Never commit tokens to version control or share them in chat.
• Revoke unused tokens from taskade.com/settings/api. You can hold at most 5 at a time.

OAuth availability

OAuth 2.0 is available for the hosted Taskade MCP (which runs at https://www.taskade.com/mcp). The local @taskade/mcp-server inbound server currently uses personal tokens only.

Rate Limits

MCP requests share the Taskade API rate limit budget.

Issuing more tokens does not buy more budget. The budget is keyed to the account (and, at the edge, to your IP) — not to the token — so every token you own draws from the same bucket. If you hit limits regularly, reduce concurrency, batch writes (operations like createTask accept arrays), and back off from the x-rate-limit-reset header.

Multi-Client Setup

You can safely run @taskade/mcp-server on Claude Desktop, Cursor, Claude Code, Windsurf, VS Code, and other clients at the same time. Each client spawns its own stdio process — state is isolated server-side per token.

Claude Desktop

File: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)

{
  "mcpServers": {
    "taskade": {
      "command": "npx",
      "args": ["-y", "@taskade/mcp-server"],
      "env": {
        "TASKADE_API_KEY": "your_api_token_placeholder"
      }
    }
  }
}

Cursor

File: .cursor/mcp.json in your project root.

{
  "mcpServers": {
    "taskade": {
      "command": "npx",
      "args": ["-y", "@taskade/mcp-server"],
      "env": {
        "TASKADE_API_KEY": "your_api_token_placeholder"
      }
    }
  }
}

Claude Code

claude mcp add taskade npx -- -y @taskade/mcp-server
# Then set TASKADE_API_KEY in your shell environment

Windsurf

File: ~/.codeium/windsurf/mcp_config.json (or Settings → Cascade → MCP → Add Server):

{
  "mcpServers": {
    "taskade": {
      "command": "npx",
      "args": ["-y", "@taskade/mcp-server"],
      "env": {
        "TASKADE_API_KEY": "your_api_token_placeholder"
      }
    }
  }
}

VS Code

Add a .vscode/mcp.json to your workspace (VS Code uses the servers key; ${input:…} prompts for your key on first run):

{
  "servers": {
    "taskade": {
      "command": "npx",
      "args": ["-y", "@taskade/mcp-server"],
      "env": {
        "TASKADE_API_KEY": "${input:taskade_api_key}"
      }
    }
  }
}

Avoid committing these config files to public repos with real tokens. Many teams use environment variable substitution (shell-level) or a secret manager to inject the token at runtime.

Plan Gating

MCP access is included on all paid Taskade plans. Free-plan users can install and connect either server, but workspace-scoped access (listing your workspaces, hosted-MCP tools) requires an active paid subscription.

Plan features may evolve. Check the pricing page for current gating.

Tool Catalog Details

The npm-published inbound server (0.0.2) exposes 57 tools across 7 categories mirroring the REST API v1 operations it wraps; the 0.1.0 source release (latest tag 0.1.1, on GitHub) adds a five-tool Agent Chat & Webhooks (API v2, beta) group (promptAgent, listConversations, getConversation, subscribeWebhook, unsubscribeWebhook). Below are the ones integrators most often need to configure precisely.

projectTasksGet

• Required args: projectId
• Optional args: limit (default 100), after, before
• Pagination: Cursor-based — pass the last task id as after to page forward.

taskCreate

• Required args: projectId, tasks (array of { contentType, content })
• Optional args: placement (afterbegin | beforeend)

agentConvosGet / agentConvoGet

• agentConvosGet lists an agent's conversations (agentId, optional limit, page).
• agentConvoGet returns one conversation (agentId, convoId).

The API v2 (beta) layer (prompt-an-agent promptAgent, agent-chat, webhook subscribe/unsubscribe) ships in v0.1.0 (latest source release v0.1.1) — currently from source on GitHub while the npm release catches up. Note: bundle export/import still lives in the Action API v2, not in this server.

For the full tool list, see the Workspace MCP reference.

Outbound MCP: the MCP Client connector

The outbound direction — Taskade acting as the MCP client — runs through automations, using the MCP Client connector. Add it as a step in a flow, point it at any remote MCP server over Streamable HTTP (with SSE fallback), and you get two actions: list its tools and call a tool. Authentication is whatever the remote server expects, configured on the step. It works on every plan that can run automations, and there is nothing to host.

An agent cannot reach an MCP server on its own. There is no per-agent connector toolbox and no Space Connectors screen in production — if you want an agent to use a remote MCP tool, have it trigger an automation that carries the MCP Client step and hand back the result.

The connector only accepts https URLs and rejects internal/loopback targets, so it cannot be pointed at your private network. See MCP Client connector for setup steps, and Which Taskade MCP do I want? for how the directions compare. For services that don't speak MCP, the 100+ native integrations are the shorter path.

Troubleshooting

Still stuck? File an issue at github.com/taskade/taskade/issues with MCP logs.

Security Best Practices

• Audit tool exposure for public agents. Opt sensitive tools (file access, automation triggers) out of public agent configurations.
• Assume a leaked token is a full account compromise. Personal access tokens carry no workspace or resource scope, so a leak exposes every workspace the owning account can reach — revoke it immediately at settings/api rather than reasoning about blast radius.
• Isolate by account, not by token. If an integration must only see one workspace, give it its own Taskade account invited to just that workspace, and issue the token there.
• Rotate on every personnel change. When a teammate leaves, rotate any shared tokens.
• Monitor the workspace activity log for unexpected MCP-initiated actions.
• The hosted Taskade MCP is always served over TLS at https://www.taskade.com/mcp.

Related

→ Workspace MCP

→ Hosted Taskade MCP

→ Action API Guide