Kelvia MCP documentation

Overview

Kelvia MCP is a Model Context Protocol server that proxies your AI client's actions into the Kelvia REST API. The client sees a set of tools like list_tasks, create_task, add_task_comment and calls them as needed.

Quick start

1. Connect your account

   Add the hosted server to your MCP client and approve access in Kelvia when the browser opens. No token needs to be copied for the standard setup.

2. Pick a transport

   For the hosted MCP use https://mcp.kelvia.app/mcp. For a local run, build the kelvia-mcp package and connect it as a stdio server.

3. Add the config to your client

   Use one of the examples below for Cursor, Claude Code, Codex CLI or local stdio.

4. Verify the connection

   Ask the client: “List my Kelvia boards”. If the agent sees your boards, move on to tasks, comments and worklogs.

Authorization and permissions

Hosted clients use OAuth by default: Kelvia opens in the browser, asks you to approve access and lets the client refresh its credentials. For autonomous agents, use a dedicated agent key with its own authorship, scopes and independent revocation.

Connecting clients

Cursor, remote HTTP

Add the server to ~/.cursor/mcp.json or a project-level .cursor/mcp.json, then select Connect in Cursor Settings → Tools & MCP.

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

Claude Code, remote HTTP

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

Codex app, CLI and IDE extension

Add the server, complete OAuth in the browser and verify the shared Codex configuration:

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

Local stdio

Build the MCP package first:

pnpm --filter kelvia-mcp build
# or
pnpm run build:mcp

Then connect the built file as a local MCP server:

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

MCP tools

The 58 tools are grouped below. Argument names in MCP use snake_case; the server maps them onto REST API fields where needed.

Annotations

Every tool declares readOnlyHint, destructiveHint and idempotentHint, so a client can approve reads on its own and ask before a delete. 22 of the 58 tools are read-only.

Toolsets

The full set costs about 45 KB of JSON schema in every session. Load only what a workflow needs — tasks,planner publishes 21 tools and about 20 KB. get_current_user is always published; an empty or unknown value publishes everything.

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

# remote — header, preferred
X-MCP-Toolsets: tasks,planner

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

Prompts & resources

The MCP server also publishes prompts and resources so the client never has to guess the schema.

Operations

Environment variables

Health and discovery

GET /health reports the live transports and the available toolsets. OAuth discovery lives at /.well-known/oauth-protected-resource/mcp on the MCP server and /.well-known/oauth-authorization-server on the backend.

Legacy SSE and scaling

Legacy SSE keeps sessions in process memory. If GET /sse and POST /messages land on different instances, the client can get 404 Session not found. SSE needs a single instance or sticky sessions. Streamable HTTP on /mcp does not have this problem.

Troubleshooting