Vikunja MCP behind Cloudflare Access

A small, self-hosted Streamable HTTP MCP server that turns a narrow Vikunja REST API surface into tools for ChatGPT and other remote MCP clients. It is designed for an existing Cloudflare Tunnel and Cloudflare Access Managed OAuth deployment.

It exposes project and task reads, implements a tightly gated write path, and keeps the Vikunja API token on the server.

AI system overview

flowchart LR
    Client["ChatGPT or another remote MCP client"]
    Access["Cloudflare Access<br/>Managed OAuth and policy"]
    Tunnel["Cloudflare Tunnel"]
    JWKS["Cloudflare Access JWKS"]
    subgraph Origin["Private origin"]
      Adapter["Vikunja MCP adapter<br/>Streamable HTTP at /mcp"]
      Guard["Origin guard<br/>signature, issuer, audience, email"]
      Tools["Narrow MCP tools<br/>writes off by default"]
      ClientLib["Vikunja client abstraction<br/>REST v1 today"]
      Vikunja["Vikunja"]
    end

    Client -->|"OAuth 2.0 authorization code flow"| Access
    Access -->|"Cf-Access-Jwt-Assertion"| Tunnel
    Tunnel --> Adapter
    Adapter --> Guard
    Guard -.->|"fetches rotating signing keys"| JWKS
    Guard --> Tools
    Tools --> ClientLib
    ClientLib -->|"Bearer token stays server-side"| Vikunja

    classDef client fill:#e8f1ff,stroke:#2563eb,color:#172554
    classDef edge fill:#ecfdf5,stroke:#059669,color:#064e3b
    classDef origin fill:#f8fafc,stroke:#64748b,color:#0f172a
    classDef data fill:#fff7ed,stroke:#ea580c,color:#7c2d12
    class Client client
    class Access,Tunnel,JWKS edge
    class Adapter,Guard,Tools,ClientLib origin
    class Vikunja data

The public endpoint terminates at Cloudflare. The adapter accepts MCP traffic only after it validates the Access assertion with Cloudflare's rotating JWKS, expected issuer, application audience, and a local email allowlist. The separate Vikunja token never reaches the MCP client.

Related MCP server: Cloudflare Remote MCP Server (Authless)

Capabilities

The adapter has one Vikunja client abstraction. MCP tools never issue REST calls directly, so a future move away from the current /api/v1 backend is contained in one layer.

Security model

• Cloudflare Access Managed OAuth authenticates the human user. Cloudflare documents a short Access-token lifetime together with a longer grant session as the normal configuration for non-browser clients.

• The origin does not trust the tunnel alone. It validates the Cf-Access-Jwt-Assertion header's signature through JWKS, issuer, audience, and the authenticated email address.

• Use a dedicated least-privilege Vikunja integration account and API token. Store the token only in the server runtime secret store.

• The container does not publish a host port. It is read-only, drops Linux capabilities, uses no-new-privileges, and has a tmpfs for temporary files.

• MCP_WRITE_ENABLED is false unless explicitly changed. Even when enabled, writes require an additional identity allowlist.

Deployment shape

The example Compose file expects three networks:

• vikunja: an existing private network shared with the Vikunja service.

• mcp-proxy: an internal network shared with the existing Cloudflare Tunnel connector.

• mcp-egress: egress only for refreshing Cloudflare Access signing keys.

The tunnel hostname must route to http://vikunja-mcp:3000. Do not publish port 3000 on the host.

cp .env.example .env
# Populate only the empty secret and Access fields in your protected runtime copy.
docker compose -f compose.example.yml up -d --build

Configure a Cloudflare Access application for the MCP hostname and enable Managed OAuth in its advanced settings. Give the Access application a narrow allow policy, set the issuer and Audience tag in the container environment, and use the same intended users in CF_ACCESS_ALLOWED_EMAILS.

Cloudflare's current guidance: Managed OAuth and origin JWT validation.

Configuration

Health and operations

• GET /healthz checks that the Node process is live and needs no Access assertion.

• GET /readyz checks Vikunja connectivity and returns 503 when it is unavailable.

• POST /mcp is the only MCP endpoint. Other methods return 405.

• Logs deliberately contain only event names and fixed identifiers. They never include assertions, API tokens, task descriptions, or Vikunja response bodies.

Development

Node.js 20 or newer is required.

npm ci
npm test
docker build --tag vikunja-mcp-cloudflare-access:test .

The test suite covers Access assertion verification, unauthenticated rejection, stateless Streamable HTTP MCP discovery, read behavior, disabled writes, existing-label handling, and the REST-client boundary.

License

MIT