Kelvia MCP server

Kelvia is a task manager that AI agents can operate through the Model Context Protocol. This server exposes 58 tools for boards, tasks, comments, worklogs, stages, members, invitations, tags, and a personal day planner.

Connect to the hosted endpoint with OAuth — one command, no token to paste. A local stdio mode exists for clients that cannot do remote MCP, and for CI. You need a Kelvia account first — sign up at kelvia.app.

Why Kelvia MCP

• Complete workflow coverage — create and triage tasks, move work across a board, log time, run stages, and plan a day. Not a read-only bridge.
• Controlled write access — agent keys have read/create/edit/delete scopes intersected with the agent's role on each board.
• Visible agent activity — changes, comments, and worklogs appear in Kelvia; supported task changes can be reverted by a human in the app.
• Load only what you need — toolsets let a client publish one part of the product instead of all 58 tools.
• Modern remote auth — Streamable HTTP with OAuth 2.1 + PKCE, or a Bearer token when an explicit agent identity is required.
• A local option when you need one — stdio for clients without remote MCP support, for CI, and for keeping the key on one machine.

See it work

From the client side — one prompt, and the agent reads the board, decides what matters, files a follow-up task and comments on the blocker:

_{A real session against mcp.kelvia.app, typeset from its transcript. create_task really did create #17, and add_task_comment really did comment on #9 — which is what the rest of this section shows.}

And from the product side. Everything below was created by an agent over this server — the board, the tasks, the discussion, and the logged time.

Watch the same run as video

Every change an agent makes is attributed to it and filterable, so a human can review exactly what happened rather than trusting a summary:

The personal day planner is part of the surface too, so an agent can block out the work it just triaged:

Hosted quick start (recommended)

The production endpoint is:

https://mcp.kelvia.app/mcp

OAuth is the default. The client opens Kelvia in a browser, you approve access, and the client stores and refreshes its OAuth credentials. No API token needs to be pasted into a configuration file.

Claude Code

claude mcp add --transport http --scope user kelvia https://mcp.kelvia.app/mcp
claude mcp list

Start Claude Code, enter /mcp, choose kelvia, and complete Authenticate in the browser. After authentication, verify the connection with:

List my Kelvia boards.

Codex app, CLI, and IDE extension

codex mcp add kelvia --url https://mcp.kelvia.app/mcp
codex mcp login kelvia
codex mcp list

The Codex app, CLI, and IDE extension share the same MCP configuration on a Codex host. In an interactive Codex session, use /mcp to inspect the server.

Equivalent ~/.codex/config.toml:

[mcp_servers.kelvia]
url = "https://mcp.kelvia.app/mcp"
auth = "oauth"

Cursor

Add the server globally in ~/.cursor/mcp.json, or per project in .cursor/mcp.json:

{
  "mcpServers": {
    "kelvia": {
      "url": "https://mcp.kelvia.app/mcp"
    }
  }
}

Open Cursor Settings → Tools & MCP, enable kelvia, and select Connect to complete OAuth in the browser. Ask Cursor to list your Kelvia boards after it reports the server as connected.

Agent-key authentication

OAuth acts as the approving Kelvia user. Use an agent key instead when the connection needs its own identity, board membership, role, expiry, and granular read/create/edit/delete scopes.

Create one in Kelvia → Profile → Agents:

1. Create an agent identity.
2. Add it to only the required boards and choose its board role.
3. Create a key with the minimum required scopes and an expiry date.
4. Copy the klv_… value when shown; Kelvia stores only its hash.

Codex with an agent key

Keep the token in the environment; Codex stores only the variable name:

export KELVIA_API_TOKEN='klv_your_agent_key'
codex mcp add kelvia --url https://mcp.kelvia.app/mcp \
  --bearer-token-env-var KELVIA_API_TOKEN
codex mcp list

Equivalent ~/.codex/config.toml:

[mcp_servers.kelvia]
url = "https://mcp.kelvia.app/mcp"
bearer_token_env_var = "KELVIA_API_TOKEN"

Claude Code with an agent key

Claude Code expands environment variables in MCP JSON. Single quotes below keep your shell from expanding the token into its command history:

export KELVIA_API_TOKEN='klv_your_agent_key'
claude mcp add-json --scope user kelvia \
  '{"type":"http","url":"https://mcp.kelvia.app/mcp","headers":{"Authorization":"Bearer ${KELVIA_API_TOKEN}"}}'
claude mcp list

Do not put tokens in URLs. The Streamable HTTP endpoint accepts authentication only through the Authorization header.

Local stdio setup

Most people should use the hosted endpoint above. Running the server locally does not keep your tasks on your machine — they live in Kelvia either way, and the local process talks to the same API. What it changes is the path your credential takes, and which clients can connect.

Use stdio when one of these applies:

• Your client cannot do remote MCP or OAuth. The major clients can, but older versions, some IDE plugins, and locked-down machines where a browser redirect will not open, cannot.
• You are automating in CI, where nobody is around to approve an OAuth prompt. (An agent key against the hosted endpoint also works — this just removes a dependency.)
• Your key should not leave the machine. With the hosted endpoint your token reaches mcp.kelvia.app and stays in its memory for the session; over stdio it only ever goes to the Kelvia API.

Requirements: Node.js 20+.

Run the published package without installing anything:

npx kelvia-mcp

Or build from source (Node.js 20+ and pnpm 9+), then use an absolute path to dist/index.js in client configuration:

git clone https://github.com/gonnagetapower/kelvia-mcp.git
cd kelvia-mcp
pnpm install
pnpm build

MCP Bundle for Claude Desktop

For local installation in Claude Desktop, build the MCP Bundle (.mcpb):

pnpm run bundle:mcpb

This produces build/kelvia-mcp-<version>.mcpb. Open that file in Claude Desktop and enter a dedicated Kelvia agent key when prompted. The bundle is a packaged form of the same local stdio server; for the hosted OAuth connection, use the recommended quick start instead.

Claude Code (stdio)

claude mcp add --scope user \
  --env KELVIA_API_TOKEN=klv_your_agent_key \
  --transport stdio kelvia -- node /absolute/path/to/kelvia-mcp/dist/index.js

Codex (stdio)

codex mcp add kelvia \
  --env KELVIA_API_TOKEN=klv_your_agent_key \
  -- node /absolute/path/to/kelvia-mcp/dist/index.js

Cursor (stdio)

{
  "mcpServers": {
    "kelvia": {
      "command": "node",
      "args": ["/absolute/path/to/kelvia-mcp/dist/index.js"],
      "env": {
        "KELVIA_API_TOKEN": "klv_your_agent_key"
      }
    }
  }
}

Available tools

The server also publishes two prompts (create_task_from_pr and triage_board_backlog) and two schema resources under kelvia://schema/….

Every tool carries MCP annotations — readOnlyHint, destructiveHint, idempotentHint — so a client can auto-approve reads and prompt before a delete. 22 of the 58 tools are read-only.

Toolsets

The full surface costs about 45 KB of JSON schema in every session. Load only the parts a workflow needs:

get_current_user is always published. Omitting the setting, or naming a toolset that does not exist, publishes everything.

# stdio: environment variable
KELVIA_TOOLSETS=tasks,planner npx kelvia-mcp

# hosted: header (preferred)
X-MCP-Toolsets: tasks,planner

# hosted: query parameter, for clients that cannot set headers
https://mcp.kelvia.app/mcp?toolsets=tasks,planner

tasks,planner publishes 21 tools and about 20 KB of schema instead of 45 KB.

Good first prompts

List my Kelvia boards.

On board "product", show open high-priority tasks and suggest a triage order.
Do not modify anything.

Create a task on board "product" titled "Fix the login redirect", assign high
priority, and show me the created task.

Plan today using my three most urgent assigned tasks. Show the proposed blocks
before creating them.

Security model

• Remote tokens are accepted only in the Authorization: Bearer … header.
• OAuth uses authorization-code flow with PKCE and dynamic client registration.
• OAuth tokens cannot manage account credentials, personal API tokens, agents, or MCP connections.
• Agent keys are hashed at rest, revocable, optionally expiring, and limited by both key scopes and board roles.
• Remote sessions appear in the Kelvia profile and can be revoked.
• Legacy SSE exists for older clients at /sse; it may require a query token because browser EventSource cannot set headers. Prefer /mcp so credentials never enter URLs, browser history, or proxy access logs.

Treat MCP servers as privileged integrations. Review a requested write before approving it, use a dedicated agent key for automation, and grant only the boards and scopes the workflow needs.

Reporting a vulnerability: see SECURITY.md. Data handling for the hosted endpoint is described in the AI and MCP data processing policy, and the privacy policy covers Kelvia as a whole.

Privacy Policy

The MCP Bundle connects to the Kelvia API and sends the requests needed to perform the actions you ask it to take. It does not run a separate analytics or advertising service. Review the Kelvia Privacy Policy and the AI and MCP Data Processing Policy before installing it.

Self-hosting the HTTP endpoint

Setting PORT switches the process from stdio to Streamable HTTP.

docker build -t kelvia-mcp .
docker run --rm -p 8080:8080 \
  -e KELVIA_API_URL=https://api.kelvia.app/api \
  -e MCP_PUBLIC_URL=https://mcp.example.com \
  kelvia-mcp

Then check GET /health, which reports the available transports and toolsets.

Environment variables

Streamable HTTP is stateless at the MCP transport layer. Legacy SSE sessions are stored in process memory, so SSE requires one instance or sticky sessions.

Troubleshooting

• Needs authentication / HTTP 401 — complete OAuth from the client's MCP panel, or verify that the Bearer-token environment variable is available to the client process.
• HTTP 403 — the key lacks a required scope, the agent lacks the required board role, or the email/account state blocks that operation.
• Server connects but a board is missing — add the agent identity to that board, or approve OAuth as a user who already has access.
• Connection closed in stdio mode — run pnpm build, use an absolute path, and confirm Node.js 20+ plus KELVIA_API_TOKEN are present.
• No tools visible — check claude mcp list, codex mcp list, or Cursor's Tools & MCP panel, then restart/reload the client after changing config.
• Large task output — use compact list_tasks, filter by board/status, then call get_task for one record instead of requesting detailed lists.
• Too many tools for the client — narrow the surface with toolsets.

Health and OAuth discovery:

GET https://mcp.kelvia.app/health
GET https://mcp.kelvia.app/.well-known/oauth-protected-resource/mcp
GET https://api.kelvia.app/.well-known/oauth-authorization-server

Development

pnpm install
pnpm run lint
pnpm run typecheck:strict
pnpm run test

pnpm run test builds the package, initializes the stdio server through the official MCP client SDK, and verifies the published tools, annotations, toolsets, prompts, resources, and server instructions.

See CONTRIBUTING.md for how this repository relates to the Kelvia monorepo and what a tool change needs to touch.

License

MIT