@koderlabs/tasks-mcp

MCP server for InstantTasks — project management for AI-augmented teams. Lets MCP-aware agents (Claude Desktop, Claude Code, Cursor, VS Code, Windsurf) discover, triage, write, and ship work from inside the chat surface.

Requirements

• Node.js 18+
• An InstantTasks account at tasks.koderlabs.net
• An MCP-compatible client (Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, …)

Standard config (hosted, OAuth)

{
  "mcpServers": {
    "instanttasks": {
      "url": "https://tasks.koderlabs.net/mcp"
    }
  }
}

The MCP server runs at https://tasks.koderlabs.net/mcp. The first tool call opens a browser tab; sign in (or skip if already signed in) and click Allow access. The token is bound to your active organization — no API key in config files.

Install in your client

claude mcp add --transport http instanttasks https://tasks.koderlabs.net/mcp

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "instanttasks": {
      "url": "https://tasks.koderlabs.net/mcp"
    }
  }
}

Restart Claude Desktop. First tool call triggers OAuth.

Click the button to install:

Or install manually:

Settings → MCP Servers → Add Server

• Name: instanttasks
• Transport: HTTP
• URL: https://tasks.koderlabs.net/mcp

Click the button to install:

Or install manually:

code --add-mcp '{"name":"instanttasks","url":"https://tasks.koderlabs.net/mcp"}'

Edit ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "instanttasks": {
      "serverUrl": "https://tasks.koderlabs.net/mcp"
    }
  }
}

When the OAuth browser flow is not available (CI runners, container agents, automated scripts) use the stdio transport with a management key. Mint one under Project Settings → SDK Keys.

claude mcp add instanttasks-local \
  -e IT_API_BASE_URL=https://tasks.koderlabs.net/api/v1 \
  -e IT_SECRET_KEY=sk_live_<your management key> \
  -- npx -y @koderlabs/tasks-mcp

Or as raw JSON:

{
  "mcpServers": {
    "instanttasks": {
      "command": "npx",
      "args": ["-y", "@koderlabs/tasks-mcp"],
      "env": {
        "IT_API_BASE_URL": "https://tasks.koderlabs.net/api/v1",
        "IT_SECRET_KEY": "sk_live_<your management key>"
      }
    }
  }
}

Getting started

1. Sign up at tasks.koderlabs.net
2. Add the MCP server with one of the snippets above
3. Call the help tool — it lists every tool grouped by skill with ✓ / ✗ flags so you immediately see what your token can do

Tools

20 tools across 4 skill groups. The help tool returns the live list filtered by your token's scopes.

v0.2.0 — the 7 widget_bug tools (get_bug_report, get_bug_screenshot, get_bug_annotations, get_bug_console_logs, get_bug_network_requests, get_bug_metadata, get_bug_breadcrumbs) were dropped. Bug reports submitted via the in-app widget now create a regular ticket (sourceType='reporter') with the screenshot as an attachment and breadcrumbs / console / network / annotations in the ticket's reporterContext jsonb. Read everything in one call via get_ticket_details. Filter user-submitted bugs via find_tickets({ source: 'reporter' }) or the IQL source:reporter.

• help — list every tool grouped by skill, ✓ / ✗ per scope
• whoami — show identity, org, and accessible projects
• find_organizations — list orgs the token can access
• find_projects — list projects in an org
• find_releases — list releases for a project

• find_issues — search auto-captured error issues
• find_tickets — search tickets by IQL or filters
• get_issue_details — full issue + event history
• get_ticket_details — ticket fields, comments, links
• get_event_details — single event payload (stack, breadcrumbs)
• get_event_attachment — raw attachment bytes

• create_ticket — new ticket on a project
• update_ticket — patch fields, assignee, labels
• transition_ticket — move through the project workflow
• add_comment — post a comment
• link_pr — attach a PR / branch
• promote_issue_to_ticket — convert a captured error issue

• pin_release — pin a ticket to a release
• symbolicate_frame — resolve one stack frame against source maps
• find_release_artifacts — list uploaded source maps / bundles

Example agent prompts

Find every open issue tagged payments and create tickets for the top three by event count.

Show me in-app bug reports submitted by users this week — use find_tickets with source='reporter'.

For ticket FE-142, fetch the reporter context (breadcrumbs, console, network) and summarize what the user was doing right before they hit the bug.

Symbolicate frame 0 of issue ABC-123's stack trace and link the resulting source file to the existing ticket.

Scopes

Tokens carry scopes; tools require specific ones. help shows ✓ / ✗ per tool for the current token.

| Scope | Grants | |---|---| | projects:read | List orgs / projects / releases | | tickets:read | Read tickets + comments | | tickets:write | Create / update / transition tickets | | issues:read | Read auto-captured error issues + bug reports | | comments:write | Post comments on tickets | | releases:read | Read release metadata + artifacts |

Standalone MCP server

Two transports ship from the single @koderlabs/tasks-mcp package:

| Entry | Transport | Use case | |------------------|-------------------------|------------------------------------------------| | dist/index.js | Streamable HTTP (Hono) | Hosted at https://tasks.koderlabs.net/mcp | | dist/stdio.js | stdio | Local agents — npx -y @koderlabs/tasks-mcp |

Self-hosted HTTP transport:

PORT=8931 \
API_BASE_URL=https://your-api.example.com/api/v1 \
MCP_INTROSPECT_KEY=sk_live_<management key> \
npx @koderlabs/tasks-mcp@latest

Client config for a self-hosted endpoint:

{
  "mcpServers": {
    "instanttasks": {
      "url": "http://localhost:8931/mcp"
    }
  }
}

Configuration

Environment variables

| Var | Required by | Purpose | |-----------------------|----------------|-------------------------------------------------------------------------| | API_BASE_URL | HTTP transport | InstantTasks API base, e.g. http://api:11002/api/v1. Defaults are dev-only. | | PORT | HTTP transport | Listen port (default 11005). | | MCP_INTROSPECT_KEY | HTTP transport | Management key (sk_live_* / sk_test_*) used to call POST /oauth/introspect when validating user OAuth tokens. The process refuses to start without it. | | MCP_PUBLIC_URL | HTTP transport | Public URL of the MCP endpoint, used in OAuth discovery metadata. | | MCP_AUTH_ORIGIN | HTTP transport | Authorization-server origin (usually the API). | | MCP_ALLOWED_ORIGINS | HTTP transport | Comma-separated browser CORS allowlist. Empty = native clients only. | | MCP_RATE_LIMIT_RPM | HTTP transport | Per-token rate limit (requests/minute). Default 120. | | IT_API_BASE_URL | stdio | Same as API_BASE_URL, but for the stdio entry. | | IT_SECRET_KEY | stdio | Caller's management key. The stdio process exits non-zero if validation fails — no permissive fallback. |

Authentication

All requests must carry Authorization: Bearer <token>. The token is validated on the API and the resulting scope set determines which tools are listed for the session:

• Management key (sk_live_* / sk_test_*) — validated via GET /api/v1/sdk/keys/whoami-management. Any non-200 (including 404) is rejected as invalid_token.
• User OAuth access token (anything else) — validated via POST /api/v1/oauth/introspect. Because that endpoint is gated by ManagementKeyGuard, the MCP server presents its own MCP_INTROSPECT_KEY as the bearer and sends the user's token in the request body. Any non-200 / active: false response is rejected as invalid_token.

There is no stub/permissive identity fallback. A misconfigured server will refuse to start; a bad token will receive a 401.

Audit logging

All write tools are wrapped in withAudit() (src/middleware/audit.ts). Each invocation ships a redacted record to POST /audit/mcp:

• args — keys like password, token, secret, etc. replaced with [REDACTED]; embedded sk_live_* / Bearer … / JWT-like substrings inside any string field are also redacted.
• result.content — same string-level redaction; binary image entries have their data blob stripped.
• Failure path emits a success: false record with the (redacted) error message.

Ship failures retry with exponential backoff (3 attempts; 1s / 3s delays). After exhaustion the (already-redacted) payload is logged at error level with toolName as correlation id. See shipAuditWithRetry in src/api-client.ts.

Build from source

pnpm install
pnpm --filter @koderlabs/tasks-mcp build
pnpm --filter @koderlabs/tasks-mcp start         # HTTP transport
pnpm --filter @koderlabs/tasks-mcp start:stdio   # stdio transport

See the repo for docker compose, Caddy routing, and OAuth configuration.

Links

• Service: tasks.koderlabs.net
• Source: github.com/jawaidgadiwala/instant-tasks
• Issues: github.com/jawaidgadiwala/instant-tasks/issues

License

MIT