Claude Code ガイド

Appearance

原文（日本語に翻訳） ​

エージェントフロントマターの mcpServers が --agent フラグ経由のメインスレッドエージェントセッションで読み込まれるようになりました。

原文（英語） ​

Agent frontmatter mcpServers are now loaded for main-thread agent sessions via --agent

概要 ​

.claude/agents/ に定義したエージェントファイルのフロントマターに mcpServers を記述しても、--agent フラグで起動したメインスレッドセッションでは反映されないという制限がありました。この更新により、--agent で起動したエージェントでも mcpServers フロントマターが正しく読み込まれ、エージェント専用のMCPサーバー設定を活用できるようになりました。

基本的な使い方 ​

エージェントファイルのフロントマターに mcpServers を定義します。

markdown
---
name: my-agent
description: カスタムMCPサーバーを使うエージェント
mcpServers:
  my-db-server:
    command: npx
    args: ["-y", "my-db-mcp-server"]
  my-api-server:
    command: node
    args: ["./mcp-servers/api-server.js"]
---

このエージェントはデータベースとAPIサーバーにアクセスできます。

--agent フラグで起動すると、フロントマターのMCPサーバーが自動的に読み込まれます。

bash
claude --agent my-agent "データベースのスキーマを確認してください"

実践例 ​

データベース操作エージェントの定義 ​

markdown
---
name: db-analyst
description: PostgreSQLデータベースを分析するエージェント
mcpServers:
  postgres:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-postgres"]
    env:
      POSTGRES_CONNECTION_STRING: "postgresql://localhost/mydb"
---

PostgreSQLデータベースを分析し、クエリの最適化提案を行います。
bash
# --agent で起動するとmcpServersが自動読み込みされる
claude --agent db-analyst "先月の売上データを分析してください"

複数MCPサーバーを持つエージェント ​

markdown
---
name: full-stack-agent
description: フロントエンドとバックエンドの両方を操作するエージェント
mcpServers:
  github:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_TOKEN: "${GITHUB_TOKEN}"
  filesystem:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"]
---

SDKからエージェントを起動 ​

python
import subprocess

result = subprocess.run(
    ["claude", "--agent", "db-analyst", "--print", "テーブル一覧を表示"],
    capture_output=True,
    text=True
)
print(result.stdout)

注意点 ​

  • セキュリティ上の理由から、プラグインのサブエージェントは mcpServers フロントマターをサポートしていません
  • --agent で起動するメインスレッドエージェントでのみ有効です（子サブエージェントとは挙動が異なります）
  • MCPサーバーの設定は settings.json のグローバル設定より優先される場合があります

関連情報 ​