# Workspace MCP: Advanced This page covers what comes after the basic setup in [Workspace MCP](/apis-and-developer/workspace-mcp.md) — rate limits, running multiple clients at once, the differences between inbound and outbound MCP, troubleshooting, and security. ## Table of Contents * [Inbound vs Outbound MCP](#inbound-vs-outbound-mcp) * [Authentication & Token Scoping](#authentication--token-scoping) * [Rate Limits](#rate-limits) * [Multi-Client Setup](#multi-client-setup) * [Plan Gating](#plan-gating) * [Tool Catalog Details](#tool-catalog-details) * [MCP Connectors](#mcp-connectors) * [Troubleshooting](#troubleshooting) * [Security Best Practices](#security-best-practices) *** ## Inbound vs Outbound MCP Taskade uses MCP in two directions. Knowing which is which unlocks the right integration pattern. ```mermaid graph LR subgraph "Inbound (Taskade as MCP server)" direction TB CLIENT1[Claude Desktop] CLIENT2[Cursor] CLIENT3[Claude Code] MCP_LOCAL["@taskade/mcp-server
local stdio server"] CLIENT1 --> MCP_LOCAL CLIENT2 --> MCP_LOCAL CLIENT3 --> MCP_LOCAL MCP_LOCAL --> TASKADE_API[Taskade API] end subgraph "Outbound (Taskade agents as MCP client)" direction TB AGENT[Taskade Agent] HOSTED[MCP Connectors] EXTERNAL[Third-party
Services] AGENT --> HOSTED HOSTED --> EXTERNAL end ``` | Direction | Who uses it | Example | Covered in | | ------------------- | ---------------------------- | ----------------------------------------- | -------------------------------------------------------------------------------------- | | **Inbound** | AI tools like Claude Desktop | "Claude, list my Taskade projects" | [Workspace MCP](/apis-and-developer/workspace-mcp.md) (this page adds advanced config) | | **Outbound** | Taskade agents | Agent calls a third-party service via MCP | [MCP Connectors](#mcp-connectors) section below | | **Genesis App MCP** | Genesis app builders | Edit app source from an IDE | [Genesis App MCP (Beta)](/apis-and-developer/workspace-mcp/genesis-app-mcp.md) | *** ## 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](https://www.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, and Claude Code 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) ```json { "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. ```json { "mcpServers": { "taskade": { "command": "npx", "args": ["-y", "@taskade/mcp-server"], "env": { "TASKADE_API_KEY": "your_api_token_placeholder" } } } } ``` ### Claude Code ```bash claude mcp add taskade npx -- -y @taskade/mcp-server # Then set TASKADE_API_KEY in your shell environment ``` {% hint style="warning" %} 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. {% endhint %} *** ## 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 | — | — | — | ✓ | {% hint style="info" %} Plan features may evolve. Check the [pricing page](https://www.taskade.com/pricing) for current gating. {% endhint %} *** ## Tool Catalog Details The inbound server exposes 50+ tools whose names mirror the [REST API v1](/apis-and-developer/comprehensive-api-guide.md) operations it wraps. 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`). {% hint style="info" %} This local server wraps **v1** and therefore has **no prompt-an-agent tool**. To prompt agents programmatically, call [`POST /api/v2/promptAgent`](/apis-and-developer/api-v2-reference.md#prompt-an-agent) directly, or use the agent inside Taskade. Likewise, bundle export/import lives in the [Action API v2](/apis-and-developer/bundles.md), not in this server. {% endhint %} For the full tool list, see the [Workspace MCP](/apis-and-developer/workspace-mcp.md) 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). *** ## 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 | {% hint style="info" %} Still stuck? File an issue at [github.com/taskade/taskade/issues](https://github.com/taskade/taskade/issues) with MCP logs. {% endhint %} *** ## 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 {% content-ref url="/pages/zeVAjbnvwKEoLPhlrqWm" %} [Workspace MCP](/apis-and-developer/workspace-mcp.md) {% endcontent-ref %} {% content-ref url="/pages/rQVk4ndx1up11FhCYTXi" %} [Hosted MCP — Genesis App (Beta)](/apis-and-developer/workspace-mcp/genesis-app-mcp.md) {% endcontent-ref %} {% content-ref url="/pages/gAVvLQJwpYMggTbXn18Q" %} [Action API v2 Reference](/apis-and-developer/api-v2-reference.md) {% endcontent-ref %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.taskade.com/apis-and-developer/workspace-mcp/workspace-mcp-advanced.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.