CircleCIを使ったCICDパイプラインのセットアップや改善、あるいはAIコーディングでのCIエラー対応を Cursor が自律的に行う仕組みが、先日リリースされました。

１つはセットアップ方法などのナレッジを整理してまとめた Agent Skill、もう１つは CircleCI のデータ・APIに効率的かつ安全にアクセスできる仕組みとしての MCP サーバーです。

この記事では、Cursor に CircleCI の Agent Skill と MCP サーバーを連携させ、CI設定ファイルの検証を自動化させる方法を紹介します。

CircleCI の MCP サーバーは、Remote MCPと CLI を利用するローカル版の 2 つを用意しています。

ジョブの失敗調査や日々の分析などにはどこからでも利用可能な Remote MCP版が便利です。ただし実際の開発や config の作成や検証などをエージェントに任せる場合は CLI 版の方がツールや機能が豊富です。

https://circleci.com/docs/guides/toolkit/circleci-mcp-overview/#hosted-vs-cli-mcp

MCP サーバーを登録する

CLI版のMCPサーバーは CircleCI CLI コマンドを利用して登録します。CLIはversion 1系を利用するため、事前にアップグレードを実施してください。

Cursor への登録には circleci mcp cursor enable を実行します。このコマンドは Cursor の MCP 設定ファイルを書き換えるため、出力 1 行目に表示される対象パスが、自分の使っている設定（ユーザー単位の ~/.cursor/mcp.json か、プロジェクト単位の .cursor/mcp.json）と一致しているかを確認してください。

$ circleci mcp cursor enable
Using config path "/Users/hidetaka/.cursor/mcp.json"
Backing up config file at "/Users/hidetaka/.cursor/mcp.backup.json"
Successfully enabled MCP server: "circleci-cli"
  Type: stdio
  Command: /opt/homebrew/bin/circleci
  Args: [mcp start]

書き換え前に mcp.backup.json が作られるため、元に戻したい場合はこのファイルを使えます。

Cursor を再起動するかウィンドウをリロードすると、設定画面の Tools & MCPs に circleci-cli が並びます。

CLI のコマンドがそのままツールになるため、利用できるツールの数は、コマンドの追加や変更に伴って変動します。表示を展開すると、circleci_config_validate のような config 系のツールが確認できます。

これで CircleCI MCPサーバーの設定は完了です。

Agent Skill を入れる

MCPサーバーだけを使うこともできますが、より効果的に使うには Agent Skillも追加することをお勧めします。CircleCI は AI エージェント向けの Agent Skill を CircleCI-Public/skills で公開しています。2026 年 8 月 6 日時点では 6 件あります。

Agent Skill	用途
`circleci-config`	config.yml の実行時間・安定性・保守性の改善
`circleci-builds`	失敗したジョブの診断とフレーキーテストの特定
`circleci-cli`	CLI での日常操作。config 検証、実行の監視、再実行
`circleci-smarter-testing`	Smarter Testing のオンボーディングと `test-suites.yml` の作成
`onboarding`	組織作成から GitHub App 連携、プロジェクト作成までの初期設定
`chunk`	Chunk の設定と利用

Cursor でスキルを追加するには、skills CLI を使い、GitHub リポジトリから直接インストールします。-g はユーザーディレクトリへのインストール、--agent cursor は対象を Cursor に限定するフラグです。

$ npx skills add CircleCI-Public/skills -g --agent cursor
◇  Found 6 skills
◆  Select skills to install
│   ○ chunk
│   ○ circleci-builds
│   ○ circleci-cli
│   ● circleci-config
│   ○ circleci-smarter-testing
│ ❯ ● onboarding

◇  Installation Summary ─────────────╮
│  ~/.agents/skills/circleci-config  │
│    copy → Cursor                   │
│  ~/.agents/skills/onboarding       │
│    copy → Cursor                   │
├────────────────────────────────────╯

スペースキーで選択します。ここで選んだのは circleci-config と onboarding の 2 件です。Cursor は Agent Skill を .agents/skills/、.cursor/skills/、~/.agents/skills/、~/.cursor/skills/ から自動的に読み込むため（Cursor のドキュメント）、インストール先の ~/.agents/skills/ に置かれたままで利用できます。

Cursor を再起動すると、Customize の Skills タブに追加された Agent Skill が並びます。

検証を依頼する

では実際にこの２つを使ってみましょう。

今回 Cursor に出した指示は、「既存の config.yml が適切かどうかを検証し、プロジェクトに合った YAML を作り直してください」という内容です。Agent Skill は説明文を見てエージェントが必要と判断したときに読み込まれるため、指示には「必要に応じてスキル活用せよ」という一文を添えています。

エージェントは ~/.agents/skills/circleci-config/references/ の cache-optimization.md と persisting-data.md を読み込んでから、キャッシュ設計の妥当性を現行プロジェクトの内容と突き合わせています。この参照資料には、Caching strategies を出典とするキャッシュ ROI やキー設計の基準が書かれています。

MCP サーバーだけでもレビューできるように見えますが、circleci_config_validate が返すのは設定がコンパイルできるかどうかと検出されたエラーです。キャッシュキーがコミット SHA になっていて一度しかヒットしない、という設計上の問題は、YAML として妥当なため検証を通過します。この判断に必要な参照資料を持っているのが Agent Skill 側です。

生成 AI による提案は非決定的です。エージェントが提示した変更は、そのまま適用せずに circleci config validate で検証し、変更前後のジョブ実行時間とキャッシュのヒット状況を CircleCI のダッシュボードで比較してから取り込んでください。

うまく動かないときに確認する順序

MCP サーバーのツールが出てこない場合は、Cursor を再起動します。設定ファイルへの書き込みが済んでいても、起動中のセッションには反映されません。それでも表示されないときは、circleci mcp cursor list で登録内容と対象パスを確認してください。

認証エラーが出る場合は、circleci auth login を実行し直すか、CIRCLE_TOKEN が対象プロジェクトへのアクセス権を持つユーザーの有効なトークンを指しているかを確認します。

Agent Skill が使われた形跡がない場合は、Customize の Skills タブに表示されているかを見ます。表示されていないなら Agent Skill のディレクトリが直下に SKILL.md を持つ構成かを確認し、表示されているのに読み込まれないなら、依頼に Agent Skill の説明文と重なる語（キャッシュ、config.yml、実行時間など）を含めてください。呼び出しの判断はエージェント側にあります。

参考リンク

CircleCI MCP overview — hosted と CLI 内蔵の比較、公開ツールの一覧、トラブルシューティング
Connecting to the CircleCI CLI MCP — circleci mcp cursor enable と disable の一次情報
CircleCI CLI reference — circleci mcp のサブコマンドとフラグ
Discuss のフィードバックスレッド — プレビュー期間中の挙動やツール変更の窓口