Kelvia

Kelvia MCP — コーディングエージェント向けタスクマネージャー

Kelviaは、人とコーディングエージェントが共有するタスクマネージャーです。具体的な使い方の一例として、未完了のタスクを Claude Code から Codex に引き継ぐことができます。このガイドでは、Kelvia を使わずに利用できる、リポジトリファイルを使ったコピー可能な引き継ぎ方法を紹介したうえで、共有タスクが役立つ場面を説明します。Model Context Protocolを通じて、エージェントはタスクの作成と更新、カンバンボード上での作業の移動、コメント、時間の記録、ステージの実行、1日の計画ができます。変更は、人間が使うものと同じ UI 上で確認でき、誰が行ったかも表示されます。

このサーバーは58 個のツールを公開し、Claude Code、Codex、Cursor などの MCP クライアントで動作します。ホスト型エンドポイントでは OAuth を使用するため、推奨セットアップでは API トークンを貼り付ける必要はありません。CI やリモート MCP に対応していないクライアント向けに、ローカルの stdio モードも利用できます。

無料で試す · MCP ドキュメント · ホスト型エンドポイント

1 つのコマンドで接続

クライアント	コマンド
Claude Code	claude mcp add --transport http --scope user kelvia https://mcp.kelvia.app/mcp
Codex	codex mcp add kelvia --url https://mcp.kelvia.app/mcp
Cursor	Settings → Tools & MCP で https://mcp.kelvia.app/mcp を追加します

最初の接続時に、OAuth の承認を行うため Kelvia がブラウザーで開きます。接続後、クライアントに「Kelvia のボードを一覧表示して」と尋ねてください。

Kelvia MCP を選ぶ理由

• ワークフロー全体をカバー — タスクの作成とトリアージ、ボード上での作業の移動、時間の記録、ステージの実行、1日の計画ができます。読み取り専用のブリッジではありません。
• 制御された書き込みアクセス — エージェントキーには読み取り／作成／編集／削除のスコープがあり、各ボードにおけるエージェントのロールに応じて適用されます。
• エージェントのアクティビティを可視化 — 変更、コメント、作業ログは Kelvia に表示されます。また、対応するタスクの変更は、アプリで人間が元に戻せます。
• 必要なものだけを読み込む — ツールセットを使うと、すべての 58 個のツールではなく、製品の一部だけをクライアントに公開できます。
• 最新のリモート認証 — Streamable HTTP と OAuth 2.1 + PKCE、または明示的なエージェント ID が必要な場合の Bearer トークンを使用できます。
• 必要に応じてローカルでも利用可能 — リモート MCP に対応していないクライアント、CI、キーを 1 台のマシンに保持したい場合に、stdioを利用できます。

動作を確認する

クライアント側では、1つのプロンプトでエージェントがボードを読み取り、重要な情報を判断し、フォローアップタスクを作成して、ブロッカーにコメントします。

_{mcp.kelvia.app に接続した実際のセッションを、トランスクリプトから組版したものです。 create_task で実際に #17 が作成され、add_task_comment で実際に #9 にコメントが追加されました。このセクションの以降の内容で、その様子を紹介します。}

プロダクト側から見ると、以下はすべてこのサーバーを介してエージェントが作成したものです。ボード、タスク、ディスカッション、記録された作業時間をご覧ください。

同じ実行内容を動画で見る

エージェントが行った変更はすべてエージェントに帰属し、絞り込みが可能です。そのため、人間は要約を信頼するだけでなく、実際に何が起きたかを正確に確認できます。

個人用のデイリープランナーも利用できるため、エージェントはトリアージした作業をそのまま予定に組み込めます。

ホステッド版のクイックスタート（推奨）

本番環境のエンドポイントは次のとおりです。

https://mcp.kelvia.app/mcp

OAuth がデフォルトです。クライアントがブラウザーで Kelvia を開き、アクセスを承認すると、クライアントが OAuth 認証情報を保存し、更新します。設定ファイルに API トークンを貼り付ける必要はありません。

Claude Code

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

Claude Code を起動し、/mcp と入力して kelvia を選択し、ブラウザーで認証を完了します。認証後、次のコマンドで接続を確認します。

List my Kelvia boards.

Codex アプリ、CLI、IDE 拡張機能

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

Codex アプリ、CLI、IDE 拡張機能は、Codex ホスト上で同じ MCP 設定を共有します。対話型の Codex セッションでは、/mcp を使ってサーバーを確認できます。

~/.codex/config.toml での同等の設定：

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

Cursor

サーバーをグローバルに設定するには ~/.cursor/mcp.json に、プロジェクトごとに設定するには .cursor/mcp.json に追加します。

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

Cursor Settings → Tools & MCP を開いて kelvia を有効にし、Connect を選択してブラウザーで OAuth を完了します。サーバーが接続済みと表示されたら、Cursor に Kelvia のボード一覧を求めてください。

エージェントキー認証

OAuth は承認を行う Kelvia ユーザーとして動作します。接続に独自の ID、ボードメンバーシップ、ロール、有効期限、きめ細かな読み取り／作成／編集／削除スコープが必要な場合は、代わりにエージェントキーを使用してください。

Kelvia → Profile → Agents で作成します。

1. エージェント ID を作成します。
2. 必要なボードのみに追加し、ボード上のロールを選択します。
3. 必要最小限のスコープと有効期限を設定してキーを作成します。
4. 表示されたら klv_… の値をコピーします。Kelvia にはそのハッシュのみが保存されます。

エージェントキーを使った Codex

トークンは環境変数に保存し、Codex には変数名のみを保存します。

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

~/.codex/config.toml での同等の設定：

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

エージェントキーを使った Claude Code

Claude Code は MCP JSON 内の環境変数を展開します。以下のシングルクォートは、シェルがコマンド履歴にトークンを展開して記録するのを防ぎます。

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

トークンを URL に含めないでください。Streamable HTTP エンドポイントが認証を受け付けるのは Authorization ヘッダー経由のみです。

ローカルの stdio セットアップ

ほとんどの方には、上記のホスト型エンドポイントの利用をおすすめします。 サーバーをローカルで実行しても、タスクがマシン上に保存されるわけではありません。いずれの場合もタスクは Kelvia に保存され、ローカルプロセスは同じ API と通信します。変わるのは、認証情報が通る経路と、接続できるクライアントです。

次のいずれかに該当する場合は、stdio を使用してください。

• クライアントがリモート MCP や OAuth に対応していない場合。 主なクライアントは対応していますが、古いバージョン、一部の IDE プラグイン、ブラウザーへのリダイレクトが開かない制限付きのマシンでは対応していないことがあります。
• CI で自動化する場合。 OAuth プロンプトを承認する人がいない環境では、ホスト型エンドポイントに対してエージェントキーを使う方法もありますが、stdio を使えば依存関係をなくせます。
• キーをマシンの外に出したくない場合。 ホスト型エンドポイントを使用すると、トークンは mcp.kelvia.app に送信され、セッション中はそのメモリーに保持されます。stdio の場合、トークンが送信されるのは Kelvia API だけです。

要件：Node.js 20 以上。

何もインストールせずに公開パッケージを実行します。

npx kelvia-mcp

または、ソースからビルドし（Node.js 20 以上、pnpm 9 以上）、クライアント設定で dist/index.js の絶対パスを指定します。

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

Claude Desktop 用 MCP Bundle

Claude Desktop にローカルインストールするには、MCP Bundle（.mcpb）をビルドします。

pnpm run bundle:mcpb

これにより build/kelvia-mcp-<version>.mcpb が生成されます。そのファイルを Claude Desktop で開き、プロンプトが表示されたら専用の Kelvia エージェントキーを入力してください。このバンドルは、同じローカル stdio サーバーをパッケージ化したものです。ホスト型 OAuth 接続を利用する場合は、代わりに推奨のクイックスタートを使用してください。

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"
      }
    }
  }
}

利用可能なツール

58 個のツール

ボード（9） — list_boards、get_board、create_board、update_board、 archive_board、unarchive_board、delete_board、list_board_columns、 get_board_activity

タスク（12） — list_tasks、list_daily_tasks、list_calendar_tasks、 get_task、get_task_by_number、create_task、update_task、reorder_task、 delete_task、get_task_activity、get_task_summary、set_task_summary

コメントと作業ログ（8） — get_task_comments、add_task_comment、 update_task_comment、delete_task_comment、get_task_worklogs、 add_task_worklog、update_task_worklog、delete_task_worklog

ステージ（8） — create_board_stage、materialize_board_backlog_stage、 update_board_stage、delete_board_stage、reorder_board_stages、 start_board_stage、complete_board_stage、reopen_board_stage

メンバーと招待（9） — list_board_members、update_board_member、 remove_board_member、list_board_invitations、create_board_invitation、 revoke_board_invitation、list_my_invitations、accept_board_invitation、 decline_board_invitation

個人用デイリープランナー（8） — list_daily_plan_blocks、 list_daily_plan_definitions、list_overdue_daily_plan_blocks、 create_daily_plan_block、update_daily_plan_block、 set_daily_plan_block_status、reorder_daily_plan_blocks、 delete_daily_plan_block

タグ（3） — list_board_tags、list_tags、create_board_tag

コア（1） — get_current_user

サーバーは、2 つのプロンプト（create_task_from_pr と triage_board_backlog）と、kelvia://schema/… にある 2 つのスキーマリソースも公開します。

すべてのツールには MCP アノテーション（readOnlyHint、destructiveHint、 idempotentHint）が付与されているため、クライアントは読み取りを自動承認し、削除の前に確認を求めることができます。58 個のツールのうち、22 個は読み取り専用です。

ツールセット

すべての機能を有効にすると、セッションごとに約 45 KB の JSON スキーマが必要です。ワークフローに必要な部分だけを読み込みます。

ツールセット	ツール	対象
boards	9	ボード、列、ボードのアクティビティ
tasks	12	タスク、タスクのアクティビティ、AI による要約
comments	8	コメントと作業記録
stages	8	スプリントとマイルストーン
members	9	メンバー、ロール、招待
planner	8	個人向けのタイムブロック式デイリープラン
tags	3	ボードとワークスペースのタグ

get_current_user は常に公開されます。設定を省略するか、存在しないツールセットを指定すると、すべてが公開されます。

# 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 を指定すると、45 KB ではなく約 20 KB のスキーマで 21 個のツールが公開されます。

最初に試すプロンプト

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.

セキュリティモデル

• リモートトークンは Authorization: Bearer … ヘッダーでのみ受け付けられます。
• OAuth では、PKCE を使用した認可コードフローと動的クライアント登録を使用します。
• OAuth トークンでは、アカウントの認証情報、個人用 API トークン、エージェント、MCP 接続を管理できません。
• エージェントキーは保存時にハッシュ化され、取り消し可能で、任意で有効期限を設定でき、キーのスコープとボードのロールの両方によって権限が制限されます。
• リモートセッションは Kelvia プロファイルに表示され、取り消すことができます。
• 古いクライアント向けに /sse でレガシー SSE を利用できます。ブラウザーの EventSource はヘッダーを設定できないため、クエリトークンが必要になる場合があります。認証情報が URL、ブラウザーの履歴、プロキシのアクセスログに含まれないよう、/mcp を優先してください。

MCP サーバーは、特権を持つインテグレーションとして扱ってください。承認する前に要求された書き込みを確認し、自動化には専用のエージェントキーを使用して、ワークフローに必要なボードとスコープのみを付与してください。

脆弱性の報告については、SECURITY.md をご覧ください。ホストされたエンドポイントでのデータの取り扱いについてはAI および MCP のデータ処理ポリシーで説明しています。また、プライバシーポリシーでは Kelvia 全体について説明しています。

プライバシーポリシー

MCP Bundle は Kelvia API に接続し、依頼された操作の実行に必要なリクエストを送信します。独自の分析サービスや広告サービスは実行しません。インストールする前に、Kelvia プライバシーポリシーとAI および MCP のデータ処理ポリシーをご確認ください。

HTTP エンドポイントのセルフホスト

PORT を設定すると、プロセスは stdio から 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

次に GET /health を確認してください。利用可能なトランスポートとツールセットが報告されます。

環境変数

変数	モード	用途
KELVIA_API_TOKEN	stdio	エージェントキーまたは個人用トークン
KELVIA_API_URL	both	API のベース URL。デフォルトは https://api.kelvia.app/api
KELVIA_TOOLSETS	both	カンマ区切りのツールセット。デフォルトはすべて
PORT	hosted	HTTP モードを有効にし、リッスンするポートを指定
MCP_PUBLIC_URL	hosted	公開された保護リソースのオリジン
MCP_AUTHORIZATION_SERVER	hosted	OAuth 認可サーバーのオリジン
MCP_ALLOWED_ORIGINS	hosted	カンマ区切りの CORS 許可リスト
MCP_RATE_LIMIT	hosted	トークンごとの 1 分あたりのリクエスト数。デフォルトは 300
MCP_INSTANCE_COUNT	hosted	HTTP インスタンス数
MCP_STICKY_SESSIONS	hosted	複数インスタンスでレガシー SSE を使う場合に必要

Streamable HTTP は MCP トランスポート層でステートレスです。レガシー SSE のセッションはプロセスメモリに保存されるため、SSE を使用するにはインスタンスを 1 つにするか、スティッキーセッションが必要です。

トラブルシューティング

• 認証が必要です／HTTP 401 — クライアントの MCP パネルから OAuth を完了するか、Bearer トークンの環境変数がクライアントのプロセスで利用できることを確認してください。
• HTTP 403 — キーに必要なスコープがない、エージェントに必要なボードのロールがない、またはメールアドレス／アカウントの状態によってその操作がブロックされています。
• サーバーには接続できるが、ボードが見つからない — エージェントの ID をそのボードに追加するか、すでにアクセス権を持つユーザーとして OAuth を承認してください。
• stdio モードで Connection closed が表示される — pnpm build を実行し、絶対パスを使用して、Node.js 20+ と KELVIA_API_TOKEN が設定されていることを確認してください。
• ツールが表示されない — claude mcp list、codex mcp list、または Cursor の ツールと MCP パネルを確認し、設定を変更した後にクライアントを再起動／再読み込みしてください。
• タスクの出力が大きい — コンパクトな list_tasks を使い、ボード／ステータスで絞り込んでから、詳細なリストをリクエストする代わりに 1 件のレコードに対して get_task を呼び出してください。
• クライアントでツールが多すぎる — ツールセットを使って公開範囲を絞り込んでください。

ヘルスチェックと OAuth の検出：

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

開発

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

pnpm run test はパッケージをビルドし、公式 MCP クライアント SDK を通じて stdio サーバーを初期化したうえで、公開されているツール、アノテーション、ツールセット、プロンプト、リソース、サーバーの指示を検証します。

このリポジトリと Kelvia モノレポとの関係、およびツールの変更時に影響する箇所については、CONTRIBUTING.md を参照してください。

ライセンス

MIT