AI エージェントとの統合

AI Assistant は、既存の TeamCity ワークフローのデバッグと分析に役立つ優れたツールですが、TeamCity UI でのみ利用できます。ただし、場合によっては、外部の AI 搭載ツールから TeamCity を操作したいことがあります。たとえば、空気(英語)や Cursor(英語) のようなエージェント型 IDE を使用している場合、コーディング環境を移動せずに CI/CD タスクを実行したい場合があります。そのためには、エージェントが TeamCity と連携できるツールにアクセスできる必要があります。

これを実現するには、主に CLI ツールと MCP サーバーの 2 つの方法があります。 TeamCity は両方をサポートしているため、まずは各アプローチの概要を簡単に見てみましょう。

MCP: モデルコンテキストプロトコル(英語)は、AI アプリケーションを外部システムに接続するためのオープンソース標準です。外部 AI ソリューションは、特定のエンドポイントに対して認証済みリクエストを送信し、このリソースを操作するためのすぐに使用できるツールの一覧を取得します。
CLI: 製品に CLI サポートが付属している場合、サポートされているコマンドを扱うよう AI エージェントに「教える」ことができます。そのためには、エージェントにスキル、つまり専門的なタスクでパフォーマンスを向上させるために、必要に応じてエージェントが読み込める指示、スクリプト、リソースをまとめた設定が必要です。最低限、スキルとは、特定のタスクを実行する方法をエージェントに伝える詳細な指示を含むシンプルな SKILL.md です。

MCP と CLI のどちらを統合するかは、使用する AI ツールの性質とその環境によって異なります。

環境要件。エージェントスキルを使用するには、関連する CLI ツールをインストールできる環境が必要です。たとえば、Codex、Claude Code、Junie CLI などのローカルで実行されるコードエージェントは、スキルを使用してコマンドを実行したり、ファイルを操作したりできます。これらとは異なり、ChatGPT や Claude などのチャットツールは、CLI ツールを直接使用することはできません。
指示の性質。主な目的が特定のアクションを実行することである場合、CLI の方が自然な選択肢となるでしょう。たとえば、コードエージェントはターミナルコマンドを呼び出して最新のビルドステータスを報告したり、特定のテストスイートを実行したりできます。同時に、MCP に依存するチャットエージェントは、高度な問題調査と分析に優れています。
安全性に関する懸念の安全性は、権限設定とサンドボックス化に大きく依存します。 MCP ツールを使用するエージェントと比較すると、CLI ツールを装備したエージェントを無謀に使用すると、権限設定が広すぎる場合に、より大きな被害をもたらす可能性があります。
実装コスト。ソフトウェアにすでに優れた CLI が備わっていて、ベンダーがすぐに使えるスキルを提供している場合、多くの場合、それをリポジトリにドロップするだけで、サーバー接続を設定することなくすぐに使い始めることができます。 TeamCity CLI には、まさにそれを可能にするすぐに使えるスキルが付属しています。
拡張性。多数のツールを事前に接続すると、かなりのオーバーヘッドが発生し、LLM の利用可能なコンテキストウィンドウが大幅に減少する可能性があります。この問題を軽減するために設計されたさまざまなソリューション (たとえば、Anthropic、ツール検索ツール (英語)) は、スキルよりも MCP ツールへの対応に優れている場合があります。

TeamCity では、 CLI ツールによって、より幅広い統合オプションが提供されます。エージェントは CLI コマンドを使用してエージェントを無効化することや、プロジェクトパラメーターを編集することができますが、TeamCity MCP ツールが現在サポートしているのは、個人ビルドの開始など、開発者向けアクションのより限定された設定です。

CLI スキルは、専用の CLI コマンドがまだ存在しない場合に、エージェントが REST API リクエストを送信する方法も学習させます。その結果、このスキルを持つエージェントは、より幅広い TeamCity タスクを処理することができます。

TeamCity MCP

TeamCity サーバーは、次の AI ツールを公開する <server-url>/app/mcp エンドポイントを公開します：

TeamCity ビルドログ: 対象ビルドの完全なビルドログを取得します。ページネーションとメッセージタイプによるフィルタリング（行全体、または警告とエラーのみ）をサポートしています。ビルド失敗の原因究明に使用します。
TeamCity REST GET: GET メソッド リクエストを TeamCity REST API を使用して送信します：プロジェクトとビルド構成の一覧を返す、最後に成功したビルドを見つける、現在ミュートされている問題を表示する、など。使用可能な操作の一覧は、認証トークンの権限スコープによって異なります。
TeamCity REST POST: POST リクエストを TeamCity REST API 経由で送信します。これには、ビルド構成を編集するリクエストも含まれます。セーフモードでは、デフォルトまたはカスタム設定で新しいビルドをトリガーするための /アプリ/rest/ビルドキュー エンドポイントへの POST リクエストに制限されます。この方法でトリガーされたすべてのビルドには personal=true 属性が付けられます。
TeamCity パイプライン取得能力: AI エージェントが、プロパティ (パラメーター、最適化設定、接続された VCS ルートとリポジトリなど) とともにパイプラインを取得できるようにします。
TeamCity パイプライン送信能力: このツールを使用すると、AI エージェントはパイプラインとそのパラメーターの作成と更新、YAML/Kotlin DSL 設定の編集と検証、VCS 接続のテストなどを行えます。
TeamCity パイプライン削除能力: AI エージェントがパイプラインとその親プロジェクトを完全に削除できるようにします。

これらのツールを取得して使用するには、AI エージェントが TeamCity でトークンベースの認証を行う必要があります。アクセストークンはユーザープロファイルページで発行できます。 TeamCity では、エージェントにトークンを発行したユーザーと同じ権限を付与するか、プロジェクトごとの細かな権限を付与するかを選択できます。

OAuth アクセス

ユーザートークンを発行したり、AI エージェント構成で渡したりせずに、サーバーを追加できます：

{
  "mcpServers": {
        "TeamCity nightly": {
            "type": "http",
            "url": "<TeamCity-server-URL>/app/mcp",
            // Skip setting up auth settings
            //"headers": { "Authorization": "Bearer $TC_AUTH_TOKEN" }
        }
  }
}

   

この場合、サーバーは追加されますが、認証するまで MCP ツールは使用できません。たとえば、Air Desktop で接続をクリックするか、Codex CLI で codex mcp login <server-name> を実行します。

その後、AI クライアントで <TeamCity-server-URL>/pkce/authorize.html ページが開きます。ここで、AI エージェントに付与される権限を確認し、承認をクリックしてアクセストークンを発行できます。

トークンは TeamCity 権限を継承することに注意してください。たとえば、サーバーログを表示できない場合、AI エージェントも表示できません。特定のプロジェクトしか編集できない場合、エージェントにも同じ制限が適用されます。

安全性に関する懸念

TeamCity MCP ツールセットには、ビルド構成、パイプライン、プロジェクトを編集できるツールが含まれています。リスクを減らし、インシデントを回避するには、セットアップとニーズに応じて次の方法を組み合わせてください。

teamcity.ai.mcp.braveMode.enabled 内部プロパティを追加し、セーフモードの場合は偽 (デフォルト) に、ブレイブモードの場合は真に設定します。
セーフモードでは、 TeamCity パイプライン送信能力 と TeamCity パイプライン削除能力 ツールは使用できず、 TeamCity REST POST は個人ビルドをキューに入れることしかできません。編集や削除は一切できません。ブレイブモードでは、これらの制限が解除されます。
細かい権限または読み取り専用権限を使用するには、手動で発行され Bearer 認証経由で渡されるアクセストークンが必要です。読み取り専用トークンを発行するには、スコープをプロジェクトごとの制限に設定し、読み取り専用プリセットを選択します。
OAuth で発行されたトークンは常に TeamCity のすべての権限を継承し、サインイン中にスコープを縮小することはできません。
クライアントにこの機能がある場合は、特定のツールを無効化してください。たとえば、カーソルで作業している場合は、設定 | ツールと MCP で個々のツールをクリックしてオン/オフを切り替えられます。
AI エージェントができることの境界を設定するには、プロンプトとスキルの文言を慎重に選んでください。これは、上記の技術的制御の代わりではなく、補足的な予防策として扱ってください。エージェントは依然として指示を誤読したり無視したりする可能性があります。

最後に、アクセストークンのリクエストレート制限を検討してください。問題のあるエージェントによる偶発的なリクエストの急増を防ぐだけでなく、ドライランモードにより、エージェントを完全にブロックせずに監査ログでリクエストパターンを確認できます。

例

このセクションでは、MCP サーバーを使用して、代表的な AI ツールを TeamCity に接続する方法を説明します。セキュリティを強化するため、 TeamCity アクセストークンを環境変数にエクスポートすることをおすすめします：

export TC_AUTH_TOKEN="your token here"

そうすれば、生の値の代わりに $TC_AUTH_TOKEN 参照を使用できるようになります。

PKCE OAuth 認証を使用するには、認可設定のセットアップを省略します。

Air、Cursor

IDE の設定を開き、以下の JSON スニペットを貼り付けて、グローバル / プロジェクト / ワークスペースサーバーを追加します。

{
  "mcpServers": {
        "TeamCity nightly": {
            "type": "http",
            "url": "<TeamCity-server-URL>/app/mcp",
            "headers": {
                "Authorization": "Bearer $TC_AUTH_TOKEN"
            }
        }
  }
}

    

Claude

設定 | 開発者 | 構成を編集ファイルを以下のように変更してください。

{
  "mcpServers": {
    "my-mcp-server": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "<TeamCity-server-URL>/app/mcp",
        "--header",
        "Authorization: Bearer ${TC_AUTH_TOKEN}"
      ]
    }
  }
}

    

Codex

~/.codex/config.toml ファイルに以下のコードスニペットを追加してください。

[mcp_servers.buildserver]
url = "<TeamCity-server-URL>/app/mcp"
[mcp_servers.buildserver.http_headers]
Authorization = "Bearer $TC_AUTH_TOKEN"

    

または、以下のターミナルコマンドを実行してください。

codex mcp add buildserver --url <TeamCity-server-URL>/app/mcp --bearer-token-env-var $TC_AUTH_TOKEN

    

Claude Code

以下のターミナルコマンドを実行してください。

claude mcp add --transport http buildserver <TeamCity-server-URL>/app/mcp --header "Authorization: Bearer $TC_AUTH_TOKEN"

    

TeamCity コマンドラインインターフェース

TeamCity CLI は、任意のマシンにインストールして、ビルドの実行、ビルドログの確認、エージェントの管理、ターミナルコマンドによるその他の操作を行えるスタンドアロンツールです。

Homebrew (推奨)：

brew install jetbrains/utils/teamcity

インストールスクリプト：

curl -fsSL https://jb.gg/tc/install | bash

Winget (推奨)：

winget install JetBrains.TeamCityCLI

PowerShell (インストールスクリプト)：

irm https://jb.gg/tc/install.ps1 | iex

AI エージェントがこのツールと連携できるようにするには、 teamcity skill install を実行してください。必要に応じて、対象のエージェントとプロジェクトを指定することもできます。

teamcity skill install
teamcity skill install --project
teamcity skill install --agent claude-code --agent cursor

  

このコマンドは、エージェント固有のスキルをデフォルトの場所にインストールするため、サポートされているエージェントはそれらを自動的に検出して使用できます — 追加のセットアップは不要です。

スキルがインストールされたら、エージェントに次のような TeamCity 関連タスクを実行するよう依頼できます：

“Start a new build in TeamCity configuration related to this project.”

“Find the latest failed build in the 'My Awesome App' TeamCity project 
and investigate it: why it failed and how to resolve this issue.”

“Find all TeamCity investigations assigned to me and reassign them to
user 'johndoe'.”

詳細については、次の記事を参照してください: TeamCity CLI AI エージェントスキル。

アクセストークンのレート制限

TeamCity は、複数のサーバーノードにわたる数百人のユーザーからの並列アクセスを処理するように設計された CI/CD ソリューションです。まれに、外部ツールとの連携によってリクエストが急増し、UI のパフォーマンスが低下することがあります。これは通常、AI エージェントなどの外部ツールが同時に数十件のリクエストを送信するなど、設定ミスが原因で発生します。

この問題を防止または解決するには、 teamcity.http.limiter.maxParralelRequestPerUser 内部プロパティを使用して、アクセストークンごとに許可される同時 HTTP リクエストの数を制限します。例: 次の設定では、トークンベースのツールの同時リクエスト数を 20 に制限します。

teamcity.http.limiter.maxParralelRequestPerUser=20

トラブルシューティングを行うには、制限値を希望の値に設定し、 teamcity.http.limiter.dryRun=true プロパティを有効にしてください。このモードでは、TeamCity は過剰なリクエストをブロックせず、監査ログに記録します。

2026 年 9 月 11 日