Typesense Cloud MCPをClaude Codeにつないで検索クラスタを操作する

Typesense Cloud MCPは、検索エンジンTypesenseのマネージドサービスが公開しているリモートMCPサーバーです。Claude Codeにつなぐと、クラスタの作成、コレクションの設計、データの投入、検索のチューニングまでを、会話の中で進められます。

接続先のURLは https://cloud.typesense.org/mcp/v1 の1本です。追加のコマンドは1行で済みます。ただ、この記事で重く扱うのは、つないだあとにエージェントへどこまで権限を渡すかです。クラスタの作成は課金に、終了は削除に直結するからです。

Typesense Cloud MCPで何を任せられるか

提供元はこのMCPを、クラスタの作成と設定、コレクションの構築、データの投入、検索のチューニング、メトリクスの確認を会話から行うための入口と説明しています。何を許すかは接続時に自分で決め、いつでも切断できます。

通信方式はStreamable HTTPで、認証はOAuthです。この2つに対応したクライアントなら同じ手順でつながります。Claude Codeは --transport http で対応しています。

エージェントが使えるツールは次の8種類と、フィードバック用の1つです(表では最後の2つを1行にまとめています)。

プロンプトでツール名を指定する必要はありません。エージェントはツールの説明を読んで選ぶので、やりたいことを日本語で書けば足ります。

Claude Codeに追加して認証する

追加は1コマンドです。

claude mcp add --transport http typesense-cloud \
  https://cloud.typesense.org/mcp/v1

typesense-cloud の部分は接続名です。任意の名前に変えられますが、後で複数アカウントを使い分ける場合の目印になります。

追加しただけでは、まだブラウザの同意を済ませていません。次の手順で認証します。

追加後の状態は、シェルからも見られます。claude mcp list は各サーバーの横に接続状態を出し、認証が済んでいないものは Needs authentication と表示されます。

claude mcp list
claude mcp get typesense-cloud

チームで同じ接続を共有したい場合は、--scope project を付けると .mcp.json に書かれます。ただしOAuthの承認は人ごとのものです。ファイルを共有しても、各メンバーが自分のアカウントで同意画面を通る必要があります。

同意画面で権限を決める

接続の質を決めるのは、この画面です。サインイン後に、エージェントが働くアカウントと権限を選んでConnectを押します。

権限は5つのプリセットから選べます。

既定のBuildは、クラスタの終了と複製、請求の読み取りを含みません。作れるキーも、アプリ向けの検索専用キーだけです。まず試すだけなら、この既定のままで過不足はありません。

プリセットとは別に、権限を1つずつ入り切りすることもできます。クラスタ側は clusters:create、clusters:configure、clusters:terminate、billing:read のように分かれ、データ側は data:view、data:search、data:full_access などに分かれます。

課金とデータ削除に関わる権限

扱いに注意したいのは、次の3つです。

• clusters:create: クラスタを作ります。作成分はアカウントに課金されます
• clusters:configure: サイズや構成を変えます。課金に影響する変更です
• clusters:terminate: クラスタを終了します

データ側の data:full_access も、コレクションの削除やドキュメントの一括削除を含みます。検索のチューニングだけを任せたいなら、Search and curateまで絞れば、データそのものを壊す経路を最初から断てます。

チームアカウントでは自分のロールが上限になる

チームアカウントの場合、同意画面で選べる権限は、自分のRBACロールが持つ範囲までに制限されます。たとえばcuratorロールの人は、検索とキュレーション系の権限しか足せません。許されない項目は、理由付きでグレーアウトします。

権限を足したくなったとき

権限は接続時に決まります。広げたいときは、エージェント側でMCPサーバーを切断し、もう一度追加して認証し直します。そのときに同意画面がまた出るので、新しい権限の組を選べます。

ツール自体は、どの接続にも全部見えています。ただし呼び出しのたびに、付与した権限と照合されます。権限が足りずに断られると、エージェントには足りない権限の名前が返るので、何を許すか考えるきっかけになります。

変更を伴う manage_cluster、documents、change_cluster_data の3つは、破壊的な操作として注釈が付いています。この注釈に従うクライアントでは、実行前に確認が入ります。

最初のプロンプトを投げる

接続できたら、提供元が用意した起点のプロンプトを日本語にして投げます。

Typesense Cloud MCPを使って、検索環境を用意してください。
クラスタを作り、./data/products.jsonl のデータを投入して、
最初の検索まで動かしてください。

提供元の説明では、エージェントは無料枠のクラスタを作り、データの形を尋ね、スキーマを提案し、データを取り込み、確認用の検索を実行します。スキーマの提案を受けた時点で、フィールド名や型を自分の目で確かめてから進めると、手戻りが減ります。

続けて頼める作業の例

提供元のdocsには、作業別の依頼例が並んでいます。日本語に直した形で、いくつか挙げます。

• データ: 「products のスキーマと数件のサンプルドキュメントを見せて」「brand をファセットのフィールドに追加して」
• 検索: 「trail running を products と articles で同時に検索して、それぞれ上位3件を出して」
• チューニング: 「在庫ありの商品を在庫切れより上にして」「sneakers で検索したら商品123を先頭に固定して」「sneakers が trainers にも一致するようにシノニムを足して」
• 基盤: 「直近24時間のCPUとメモリを見せて」「高可用性をオンにして、変更を午前2時(UTC)に予約して」
• 請求: 「直近3回の請求書を見せて」

注目したいのは、Typesenseのdocs自体も引けることです。search_typesense_docs は、接続中のクラスタが動いているバージョンに合わせてdocsを検索します。パラメータの名前や挙動をバージョン違いのページから拾ってしまう事故が起きにくくなります。たとえば「drop_tokens_threshold は何をするもので、いくつにすべきか」のような質問が、そのまま通ります。

Claude Code側で押さえておく運用

提供元の手順にはCodex CLI向けの工夫が1つ載っています。プロジェクトの AGENTS.md に、Typesense Cloudの操作ではMCPのツールを使うよう1行書いておく方法です。キーを人に尋ねる動きを避けるための手当てです。

Claude Codeでは、同じ役割を CLAUDE.md が担います。例えば次のように書けます(提供元の例文に沿った形です)。

## 検索基盤
- Typesense Cloudのアカウント・クラスタ・コレクションに関する作業は、
  typesense-cloud のMCPツールを使う
- クラスタの作成・サイズ変更・終了は、実行前に内容を私に確認する

2行目は提供元の文面にはない、この記事での追加です。権限をBuildに絞っていても、課金が生じるクラスタ作成やサイズ変更は、人の確認を挟んでから進めると安全です。

もう1つ、同時に使うMCPサーバーが増えると、ツール定義がコンテキストを圧迫します。複数のサーバーを並べる前に、MCPのトークン消費の仕組みを確認しておくと判断しやすくなります。

大きなデータの取り込みは手元のcurlで行われる

投入できるデータ量には、1回の呼び出しごとの上限があります。

これを超える取り込みと、すべてのエクスポートでは、エージェントがcurlコマンドを返します。そのコマンドを自分のマシンで実行すると、データがマシンとクラスタの間を直接流れます。コマンドは、その作業1回のために作られる一時キーを使います。対象のコレクションと操作に限定されていて、有効期間は24時間です。キーは一度だけ取得され、手元の非公開ファイルに保存されます。

つまり、Claude Codeのようにシェルを持つクライアントなら、大量データもコマンド経由で処理できます。claude.aiやChatGPTのようにコマンドを実行できないクライアントは、インラインの上限の範囲内に収まります。

エージェントはクラスタの管理者キーを受け取りません。データ操作は、Typesense Cloudがサーバー側で保持しているキーで行われます。

無料枠と課金の分かれ目

新しいアカウントは、支払い方法なしで無料枠のクラスタを1つ作れます。構成は0.5GBのメモリ、バースト可能な2 vCPU、1ノードです。

無料枠を超えるものを作るには、支払い方法か、新しいクラスタに十分な前払いクレジットが要ります。構成の変更と複製には、支払い方法か、前払いクレジットの正の残高が必要です。Typesenseサーバーのバージョンアップは例外で、無料枠のクラスタでも常に行えます。

支払い方法が必要な場面になると、エージェントがそう伝え、無料枠に収まる部分的なデータでの試行を提案します。試す段階では、このやり取りがそのまま歯止めになります。

レート制限は接続ごとに、データ呼び出し(検索、ドキュメント、読み書き)が1分あたり300回、クラスタ管理の操作が1分あたり30回です。大量のドキュメントを1件ずつ投入させる依頼は避け、まとめて取り込ませる指示にするほうが、上限に当たりにくくなります。

ブラウザなしで動かす(CI・サーバー向け)

ブラウザを開けない環境では、OAuthの代わりに、クラスタ管理APIキーをBearerトークンとして渡せます。

claude mcp add --transport http typesense-cloud \
  https://cloud.typesense.org/mcp/v1 \
  --header "Authorization: Bearer ${TYPESENSE_CLOUD_MANAGEMENT_API_KEY}"

キーは、作成時に表示されたとおりに使います。この方式で使えるのは、クラスタ向けの4ツール(whoami、search_typesense_docs、get_clusters、manage_cluster)だけです。データを触るツールは、サインインした人として動くため、ブラウザでの接続が要ります。

そのためヘッドレスなエージェントの役割は、クラスタを用意してキーを発行するところまでです。その後のデータ操作はTypesenseのサーバーAPIを直接使う形になります。

クラスタAPIキーの受け渡し

manage_cluster は、クラスタの管理者キーと検索専用キーを発行できます。どちらも全コレクションが対象で、期限はありません。キーは会話に表示されません。エージェントは、キーを5分以内に1回だけ取得するcurlコマンドを受け取り、キーは手元の非公開ファイルに保存されます。シェルを持たないclaude.aiなどは、レスポンスの中で直接受け取る形になります。

アプリケーションには検索専用キーを渡し、管理者キーはサーバー側に置きます。data:search を持つ接続は、ロールがキー管理を許していれば、アプリ向けの検索専用キーをクラスタに直接作れます。この場合、管理者キーを発行しなくても「カタログをアプリから検索できるようにする」までが完結します。コレクションや期限を限定した鍵が必要なら、エージェントに作成を頼む形です。

つながらないとき・動かないときの切り分け

複数のTypesenseアカウントを使いたい場合は、同じURLを別の接続名で追加します。1つの接続は1つのアカウントにだけ結びつくためです。アカウントの所有者には、新しい接続が承認されるたびにメールが届きます。接続の一覧はAccountのConnected appsで確認でき、そこから切断もできます。

検索の運用を任せる前に決めておきたいこと

このMCPは、検索クラスタの構築を速くします。一方、ここまで見たとおり、速さは権限の広さと表裏一体です。

進め方の一例として、立ち上げの段階ではBuildで接続し、クラスタとスキーマを固めます。運用に入ったら、検索の調整だけを頼む接続をSearch and curateで別に作ります。権限の違う接続を別名で用意しておけば、日々の作業で破壊的な操作に手が届く状態を避けられます。

同じ考え方はほかのサービスにも当てはまります。ホスティングのmittwald MCPの記事ではAPIトークンの権限の絞り方を、データベースのCouchbaseプラグインの記事では稼働中クラスタに対するスキルの使い方を扱っています。マネージドDBを触らせる場合の手順は、Cloud SQL for PostgreSQLプラグインの記事が参考になります。

よくある質問

Claude Codeを入れていなくても使えますか

使えます。claude.aiとClaude Desktopでは、CustomizeからConnectorsを開き、カスタムコネクタとして同じURLを貼ります。ただしコマンドを実行できないため、大きなデータの取り込みはインラインの上限内に収まります。