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
• Access Rules
• Tool Catalog Details
• Outbound MCP: the MCP Client connector
• Troubleshooting
• Security Best Practices

Inbound vs Outbound MCP

Taskade uses MCP in two directions. Before you select an integration pattern, identify the direction.

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 tokens regularly. 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.

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 tools call Taskade APIs and can return 429 when a request reaches the current limit.

If limits occur regularly, reduce concurrency. Batch writes when an operation accepts arrays. Use x-rate-limit-reset to schedule the next request.

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.

Access Rules

The two inbound servers check access differently.

An empty hosted list_spaces response can mean that the account has no accessible workspace with MCP enabled. The local server reports access errors from the API operation it calls.

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

Tool Catalog Details

The npm-published inbound server mirrors REST API v1 and adds selected agent chat and legacy webhook subscription tools. The Workspace MCP page lists them 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 (an array of up to 20 entries)
• Each entry: contentType (text/markdown | text/plain), content (up to 2,000 characters), and placement. All three are required
• Placement: Without taskId, use afterbegin for the top of the project or beforeend for the end. With taskId, use beforebegin, afterbegin, beforeend, or afterend to place the task relative to that task

agentConvosGet / agentConvoGet

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

This server has no bundle tools. Export and import bundles through the REST API or the Action API. See Bundles & App Kits.

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 an automation. Point it at a remote MCP server. The connector tries Streamable HTTP first and falls back to SSE.

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

The MCP Client connector is shipped and ungated. It runs on every plan, including Free.

When the remote server requires a token, add the optional bearer token.

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 applies these connection rules:

• It accepts https URLs only.
• It rejects credentials embedded in the URL.
• It rejects localhost, *.localhost, *.local, and *.internal.
• It rejects loopback, private, link-local, CGNAT, unspecified, and IPv4-mapped internal IP literals.
• It rejects redirects instead of following them.
• It gives each transport 20 seconds to complete the handshake.

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