MCP 接続ガイド

MCP とは

MCP (Model Context Protocol) は、Claude のようなエージェントがユーザーに代わって外部のツールやデータへアクセスするための、 クライアント/サーバー共通の規格。kichijitsu はこれを使って、カレンダーを読み書きできる「公式 API」を提供している。

サーバーは read-through 原則を守っており、予定そのものを永続化することはない。ツールが呼ばれるたびに Google から取得して返すか、その場で書き戻すだけ。エージェントは予定の一覧・検索に加えて、 空き時間の提案や予定の作成・変更・削除まで行える — Notion Calendar には無い、kichijitsu の差別化要素の一つ。

接続手順

MCP サーバーのエンドポイントは https://kichijitsu.love-rox.cc/mcp 。

対応する MCP 仕様は 2026-07-28 (ステートレス) と 2025-11-25 以前 (initialize ハンドシェイク) の両方。トランスポートは Streamable HTTP で、単一のエンドポイントを使う。クライアントがどちらの世代でも、この URL に設定するだけでよい。公開しているのは tools のみ (resources / prompts は未実装)。

1. MCP トークンを発行する

   kichijitsu アプリ右上の設定(歯車アイコン)を開き、「MCP トークン」セクションの「+ トークンを発行」から発行する(ラベルは任意)。生の値は発行直後に一度だけ表示され、以降は二度と表示されない。その場でコピーしておくこと。

2. Claude Code へ登録する

   発行したトークンを使って、ターミナルから1回登録すればよい。

   claude mcp add --transport http kichijitsu https://kichijitsu.love-rox.cc/mcp --header "Authorization: Bearer <token>"

   登録後は Claude Code を再起動してから使い始めること。

3. Claude Desktop へ登録する

   Claude Desktop はリモートの Streamable HTTP MCP サーバーを直接サポートしていないため、橋渡し役の mcp-remote パッケージを経由する。設定ファイル (macOS では ~/Library/Application Support/Claude/claude_desktop_config.json) に以下を追加する。

   {
     "mcpServers": {
       "kichijitsu": {
         "command": "npx",
         "args": [
           "-y",
           "mcp-remote",
           "https://kichijitsu.love-rox.cc/mcp",
           "--header",
           "Authorization:${AUTH_HEADER}"
         ],
         "env": {
           "AUTH_HEADER": "Bearer <token>"
         }
       }
     }
   }

   Authorization:${AUTH_HEADER}のように : の前後にスペースを入れない書き方は、Claude Desktop (Windows) が引数中のスペースを正しく渡せない既知の問題を避けるための mcp-remote 側の回避策。値は env 側に置けばスペースを含めてよい。設定を保存したら Claude Desktop を再起動する。

使えるツール一覧

現在 8 つのツールを公開している。書き込み系はエージェント側でユーザーへの実行前確認を前提にした説明になっている。

hook からの作業時間記録

Claude Code の SessionStart/Stop hook のような非対話のシェルからは、MCP 接続を経由せず curl 一発で作業実績を記録できる。認証は MCP トークンの Bearer で、値は設定ファイルに直書きせず環境変数から読むこと。

curl -sf -X POST https://kichijitsu.love-rox.cc/api/work-intervals \
  -H "Authorization: Bearer ${KICHIJITSU_MCP_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "start": "'"$SESSION_START_ISO"'",
    "end": "'"$(date -u +%Y-%m-%dT%H:%M:%SZ)"'",
    "repo": "Love-Rox/kichijitsu",
    "branch": "'"$(git branch --show-current)"'",
    "agent": "claude-code"
  }'

成功すると { calendarId, eventId } を 200 で返す。認証失敗は 401、 start >= end・repo 欠落などの入力不正は 400、Google 側の失敗は 502 になる。

運用の注意

デプロイ後・トークン再発行後は、MCP クライアントの再起動が必要になる。ツールのスキーマ (名前・説明・入力) はクライアントが接続時にキャッシュするため、デプロイしただけでは反映されない。反映を確認するときは、まず Claude Code / Claude Desktop を再起動してから検証すること。

同様に、トークンを再発行(＝旧トークンを失効)した場合も、起動中のセッションは旧トークンを掴んだまま 401 が続く。Claude Code はこれを requires re-authorization (token expired) と表示するが、kichijitsu の MCP トークンに 有効期限は無い。この表示が出たら、実際は「トークンが失効/未登録」か「クライアントのセッションが古い」のどちらか。

サーバー側で認証が通ったことがあるかどうかは last_used_at で客観的に判定できる(null のままなら、クライアントが新しいトークンをまだ送れていない)。

トークンの取り扱い