@tasksurf/mcp-server

Connect AI coding assistants to your team's TaskSurf workspace. Search knowledge docs, view tasks, read standups, and get team context -- all from Claude Code, Cursor, or any MCP-compatible client.

Quick Start

1. Create an API key at app.tasksurf.io/settings

2. Set your API key in your shell profile (~/.zshrc or ~/.bashrc):

   export TASKSURF_API_KEY="tsrf_..."

3. Add to your AI coding tool (see setup sections below)

Claude Code Setup

Option A: CLI command (quickest)

claude mcp add --transport stdio tasksurf -- npx @tasksurf/mcp-server

Option B: .mcp.json (shareable with your team via git)

Create .mcp.json in your project root:

{
  "mcpServers": {
    "tasksurf": {
      "type": "stdio",
      "command": "npx",
      "args": ["@tasksurf/mcp-server"],
      "env": {
        "TASKSURF_API_KEY": "${TASKSURF_API_KEY}"
      }
    }
  }
}

Commit .mcp.json to git. Each team member sets their own TASKSURF_API_KEY in their shell profile.

Cursor Setup

Add to your Cursor MCP configuration (Settings > MCP):

• Name: tasksurf
• Command: npx @tasksurf/mcp-server
• Environment: TASKSURF_API_KEY = your API key

Available Tools

| Tool | Description | |------|-------------| | search_knowledge | Search the knowledge base by query. Returns matching doc titles and IDs. | | get_knowledge_doc | Get the full content of a knowledge doc by ID. | | list_knowledge_docs | List all knowledge docs, optionally filtered by tag. | | list_tasks | List tasks with optional status, assignee, priority, and search filters. | | get_task | Get full task details: description, estimates, time tracking, status history. | | list_standups | List daily standup entries. Defaults to today. | | get_workspace_info | Get team name, member list, roles, and workspace tier. |

Resources

| Resource | Description | |----------|-------------| | tasksurf://workspace/overview | Aggregated workspace snapshot (team, active tasks, standups). Attach with @tasksurf. |

Configuration

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | TASKSURF_API_KEY | Yes | -- | Your TaskSurf API key (starts with tsrf_) | | TASKSURF_API_URL | No | https://api.tasksurf.io/v1 | API base URL (for self-hosted or testing) | | TASKSURF_TOOLS | No | all | Comma-separated tool groups: knowledge, tasks, standups, team |

CLI Flags

| Flag | Description | |------|-------------| | --api-key <key> | Override TASKSURF_API_KEY env var | | --verbose, -v | Show tool call logs with latency | | --quiet, -q | Suppress all output except fatal errors | | --version | Print version and exit |

Limiting Tools

Reduce context window usage by enabling only the tools you need:

# Only knowledge and task tools
TASKSURF_TOOLS=knowledge,tasks npx @tasksurf/mcp-server

Troubleshooting

"TASKSURF_API_KEY environment variable is not set"

Set the API key in your shell profile and restart your terminal:

echo 'export TASKSURF_API_KEY="tsrf_..."' >> ~/.zshrc
source ~/.zshrc

"API key rejected"

Your key may have been revoked or expired. Create a new key at app.tasksurf.io/settings.

"Could not connect to api.tasksurf.io"

Check your internet connection. The MCP server requires HTTPS access to the TaskSurf API.

Tools not showing up in Claude Code

1. Verify the server starts: npx @tasksurf/mcp-server --version
2. Check Claude Code MCP panel for connection errors
3. Restart Claude Code after adding the server

Debugging

Run with verbose logging to see each tool call:

npx @tasksurf/mcp-server --verbose

Use the MCP Inspector for interactive testing:

npx @modelcontextprotocol/inspector npx @tasksurf/mcp-server

Requirements

• Node.js 18 or later
• A TaskSurf account with a workspace
• An API key (create at Settings > API Keys)

License

MIT