kelvia-mcp

Purpose

Kelvia MCP is a shared task manager for people and coding agents. One specific use is handing off unfinished tasks between Claude Code and Codex. Through the Model Context Protocol, agents can create and update tasks, move work across a Kanban board, post comments, log time, run phases, and plan a day's schedule, with all changes visible and attributed in the same interface people use.

Main capabilities

The server exposes a total of 58 tools, covering the following groups:

• Boards (9): list boards, get a board, create/update/archive/unarchive/delete boards, list board columns, view board activity.
• Tasks (12): list tasks, list daily tasks, list calendar tasks, get a task, get a task by number, create/update/reorder/delete tasks, view task activity, get and set task summaries.
• Comments and time entries (8): get/add/update/delete task comments, get/add/update/delete task time entries.
• Phases (8): create board phases, materialize backlog phase entities, update/delete/reorder phases, start/complete/reopen phases.
• Members and invitations (9): list board members, update/remove members, list/create/revoke board invitations, list my invitations, accept/decline board invitations.
• Personal schedule planning (8): list daily plan blocks, list daily plan definitions, list overdue blocks, create/update/set status/reorder/delete daily plan blocks.
• Tags (3): list board tags, list tags, create board tags.
• Core (1): get_current_user.

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

Each tool carries MCP annotations (readOnlyHint, destructiveHint, idempotentHint), which clients can use to automatically approve read operations and prompt before deletion. 22 of the 58 tools are read-only.

Usage

Hosted quick start (recommended)

The production endpoint is mcp.kelvia.app. OAuth is the default method: the client opens Kelvia in the browser, and you approveAfter access, the client stores and refreshes its OAuth credentials, so there is no need to paste an API token into a configuration file.

Claude Code: after starting, enter /mcp, select kelvia, complete Authenticate in the browser, then verify the connection.

Codex: The Codex app, CLI, and IDE extensions share the MCP configuration on the same Codex host; you can inspect servers with /mcp in an interactive session.

Cursor: add the server in ~/.cursor/mcp.json or the project-level .cursor/mcp.json, open Cursor Settings → Tools & MCP, enable kelvia, and select Connect to complete OAuth in the browser.

Agent key authentication

OAuth acts as the approved Kelvia user. When a connection needs its own identity, board membership, role, expiration, and fine-grained read/create/edit/delete scopes, use an agent key instead. Create it in Kelvia → Profile → Agents: create the agent identity, join only the required boards and select board roles, create the key with the minimum necessary scopes and an expiration date, and copy the displayed klv_… value (Kelvia stores only its hash).

Tokens should be kept in environment variables; do not put tokens in URLs. The Streamable HTTP endpoint accepts authentication only via the Authorization header.

Local stdio setup

Most people should use the hosted endpoint above. Running the server locally does not leave tasks on the local machine—tasks still exist in Kelvia, and the local process accesses the same API; what changes is the credential transport path and which clients can connect. Applicable cases: the client does not support remote MCP or OAuth; automating in CI; keys should not leave the local machine. Requires Node.js 20+.

MCP Bundle for Claude Desktop

To install locally into Claude Desktop, build the MCP Bundle (.mcpb), open the file, and enter a dedicated Kelvia agent key when prompted. The bundle is the packaged form of the same local stdio server.

Toolsets loaded on demand

The full tool surface consumes about 45 per session KB JSON schema. You can load only the parts needed by the workflow: get_current_user is always published; omitting this setting or naming a nonexistent toolset publishes all tools. For example, tasks,planner publishes 21 tools and about 20 KB of schema.

Applicable Scenarios

• Hand off shared tasks among Claude Code, Codex, and humans, keeping summaries, status, and work history on the same board.
• Let agents read the board, decide priorities, submit follow-up tasks, and comment on blockers.
• Reserve time in a personal schedule planner for work that has just completed triage.
• Automation that requires controlled write permissions: the scope of an agent key intersects with the agent role on each board.
• Require visible agent activity: changes, comments, and work logs all appear in Kelvia, and supported task changes can be rolled back by a human in the app.

Limitations

• Streamable HTTP is stateless at the MCP transport layer; legacy SSE session storage is in process memory, so SSE requires a single instance or sticky sessions.
• Legacy SSE is at /sse and may require a query token because browser EventSource cannot set headers; prefer /mcp.
• OAuth tokens cannot manage account credentials, personal API tokens, agents, or MCP connections.
• Agent keys are stored hashed at rest, revocable, optionally expiring, and limited by both key scope and board role.
• Remote sessions appear in the Kelvia profile and can be revoked.
• Treat the MCP server as a privileged integration: review requests before approving writes, use dedicated agent keys for automation, and grant only the boards and permissions the workflow needs.
• For data processing on hosted endpoints, see the AI and MCP data processing policy; the privacy policy covers all of Kelvia.

Self-Hosted HTTP Endpoint

Setting PORT switches the process from stdio to Streamable HTTP, after which the available transports and toolsets can be checked via GET /health.

Troubleshooting

• Authentication required / HTTP 401: complete OAuth in the client's MCP panel, or confirm that the Bearer token environment variable is available to the client process.
• HTTP 403: the key lacks the required scope, the agent lacks the required boardrole, or the email/account status blocks the operation.
• Server connected but board missing: add the agent identity to that board, or approve OAuth with a user who already has access.
• stdio mode connection closed: run pnpm build, use absolute paths, and confirm that Node.js 20+ and KELVIA_API_TOKEN are present.
• Tools not visible: check claude mcp list, codex mcp list, or Cursor's Tools & MCP panel, and restart/reload the client after changing the configuration.
• Task output too large: use the streamlined list_tasks, filter by board/status, then call get_task for a single record.
• Too many client tools: use toolsets to narrow the tool surface.