Workspace MCP: Advanced

This page covers advanced Workspace MCP topics.

These topics include rate limits, multiple clients, MCP directions, 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. Identify the direction before you select an 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. Token creation has no scope or workspace selector.

The token can access everything that its owning account can access. Treat it as a password for the whole account.

Do not give the token to a third party as a workspace-limited credential.

For workspace boundaries, use a separate Taskade account that is only a member of that workspace. You can also use the hosted server's OAuth flow.

Token best practices

• Use one token per client or use case. This provides revocation and audit isolation.
• The last_accessed_at value shows whether a token is still in use. Separate tokens do not reduce access.
• Rotate every 90 days. Create a replacement token. Then update all client configurations.
• 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

The hosted Taskade MCP (which runs at https://www.taskade.com/mcp) accepts either OAuth 2.0 or a personal access token. The local @taskade/mcp-server inbound server uses personal tokens only.

Rate Limits

MCP requests share the Taskade API rate limit budget.

More tokens do not provide more request capacity. The budget belongs to the account, not the token.

If limits occur regularly, reduce concurrency. Batch writes because operations such as createTask accept arrays. Wait for x-rate-limit-reset.

Multi-Client Setup

You can run @taskade/mcp-server in multiple clients at the same time.

Each client starts a separate stdio process. The server isolates state by 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 .vscode/mcp.json to your workspace. VS Code uses servers, and ${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}"
      }
    }
  }
}

Do not commit configuration files that contain real tokens. Inject tokens at runtime with environment variables or a secret manager.

Plan Gating

The two servers are gated differently. Do not treat them as one entitlement.

Any account can install and connect either server. On the hosted server, list_spaces returns only the workspaces on a paid plan. An account with no paid workspace therefore sees an empty list, which is the plan gate and not a fault.

The local server's one gate is endpoint-specific, not server-wide. Below Pro, subscribeWebhook returns 402 with code: "PAYMENT_REQUIRED". Starter is below Pro for this entitlement. unsubscribeWebhook stays open on every plan, so a downgraded account can still remove its hooks.

This gate reads the plan of the account that owns the token. The hosted server checks the plan of each workspace instead. See Plan Availability for the same rule beside the full tool catalog.

Plan features can change. See the pricing page for current access details.

Tool Catalog Details

The npm-published inbound server (0.1.1) exposes 62 tools. Seven categories hold 57 tools from REST API v1.

An eighth category adds five Agent Chat & Webhooks (API v2, beta) tools, introduced in 0.1.0. The Workspace MCP page lists all 62 by name.

This section describes the tools that integrators most often configure.

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 and is on npm as of 0.1.1. 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

Outbound MCP runs through automations with the MCP Client connector.

Add the connector to a flow. Point it at a remote MCP server over Streamable HTTP, with SSE fallback.

The connector ships exactly two actions and no triggers: list the server's tools and call one tool.

Configure the authentication that the remote server requires. The connector works on every plan that can run automations.

An agent cannot reach an MCP server on its own. Production has no per-agent connector toolbox and no Space Connectors screen. The agent path is behind a feature flag that is off on every production tier.

To let an agent use a remote MCP tool, configure the agent to trigger an automation that carries the MCP Client step. The automation hands the result back.

The connector accepts only https URLs and rejects internal or loopback targets. It cannot access your private network.

See MCP Client connector for setup. See Which Taskade MCP do I want? to compare directions.

For services without MCP, use the 100+ native integrations.

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. A leak exposes every workspace the owning account can reach. Revoke the token at settings/api instead of reasoning about the blast radius.
• Isolate by account, not by token. If an integration must access one workspace, give it a dedicated Taskade account.
• Invite that account only to the required workspace. Then issue the token from that account.
• 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