Conatus MCP Server

An independently installable Model Context Protocol server for the self-hosted Conatus task manager.

It exposes agent-safe tools for projects, sections, tasks, labels, comments and reminders. It supports local stdio clients and remote Streamable HTTP clients. Permanent deletion is intentionally not exposed.

Requirements

• Node.js 20 or newer

• A reachable Conatus installation with the /api/v1 API

• A scoped API token created in Settings → API tokens

Related MCP server: Google Tasks MCP Server

Local stdio setup

The local mode is the recommended default. The AI host starts one MCP process for the configured task-manager account.

One-command setup

Run the interactive installer to validate your Conatus URL and scoped API token, then register the server with Claude Desktop, Claude Code, Cursor, or another JSON MCP configuration file:

npx -y conatus-mcp setup

The installer never echoes the token, verifies it before changing a config file, and restricts the written configuration file to owner-only permissions where the operating system supports them. Restart the chosen client when it finishes. The direct configuration below remains the non-interactive fallback.

{
  "mcpServers": {
    "my-tasks": {
      "command": "npx",
      "args": ["-y", "conatus-mcp"],
      "env": {
        "TASKS_BASE_URL": "https://tasks.example.com",
        "TASKS_API_TOKEN": "tdm_replace_me"
      }
    }
  }
}

For a local development installation, use http://localhost:3000 as TASKS_BASE_URL.

You can also install the package once:

npm install --global conatus-mcp
conatus-mcp

Remote Streamable HTTP mode with browser OAuth

Use OAuth when an agent needs to connect by URL. The MCP server acts as a single-user gateway: its scoped TASKS_API_TOKEN identifies the task workspace, while each AI client receives a separate short-lived OAuth token. The task token never leaves the server.

TASKS_BASE_URL=https://tasks.example.com \
TASKS_API_TOKEN=tdm_replace_me \
MCP_HOST=0.0.0.0 \
MCP_PORT=3001 \
MCP_PUBLIC_URL=https://mcp.example.com/mcp \
MCP_OAUTH_PASSWORD='use-a-long-separate-approval-password' \
MCP_OAUTH_STORE_PATH=/var/lib/task-mcp/oauth-store.json \
MCP_ALLOWED_ORIGINS=https://your-ai-host.example \
conatus-mcp-http

Give the AI client only https://mcp.example.com/mcp. A compatible client discovers the protected-resource metadata, dynamically registers itself, opens the approval page and completes an OAuth authorization-code flow with S256 PKCE. Enter MCP_OAUTH_PASSWORD in that page to approve it.

The server issues one-hour access tokens and rotating 30-day refresh tokens. OAuth client registrations and token hashes are stored in the file at MCP_OAUTH_STORE_PATH with mode 0600; raw OAuth tokens and the approval password are not stored. Run one MCP replica per store file. For multiple replicas, replace the JSON store with a shared transactional store first.

Put TLS and a reverse proxy in front of port 3001. MCP_PUBLIC_URL must be the exact external endpoint and end in /mcp. Production URLs must use HTTPS. Requests carrying an Origin header are accepted only when the origin is listed in MCP_ALLOWED_ORIGINS; native clients commonly send no Origin.

Domain and reverse proxy

The task app and MCP gateway can use separate addresses:

• https://tasks.example.com → the web app and /api/v1

• https://mcp.example.com/mcp → this child MCP service

Create DNS records for both names, terminate TLS at your proxy and forward mcp.example.com to port 3001. Only the proxy should expose that port. The OAuth metadata, registration, authorization, token, revocation, approval and MCP endpoints all share the MCP origin.

Static bearer fallback

For clients that cannot perform OAuth, omit MCP_PUBLIC_URL and MCP_OAUTH_PASSWORD, then set MCP_BEARER_TOKEN to a long random value. Connect to /mcp and send that value as a bearer token. This is less convenient to rotate per client and should not be pasted into prompts.

Binding to a non-loopback address without either complete OAuth configuration or MCP_BEARER_TOKEN is rejected.

Docker

Released images are published to ghcr.io/nojusmorkunas/conatus-mcp. Build locally only when working on the server itself:

docker build -t conatus-mcp .
docker run --rm -p 127.0.0.1:3001:3001 \
  -v task-mcp-oauth:/data \
  -e TASKS_BASE_URL=https://tasks.example.com \
  -e TASKS_API_TOKEN=tdm_replace_me \
  -e MCP_HOST=0.0.0.0 \
  -e MCP_PUBLIC_URL=https://mcp.example.com/mcp \
  -e MCP_OAUTH_PASSWORD='use-a-long-separate-approval-password' \
  -e MCP_OAUTH_STORE_PATH=/data/oauth-store.json \
  conatus-mcp

Environment variables

Do not put tokens in prompts, tool arguments, source control or command-line arguments. Environment variables keep them out of MCP messages and most process listings.

To revoke one OAuth client, let that client call the advertised revocation endpoint. To revoke every connected client, stop the service and remove its OAuth store file, then restart; all clients must connect again. Revoke or rotate TASKS_API_TOKEN in task-manager Settings if the gateway itself is compromised.

Tools

• Workspace: get_workspace_context

• Projects: list_projects, get_project, create_project, update_project

• Sections: create_section, update_section

• Tasks: list_tasks, get_task, create_task, quick_add_task, update_task, move_task, complete_task, reopen_task, set_task_labels

• Labels: list_labels, create_label

• Collaboration: add_comment

• Scheduling: set_reminder

Create operations use idempotency keys so retries do not create duplicate tasks. Task and comment content is returned as structured user data and must not be treated as agent instructions.

Resources

• taskapp://workspace

• taskapp://views/today

• taskapp://views/upcoming

• taskapp://projects/{id}

• taskapp://tasks/{id}

Development

npm install
npm test
npm run build
npm run dev

Test the built stdio server with MCP Inspector:

TASKS_BASE_URL=http://localhost:3000 \
TASKS_API_TOKEN=tdm_replace_me \
npx @modelcontextprotocol/inspector node dist/cli.js

Releasing

Publishing a GitHub release builds ghcr.io/nojusmorkunas/conatus-mcp for linux/amd64 and linux/arm64, then publishes the npm package. Both come from the released commit, so a release either produces both artifacts or neither.

Tag the release vX.Y.Z matching package.json; the npm job refuses to publish a mismatch. Mark prereleases as such on GitHub and they go to the beta dist-tag, leaving latest on the newest stable release.

npm publishing uses trusted publishing, so this repository stores no npm token. It requires a one-time configuration on the package's npmjs.com settings page linking it to this repository and the Publish release workflow.

To publish by hand instead:

npm publish --tag latest   # or --tag beta for a prerelease

Name the dist-tag explicitly. npm rejects a bare npm publish for any version with a semver prerelease suffix, which every 0.x.y-beta.z has.

prepublishOnly reruns the test, lint and build checks. publishConfig.access is already set, so no --access flag is needed.