Workspace MCP

Workspace MCP runs @taskade/mcp-server on your computer and connects your MCP client to Taskade projects, tasks, agents, and media. The local server wraps REST API v1 and adds a small set of Action API v2 tools.

Page type: How-to guide. Use it when you know the goal and need the steps.

Tip: Most readers want the hosted Taskade MCP instead. It needs no install, signs in with OAuth, and can edit Taskade Genesis app source. Not sure? See Which Taskade MCP do I want?.

Before you start

You need a token and Node.js.

What is MCP?

The Model Context Protocol lets an AI assistant call outside tools and read outside data. The @taskade/mcp-server package turns the Taskade API into MCP tools.

Your MCP client starts the server on your computer. The server calls REST API v1 with your token.

Install & run

The server is published as @taskade/mcp-server on npm. Your client runs it with npx, so you do not install it globally.

TASKADE_API_KEY="$TASKADE_TOKEN" npx -y @taskade/mcp-server

The server reads the personal access token from TASKADE_API_KEY. Settings → API also manages OAuth 2.0 clients and webhooks.

Warning: Do not commit a config file that holds a real token. The token can do everything that your account can do.

Set up your client

Each client below starts the local server for you. Replace your_api_token_placeholder with your token.

Claude Desktop

Add the server to the Claude Desktop config file, then restart Claude Desktop.

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

Claude Code

One command adds the server with its token:

claude mcp add --transport stdio taskade --env TASKADE_API_KEY=your_api_token_placeholder -- npx -y @taskade/mcp-server

Cursor

Cursor uses the same shape, in ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project):

{
  "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. The ${input:…} value asks for the token on the first run, so the file holds no secret:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "taskade_api_key",
      "description": "Taskade personal access token",
      "password": true
    }
  ],
  "servers": {
    "taskade": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@taskade/mcp-server"],
      "env": {
        "TASKADE_API_KEY": "${input:taskade_api_key}"
      }
    }
  }
}

Windsurf

Add the server to ~/.codeium/windsurf/mcp_config.json:

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

ChatGPT and other remote-only clients

ChatGPT connects only to remote MCP servers, so it cannot start this local server. Connect ChatGPT to the hosted Taskade MCP instead.

HTTP / SSE mode

The npm package runs over stdio only. An HTTP mode exists in the source code.

Note: For HTTP or SSE, clone github.com/taskade/mcp and run the HTTP entry of the server package. The server listens on http://localhost:3000. Set PORT to change the port.

Connect over SSE at http://localhost:3000/sse?access_token=your_api_token_placeholder.

Warning: Use HTTP mode only on a trusted local network or behind TLS. The token travels as a query parameter (?access_token=…).

Example Usage in Claude

After you connect, ask your client for real work. Each prompt below uses the tools in the next section.

Spin up next week's client-onboarding tasks and assign them.

Mark every overdue invoice task complete and tell me what is left.

Create a project for the Q3 launch with one task for each milestone.

Show me the tasks in my Sales Pipeline project and mark the first one complete.

Full tool reference

Every tool that the local server exposes, grouped by area. Use the names to configure exact tool calls.

The tool catalog mirrors REST API v1 and adds agent chat and legacy webhook subscription tools from Action API v2.

Note: The API v2 (beta) tools cover agent prompts, agent chat, and the legacy webhook subscriptions. For signed webhooks, use the Webhook Registration API.

Access Behavior

Workspace MCP keeps the authentication, permission, and plan rules of each API operation that it calls. It does not use the plan check of the hosted server, which admits paid workspaces only.

• The subscribeWebhook and unsubscribeWebhook tools call the legacy unsigned subscription operations.
• The signed Webhook Registration API is a separate surface. This server has no tool for it.
• If a tool returns an access error, check the requirements of that operation and the permissions of the token owner.

Set this up with your coding agent

Paste this block into your coding agent to connect it.

Start the local Taskade MCP server with "npx -y @taskade/mcp-server" over stdio. Set the environment variable TASKADE_API_KEY to a personal access token from https://www.taskade.com/settings/api. First call workspacesGet and report the workspaces you can see. Do not write anything until I confirm.

Next steps

• Workspace MCP: Advanced: token scoping, rate limits, troubleshooting, and security.
• Hosted Taskade MCP: the no-install server with OAuth and app source editing.
• REST API guide: the endpoints that these tools call.
• github.com/taskade/mcp: the source code of the server.