Workspace MCP: Advanced

Rate limits, multi-client setup, troubleshooting, and security guidance for running the Taskade Workspace MCP server in production.

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

• MCP Connectors

• Troubleshooting

• Security Best Practices

---

Inbound vs Outbound MCP

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

Direction	Who uses it	Example	Covered in
Inbound	AI tools like Claude Desktop	"Claude, list my Taskade projects"	Workspace MCP (this page adds advanced config)
Outbound	Taskade agents	Agent calls a third-party service via MCP	MCP Connectors section below
Taskade Genesis App MCP	Genesis app builders	Edit app source from an IDE	Genesis App MCP (Beta)

---

Authentication & Token Scoping

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

Token best practices

• Scope narrowly. Create a dedicated token per workspace or per use case rather than reusing one token everywhere.

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

OAuth availability

OAuth 2.0 is available for the Genesis App MCP (which runs hosted at a URL). The local @taskade/mcp-server inbound server currently uses personal tokens only.

---

Rate Limits

MCP requests share the Taskade API rate limit budget.

Symptom	Cause	Fix
Tool call returns 429	Rate limit exceeded	Implement backoff in your client wrapper
Multiple tools failing simultaneously	Token-wide rate limit exhausted	Reduce concurrency; split tokens
Slow tool response	Upstream model slowness	Check model pricing tier; auto-mode routes dynamically

If you hit limits regularly, split your integration across multiple scoped tokens so each has its own budget.

---

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

Feature	Free	Pro	Business	Max / Enterprise
Inbound MCP (@taskade/mcp-server)	Limited	Limited	Full	Full
MCP Connectors (outbound)	—	—	✓	✓
Taskade-as-MCP-server (external clients read workspace)	—	—	✓	✓
Custom domain for MCP	—	—	—	✓

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

---

Tool Catalog Details

The inbound server exposes 62 tools across 8 categories. Most mirror the REST API v1 operations it wraps; the newest category is a small 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).

This server now bundles a small API v2 (beta) layer (prompt-an-agent promptAgent, agent-chat, webhook subscribe/unsubscribe) on top of the v1 surface. 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.

---

MCP Connectors

MCP Connectors let your Taskade agents connect outbound to third-party services. You browse and enable connectors from the Integrations screen in your workspace — no code, no hosting.

Agents see enabled connectors as tools. You can opt specific tools out per agent (especially useful for public-facing agents). See MCP Connectors for the full catalog and setup steps.

---

Troubleshooting

Symptom	Likely cause	Fix
"Connection refused" in Claude Desktop	MCP process crashed	Restart Claude Desktop; check ~/Library/Logs/Claude/
"Unauthorized" on every tool	Token invalid or rotated	Regenerate token; update all client configs
"Workspace not found"	Token scoped to wrong workspace	Create a token in the right workspace
Tools appear but return 429	Rate limited	Back off; consider splitting tokens
Agent invisible in shared workspace	Permission issue (fixed v6.114.1)	Update to latest @taskade/mcp-server
OAuth loop (Genesis App MCP)	Expired refresh token	Re-authenticate in the client
Tool timeout	Large response or slow upstream	Check upstream; reduce query scope

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.

• Use per-workspace tokens. A leaked personal token is bounded to one workspace if scoped correctly.

• Rotate on every personnel change. When a teammate leaves, rotate any shared tokens.

• Monitor the workspace activity log for unexpected MCP-initiated actions.

• Use TLS / custom domain for Genesis App MCP in production.

---

Related

Workspace MCPHosted MCP — Genesis App (Beta)Action API v2 Reference