MCP Server

TaskView ships an MCP (Model Context Protocol) server that lets AI assistants such as Claude Code and Claude Desktop work with your projects and tasks through the TaskView API.

It runs in two modes:

Local (stdio):   AI client  ──stdio──▶  taskview-mcp (npx)      ──HTTPS──▶  TaskView API
Shared (HTTP):   AI client  ──HTTPS──▶  taskview-mcp container  ──HTTP───▶  TaskView API

• Local (stdio) — each user runs the server on their machine via npx; the token lives in the client config.
• Shared (HTTP) — one server container runs next to your TaskView instance; every user connects to its URL and authenticates with their own API token per request, or over OAuth for clients that cannot send a token header.

Prerequisites

• Node.js >= 24
• A TaskView API token (tvk_...) — create one in your account settings. See API tokens.

Configuration

No installation is required — the server runs via npx. Add it to your MCP client config:

{
  "mcpServers": {
    "taskview": {
      "command": "npx",
      "args": ["-y", "taskview-mcp"],
      "env": {
        "TASKVIEW_URL": "https://api.taskview.tech",
        "TASKVIEW_TOKEN": "tvk_your_token_here"
      }
    }
  }
}

• Claude Code — add to .claude/settings.json (project) or ~/.claude.json (global).
• Claude Desktop — add to claude_desktop_config.json.

Set TASKVIEW_URL to your own instance when self-hosting.

Shared HTTP server (self-hosted)

The gimanhead/taskview-ce-mcp image serves MCP over HTTP (Streamable HTTP transport), so users don't need Node.js or npx — they just point their client at a URL. Add it to your docker-compose.yml next to the API (see the commented block in the installation guide):

  taskview-mcp:
    image: gimanhead/taskview-ce-mcp:latest
    restart: unless-stopped
    environment:
      # Where this MCP server forwards requests; the docker-network address
      # of your API service works best. For OAuth it must be the public API
      # URL instead — see below.
      TASKVIEW_URL: "http://taskview-api-server:1401"
    ports:
      - "3100:3100"
    networks: [backend]

The MCP endpoint is /mcp (port 3100, configurable via MCP_HTTP_PORT), health check at /health. Every request must carry the caller's own token in the Authorization header — requests without it get 401. The server is stateless and keeps no data: each request is forwarded with exactly the token it came with.

Connect from Claude Code:

claude mcp add --transport http taskview https://mcp.your-domain.com/mcp \
  --header "Authorization: Bearer tvk_your_token_here"

or in .mcp.json (Claude Code, Cursor, VS Code):

{
  "mcpServers": {
    "taskview": {
      "type": "http",
      "url": "https://mcp.your-domain.com/mcp",
      "headers": { "Authorization": "Bearer tvk_your_token_here" }
    }
  }
}

Put the port behind your reverse proxy with HTTPS for anything beyond local use.

OAuth (cloud clients)

Cloud assistants have no field for a pasted token: claude.ai and Claude Desktop custom connectors, ChatGPT connectors and similar clients authorize over OAuth 2.1 instead. The shared HTTP server supports this with nothing extra to run. The MCP server presents itself as the protected resource and names your TaskView API as the authorization server; the API handles client registration, the consent screen and tokens.

What happens when a client connects:

1. The client calls /mcp without a token and gets 401 with a WWW-Authenticate header pointing at the resource metadata.
2. It reads /.well-known/oauth-protected-resource on the MCP server, then /.well-known/oauth-authorization-server on the API.
3. It registers itself (dynamic client registration, RFC 7591) and opens the TaskView consent screen in your browser.
4. You sign in and tick the permissions and projects the app may use. Ticking nothing grants your full access; your RBAC role is the ceiling either way.
5. The client receives a tvo_ access token (valid 1 hour) and a refresh token (valid 30 days), and sends the access token to /mcp like any other bearer token.

To connect, paste the MCP URL (https://mcp.your-domain.com/mcp) into the client's custom connector form. When it asks you to authorize, the TaskView consent screen opens. Claude Code can use OAuth too: add the server without the --header flag and run /mcp to authenticate.

Configuration for OAuth

• MCP_PUBLIC_URL on the MCP server — the public URL of the server exactly as clients reach it. This is the OAuth resource identifier. When unset it is derived from the request's Host and X-Forwarded-Proto headers.
• TASKVIEW_URL on the MCP server — advertised to clients as the authorization server, so for OAuth it must be the public API URL (https://api.your-domain.com), not the docker-network address from the example above.
• API_PUBLIC_URL and APP_URL on the API — the first names the authorization server in its metadata, the second is where the consent screen lives. See environment variables.
• OAUTH_DYNAMIC_REGISTRATION=false on the API — stops new clients from registering themselves, which closes OAuth for new connections on a locked-down instance. Existing connected apps keep working.

Mounted under a path. When the MCP server sits behind a reverse proxy at https://api.your-domain.com/mcp rather than on its own host, put the full path into MCP_PUBLIC_URL. The resource metadata then also lives at /.well-known/oauth-protected-resource/mcp (RFC 9728), which is where a client that computes the address from the spec will look. The server publishes it at both that address and the root one, but the proxy has to route the path-inserted address to the MCP server too:

location = /.well-known/oauth-protected-resource/mcp {
    proxy_pass http://127.0.0.1:3100/.well-known/oauth-protected-resource/mcp;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
}

Managing connected apps

Every app you authorized is listed in your account settings under Connected apps, with the permissions and projects you granted and when it was last used. Revoking one cuts off its access immediately. OAuth tokens do not appear in the API tokens list and cannot be deleted from there.

Manually issued tvk_ tokens keep working exactly as before. OAuth is an additional way in, not a replacement: use tvk_ for stdio, CLIs and CI, where there is no browser to complete an authorization flow.

Permissions

The assistant can only do what its credential allows. API token permissions are scoped to selected projects; an OAuth grant carries the permissions and projects you ticked on the consent screen. Both are intersected with your RBAC role, so an AI client never exceeds your own access. Grant the minimum scope needed.