Gagarin Cloud

mcp

mcp.gagarin.cloud — 手軽にデプロイし、安心して保守できます。

エージェントに URL を 1 つ追加すれば、アプリを HTTPS の公開アドレスで実行し、Postgres、Qdrant、Valkey、キュー、またはバケットを用意し、接続可能な対象を設定して、ロールバックできます。アラート、ログ、バックアップ、プロジェクトのメモリも付属し、メールで承認しない限り、何も削除されません。これは Gagarin の API をツールとして提供するもので、ツールは 51 個あり、クライアントが最初にどのツールについて尋ねるべきか判断できるよう、すべてに注釈が付いています。イメージのビルドとプッシュには Docker とソースが必要なため、そのステップはそれらがあるマシンで gg ship を実行します。それ以降は、すべてここで行えます。

https://mcp.gagarin.cloud/mcp

Model Context Protocol は、エージェントが自分には組み込まれていないツールを見つけて呼び出すための仕組みです。これは Gagarin の MCP サーバーであり、コーディングエージェントに Gagarin を追加する方法をインストールではなく URL にするために存在します。プラットフォームを単にドキュメント化するのではなく、インストール可能にする唯一の成果物です。

接続方法は 2 つ、実装は 1 つです。

リモート	https://mcp.gagarin.cloud/mcp、ストリーミング可能な HTTP、Authorization ヘッダー内の認証情報 — OAuth サインインまたは手動で設定します
ローカル	このリポジトリのクローンで npm run stdio を実行します。認証情報は GAGARIN_TOKEN、または gg login が書き込んだファイルから取得します。このサーバーの開発用であり、インストール方法ではありません

サインイン

OAuth を使ったリモート接続。 クライアントには URL だけを渡します。

https://mcp.gagarin.cloud/mcp

Claude、ChatGPT、Claude Code は、接続時にサインインを求めます。クライアントがブラウザーを開き、ユーザーが GitHub または Google でサインインします。認証情報のないリクエストには、認可サーバーとして api.gagarin.cloud を指定する /.well-known/oauth-protected-resource/mcp を指す WWW-Authenticate ヘッダーとともに、401 が返されます。このサーバーはトークンについて何も判断しません。判断するのはエンジンであり、呼び出しのたびに確認します。GAGARIN_MCP_ORIGIN と GAGARIN_ISSUER は、開発環境で 2 つの公開名を上書きします。これらは、クラスター内の Service であり、クライアントがサインインできるアドレスではない GAGARIN_API とは別のものです。

ヘッダーに認証情報を設定するリモート接続。 OAuth でサインインできないクライアントや、サインインさせるべきではないマシン向けです。gg login または gg creds create で取得した認証情報を使います。

{
  "mcpServers": {
    "gagarin": {
      "type": "http",
      "url": "https://mcp.gagarin.cloud/mcp",
      "headers": { "Authorization": "Bearer <your gagarin credential>" }
    }
  }
}

stdio を使ったローカル接続。 クローンしたリポジトリで npm run stdio を実行すると、パイプ経由で同じツールが動作し、gg login が書き込んだファイルを読み込みます。GAGARIN_TOKEN が設定されていれば、そちらを使います。これは開発用であり、意図的に npm には公開していません。このサーバーの目的は、エージェントへの Gagarin の追加をインストールではなく URL にすることです。誰かのノート PC にパッケージを置けば、ツールが変更された日から古くなる src/tools.ts のコピーがもう 1 つできてしまいます。

有効期限切れまたは失効した認証情報も、入口で検出されます。クライアントが再度サインインするのは HTTP 401 の場合だけだからです。すべての POST で、まず呼び出し元のトークンを使ってエンジンの /v1/whoami に問い合わせ、エンジンからの 401 は error="invalid_token" を伴う 401 に変換されます。リクエストごとにクラスター内の呼び出しが 1 回増えますが、キャッシュはありません。記憶されたトークンも保存されたトークンであり、このサーバーは何も保存しないためです。エンジンに到達できない場合や 5xx など、そこで発生したその他の失敗はサインインの問題ではないため、リクエストは続行され、各ツールがエンジン独自のコードでその失敗を報告します。

開発

npm install
npm run build
npm test                 # builds, then node --test over dist/
npm start                # the HTTP server on :8080
npm run stdio            # the same tools over a pipe

内容

パス	内容
src/api.ts	このサーバーが Gagarin とやり取りする唯一の部分です。リクエストを 1 つ送り、エラーエンベロープを 1 つ返します
src/tools.ts	すべてのツールです。それぞれのパス、形式、呼び出し前に必要なルールが記されています
src/server.ts	接続時にクライアントへ伝える内容と、gagarin://guide リソースです。メモリの使い方や、リポジトリがどのプロジェクトに属するかを示す .gagarin.json の注記も含まれます
src/app.ts	mcp.gagarin.cloud です。ステートレスなストリーミング可能 HTTP、リクエストごとのサーバー、OAuth 保護リソースメタデータを扱います
src/http.ts	リスナー、その設定、ドレイン処理です
src/stdio.ts	クローンから開発するための、パイプ経由で同じツールを使う仕組みです
src/credentials.ts	gg login が書き込んだ認証情報ファイルを読み込みます。書き込みは行いません
Dockerfile	mcp.gagarin.cloud が実行するイメージです。ビルドステージでテストを実行します

プロジェクトメモリ

すべてのプロジェクトにはメモリがあります。これは、コードベースに関してエージェントが保存する、小さく永続的な事実です。判断とその理由、慣習、注意点などを保存することで、次のセッションで同じことを再発見せずに済みます。これはレジストリと同様にプロジェクトに組み込まれており、メモリにアクセスする方法はこれらのツールだけです。メモリサービスには独自のアドレスも、gg コマンドも、コンソールページもありません。エンジンはほかのすべてと同様に、呼び出しごとに読み取り可能なユーザー（viewer）と書き込み可能なユーザー（editor）を判断します。

ツール	機能
memory_briefing	プロジェクトについて分かっていることをトークン予算内にまとめます。プロジェクトで最初に呼び出すツールです。focus と paths で内容を調整でき、最後に過去 7 日間の変更が含まれます
memory_search	セマンティック検索とキーワード検索を組み合わせた検索です。クエリを指定しない場合は、ランク順に参照します
memory_get	ID またはキーを指定して、メモリの全文を取得します
memory_related	1 つのメモリからリンクをたどります
remember	事実を 1 つ保存します。ほぼ重複する内容は、衝突したメモリとともに拒否されます。key を指定すると、そのキーを保持するメモリが置き換えられます
memory_update	フィールドを変更し、キーを設定または解除し、ピン留めやアーカイブを行い、引き続き有効であることを confirm するか、異議を唱える dispute を行います
memory_link / memory_unlink	2 つのメモリを関連付けるか、関連付けを解除します
memory_review	メンテナンスを行います。重複の可能性があるもの、孤立したもの、大きすぎるもの、古いもの、未読や異議のあるメモリ、上限までの残りを確認します

エクスポートとインポートにはツールがありません。これらは人やスクリプト向けの機能であり、ツールの定義は呼び出すかどうかにかかわらず、すべてのセッションでトークンを消費するためです。

これらが返すのは、メモリサービス独自の text、つまり予算内に収めたプレーンテキスト形式です。これは以下のルールが適用される、より限定的なケースであり、例外ではありません。レンダリングも引き続きエンジンによるもので、両方を返すと、サービスが節約しようとしているトークンを 2 倍消費してしまいます。text を含まない本文は、ほかの回答と同様に JSON として返されます。

これは翻訳者であり、それ以外の何者でもありません

独自の認証情報もデータベースも持たず、API が下す判断を覆すこともありません。各ツールは、呼び出し元自身のベアラートークンを付けて api.gagarin.cloud を呼び出すだけで、すべての拒否はエンジンの拒否を編集せずにそのまま渡します。

ほかのすべての基盤となるのは、この性質です。このサーバーを持っていても、何も得られません。だからこそ、単一の書き込みゲートの前にパブリックエンドポイントを安全に設置でき、これを弱めるような変更は一切してはいけません。

欠落のように見えるものの、明記しておく価値のある帰結が 2 つあります。

• 回答はエンジンの JSON そのものであり、その要約ではありません。 すべてのサービス、台帳の行、接続には、エンジンが書いた sentence がすでに含まれています。これは、ターミナルとダッシュボードで同じ行の説明が異ならないようにするためです。ここに 3 つ目のレンダラーを設けると、歩調を合わせるべき意見がもう 1 つ増えることになります。
• エラーは [code] message と hint: 行で構成されます。これは gg が出力する形式です。形式を統一することで、Gagarin のスキルを読んだエージェントは、2 つ目の形式を教えなくても、ここから返される内容を理解できます。エンジンがエンベロープ以外の情報も送る場合（memory_duplicate には類似項目が含まれます）、それを捨てずにヒントの後ろに追加します。

意図的に対応していないこと

機械が必要なことが 4 つあり、ここで提供するとプラットフォーム障害のように見える失敗を招きます。

• イメージをビルドしてプッシュする。 gg ship はビルド、プッシュ、デプロイを一体化したコマンドで、ソースがある場所で docker を実行します。ここでの deploy は、すでに Gagarin のレジストリにあるイメージ（CI がプッシュしたタグ、または再指定したタグ）を実行します。イメージをレジストリに登録するのは CLI の役目です。
• トンネルを開く。 gg connect はローカルポートをバインドします。
• ジョブの完了を待つ。 run はほかの書き込みと同様に、リビジョンを送信して返します。gg run は実行が終わるまでブロックし、スクリプト自身の終了コードを返します。これはパイプラインが求める動作です。MCP では、フェーズとコードを確認するために status をポーリングします。
• 承認をクリックする。 これは設計上、受信箱を持つ人間が行います。

また、このリポジトリにはリソースの種類、サイズ、スコープの一覧もありません。それらを管理するのはエンジンであり、エンジンの拒否にはそれらの名前が示されます。ここで z.enum を使うと、別のリポジトリに 2 つ目の一覧を作ることになります。種類が追加された日に誤った一覧になります。このコードベースは、まさに同じ種類の値について、かつて gg で一度この間違いをしています。

実行場所

Kubernetes クラスター内のコントロールプレーンの隣で実行し、サイトやコンソールと並べて Vercel 上では実行しません。 サイトとコンソールは、プラットフォームが停止しても稼働し続け、そのことを伝えるために Scaleway の外で動いています。API に到達できないとき、このサーバーには伝えることが何もありません。これは別の形をとった API そのものなので、ロードバランサーを経由して外に出るのではなく、クラスター内の Service を通じて API にアクセスできる場所に置きます。

Pod は RBAC を持たず、トークンもマウントしない ServiceAccount として、読み取り専用のルートファイルシステム上で実行されます。どれも必要ありません。

main へのプッシュごとにイメージをビルドし、ロールアウトします — .github/workflows/deploy.yml。それを実行できる認証情報は production 環境のシークレットであり、使用できるのは main のみなので、プルリクエストがそれらの認証情報と同じ場所で実行されることはありません。main へのマージはデプロイを意味します。

ツールの追加

src/tools.ts に server.registerTool の呼び出しを 1 つ追加します。名前、呼び出し元にとって最も重要なルールを説明する説明文、zod の形状、そして api.call を記述します。次に src/tools.test.ts に、パス、メソッド、ボディを検証するテストを追加します。静かに間違った状態になりうるのはこれらだけであり、誤ったパスに PUT するデプロイは 404 を返し、サービスが存在しないかのように見えるためです。

API に存在しない機能のためにツールを追加しないでください。このファイルが機能を最初に登場させる場所になるべきではありません。