Claude Codeチーム運用ガイド - managed設定とポリシー管理

はじめに

チームでClaude Codeを導入する際、個人ごとに異なる設定や許可されるMCPサーバーがバラバラでは、セキュリティリスクの増大や開発体験の不統一を招きます。特にエンタープライズ環境では、IT部門がポリシーを一元管理し、組織全体で統一されたClaude Code環境を構築することが重要です。

本記事では、managed-mcp.jsonによるMCPサーバーの一元管理、allowedMcpServers/deniedMcpServersによるポリシー制御、settings.jsonのチーム展開戦略、そしてOpenTelemetryを活用した監視とログ収集について解説します。この記事を読むことで、以下のことができるようになります。

managed-mcp.jsonでチーム全体のMCPサーバーを一元管理する
MCPサーバーの許可/拒否ポリシーを設定し、セキュリティを強化する
settings.jsonをチームに効果的に展開する
OpenTelemetryを使用してClaude Codeの利用状況を監視・分析する

実行環境

オペレーティングシステム: macOS 10.15以上、Ubuntu 20.04以上/Debian 10以上、Windows 10以上（WSL 1/2またはGit for Windows）
ハードウェア: 4GB以上のRAM
Node.js 18以上（npmインストールの場合のみ必要）
インターネット接続（認証およびAI処理に必要）
シェル環境: Bash、Zsh、またはFish推奨

前提条件

コマンドライン操作の基礎知識
Gitの基本操作（clone、commit、push等）
プログラミングの基礎知識（言語は問わない）
Claude.aiまたはAnthropic Consoleアカウント
Claude Codeのインストールと認証が完了していること
IT管理者権限（Managed設定を配置する場合）

チーム運用における設定の階層構造

Claude Codeのチーム運用では、4つの設定スコープを理解し、適切に活用することが重要です。

flowchart TB
    subgraph "設定スコープの優先順位"
        A[Managed設定<br>/system/managed-settings.json] --> B[コマンドライン引数]
        B --> C[Local設定<br>.claude/*.local.json]
        C --> D[Project設定<br>.claude/settings.json]
        D --> E[User設定<br>~/.claude/settings.json]
    end
    
    A -.- A1[IT部門が管理<br>ユーザーは上書き不可]
    D -.- D1[チームで共有<br>Git管理]
    E -.- E1[個人の好み<br>全プロジェクト適用]

この階層構造により、組織全体のポリシー（Managed）からチーム共有の設定（Project）、個人の好み（User）まで、柔軟かつセキュアな設定管理が可能です。

各スコープの配置場所

スコープ	macOS	Linux	Windows
Managed	/Library/Application Support/ClaudeCode/	/etc/claude-code/	%PROGRAMDATA%\ClaudeCode\
User	~/.claude/	~/.claude/	%USERPROFILE%.claude\
Project	.claude/（リポジトリ内）	.claude/（リポジトリ内）	.claude/（リポジトリ内）
Local	.claude/*.local.json	.claude/*.local.json	.claude/*.local.json

managed-mcp.jsonによるMCPサーバー一元管理

managed-mcp.jsonは、IT部門が組織全体で使用可能なMCPサーバーを定義するためのファイルです。このファイルに記述されたMCPサーバーは、すべてのユーザーのClaude Codeセッションで自動的に利用可能になります。

managed-mcp.jsonの配置場所

OS	パス
macOS	/Library/Application Support/ClaudeCode/managed-mcp.json
Linux	/etc/claude-code/managed-mcp.json
Windows	%PROGRAMDATA%\ClaudeCode\managed-mcp.json

managed-mcp.jsonの基本構造

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29


{
  "mcpServers": {
    "company-github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "description": "社内GitHub連携"
    },
    "company-sentry": {
      "type": "http",
      "url": "https://mcp.sentry.dev/mcp",
      "description": "エラー監視・デバッグ"
    },
    "company-slack": {
      "type": "http",
      "url": "https://mcp.slack.com/mcp",
      "description": "Slack連携（承認済みチャンネルのみ）"
    },
    "internal-db": {
      "type": "stdio",
      "command": "/opt/claude-code/mcp/db-server",
      "args": ["--config", "/etc/claude-code/db-config.json"],
      "env": {
        "DB_HOST": "internal.db.company.com",
        "DB_PORT": "5432"
      },
      "description": "社内データベース（読み取り専用）"
    }
  }
}

MCPサーバータイプの選択

managed-mcp.jsonでは、3種類のトランスポートタイプを使用できます。

タイプ	用途	設定例
http	クラウドベースのMCPサーバー	GitHub、Sentry、Slack等
sse	SSEベースのリモートサーバー（非推奨）	一部レガシーサービス
stdio	ローカル実行のMCPサーバー	社内ツール、カスタムサーバー

環境変数の活用

managed-mcp.jsonでは環境変数を展開できます。これにより、機密情報を設定ファイルに直接記述せずに管理できます。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


{
  "mcpServers": {
    "secure-api": {
      "type": "http",
      "url": "${COMPANY_MCP_BASE_URL:-https://mcp.company.com}/api",
      "headers": {
        "Authorization": "Bearer ${COMPANY_MCP_TOKEN}"
      }
    }
  }
}

環境変数はシステム全体、またはユーザーごとに設定できます。

1
2
3


# macOS/Linux: /etc/profile.d/claude-code.sh
export COMPANY_MCP_BASE_URL="https://mcp.company.com"
export COMPANY_MCP_TOKEN="your-organization-token"

allowedMcpServers/deniedMcpServersによるポリシー制御

IT部門は、ユーザーが追加できるMCPサーバーを制限することで、セキュリティポリシーを強制できます。managed-settings.jsonのallowedMcpServersとdeniedMcpServers設定を使用します。

ポリシー制御の設定

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


{
  "mcpServers": {
    "allowedMcpServers": [
      "https://api.githubcopilot.com/*",
      "https://mcp.sentry.dev/*",
      "https://mcp.slack.com/*",
      "https://mcp.notion.com/*",
      "https://mcp.linear.app/*",
      "https://mcp.company.com/*"
    ],
    "deniedMcpServers": [
      "https://*.untrusted.com/*",
      "http://*"
    ]
  }
}

ポリシーの評価順序

MCPサーバーの許可/拒否は以下の順序で評価されます。

flowchart TD
    A[MCPサーバー追加リクエスト] --> B{deniedMcpServersに<br>マッチ?}
    B -->|Yes| C[拒否]
    B -->|No| D{allowedMcpServersに<br>マッチ?}
    D -->|Yes| E[許可]
    D -->|No| F{allowedMcpServersが<br>空?}
    F -->|Yes| G[許可（デフォルト）]
    F -->|No| H[拒否]

パターンマッチングの構文

MCPサーバーのURLパターンには、以下のワイルドカードが使用できます。

パターン	説明	例
`*`	任意の文字列にマッチ	`https://mcp..com/`
`?`	任意の1文字にマッチ	`https://mcp?.company.com/*`

実践的なポリシー設定例

以下は、エンタープライズ環境で推奨されるポリシー設定の例です。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


{
  "mcpServers": {
    "allowedMcpServers": [
      "https://api.githubcopilot.com/*",
      "https://mcp.sentry.dev/*",
      "https://mcp.slack.com/*",
      "https://mcp.notion.com/*",
      "https://mcp.linear.app/*",
      "https://mcp.asana.com/*",
      "https://mcp.company.com/*",
      "https://*.internal.company.com/*"
    ],
    "deniedMcpServers": [
      "http://*",
      "https://*.untrusted-domain.com/*",
      "https://mcp.competitor.com/*"
    ]
  },
  "permissions": {
    "deny": [
      "WebFetch(http://*)",
      "Bash(curl:*)",
      "Bash(wget:*)"
    ],
    "disableBypassPermissionsMode": "disable"
  }
}

制限的なポリシー（ホワイトリスト方式）

セキュリティを最優先とする環境では、明示的に許可されたサーバーのみを使用可能にします。

1
2
3
4
5
6
7
8


{
  "mcpServers": {
    "allowedMcpServers": [
      "https://mcp.company.com/*"
    ],
    "deniedMcpServers": []
  }
}

この設定では、https://mcp.company.com/配下のMCPサーバーのみが許可され、それ以外のすべてのMCPサーバーは拒否されます。

settings.jsonのチーム展開戦略

チーム全体で統一された開発体験を提供するため、settings.jsonを効果的に展開する戦略を解説します。

展開レベルの使い分け

flowchart LR
    subgraph "組織全体"
        A[managed-settings.json<br>IT部門管理]
    end
    
    subgraph "チーム/リポジトリ"
        B[.claude/settings.json<br>Git管理]
    end
    
    subgraph "個人"
        C[~/.claude/settings.json<br>ローカル]
        D[.claude/settings.local.json<br>ローカル]
    end
    
    A --> B --> C
    A --> B --> D

managed-settings.jsonの展開（組織全体）

IT部門がシステムディレクトリに配置し、組織全体に強制するポリシーを定義します。

macOSでの配置例

1
2
3
4
5
6


# ディレクトリ作成
sudo mkdir -p "/Library/Application Support/ClaudeCode"

# 設定ファイルを配置
sudo cp managed-settings.json "/Library/Application Support/ClaudeCode/"
sudo chmod 644 "/Library/Application Support/ClaudeCode/managed-settings.json"

Linuxでの配置例

1
2
3
4
5
6


# ディレクトリ作成
sudo mkdir -p /etc/claude-code

# 設定ファイルを配置
sudo cp managed-settings.json /etc/claude-code/
sudo chmod 644 /etc/claude-code/managed-settings.json

Windowsでの配置例

1
2
3
4
5


# ディレクトリ作成
New-Item -ItemType Directory -Path "$env:PROGRAMDATA\ClaudeCode" -Force

# 設定ファイルを配置
Copy-Item managed-settings.json "$env:PROGRAMDATA\ClaudeCode\"

Project設定の展開（チーム共有）

リポジトリの.claude/settings.jsonに配置し、Gitで管理します。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


{
  "permissions": {
    "allow": [
      "Bash(npm run:*)",
      "Bash(npx:*)",
      "Bash(pnpm:*)",
      "Bash(yarn:*)",
      "Bash(git status)",
      "Bash(git diff:*)",
      "Bash(git log:*)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Read(./config/credentials.json)",
      "Bash(rm -rf:*)",
      "Bash(sudo:*)"
    ]
  },
  "env": {
    "NODE_ENV": "development",
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1"
  }
}

新規プロジェクトへの展開テンプレート

組織内の新規プロジェクトに展開するためのテンプレートを用意することを推奨します。

.claude/settings.json（テンプレート）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


{
  "$schema": "https://code.claude.com/schemas/settings.json",
  "permissions": {
    "allow": [
      "Bash(npm run:*)",
      "Bash(npx:*)",
      "Bash(git status)",
      "Bash(git diff:*)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  },
  "attribution": {
    "commit": "Co-Authored-By: Claude <claude@anthropic.com>",
    "pr": ""
  },
  "env": {
    "NODE_ENV": "development"
  }
}

.claude/CLAUDE.md（テンプレート）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29


# プロジェクト概要

[プロジェクトの説明を記述]

## 技術スタック

- フレームワーク: [使用フレームワーク]
- 言語: [使用言語]
- データベース: [使用DB]

## よく使うコマンド

- 開発サーバー起動: `npm run dev`
- テスト実行: `npm run test`
- ビルド: `npm run build`
- リント: `npm run lint`

## コーディング規約

@docs/coding-standards.md

## ディレクトリ構造

~~~text
src/
├── app/          # アプリケーションコード
├── components/   # 共通コンポーネント
├── lib/          # ユーティリティ
└── types/        # 型定義


### Configuration as Code

設定をコードとして管理し、CI/CDパイプラインで検証することを推奨します。

~~~yaml
# .github/workflows/validate-claude-config.yml
name: Validate Claude Code Config

on:
  pull_request:
    paths:
      - '.claude/**'
      - '.mcp.json'

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Validate settings.json
        run: |
          if [ -f ".claude/settings.json" ]; then
            npx ajv-cli validate \
              -s https://code.claude.com/schemas/settings.json \
              -d .claude/settings.json
          fi
      
      - name: Validate mcp.json
        run: |
          if [ -f ".mcp.json" ]; then
            npx ajv-cli validate \
              -s https://code.claude.com/schemas/mcp.json \
              -d .mcp.json
          fi

OpenTelemetryによる監視とログ収集

Claude Codeは、OpenTelemetry（OTLP）プロトコルを使用したテレメトリデータのエクスポートをサポートしています。これにより、組織全体のClaude Code利用状況を監視・分析できます。

テレメトリデータの種類

Claude Codeがエクスポートするテレメトリデータは以下の通りです。

データ種別	内容
スパン（Spans）	操作の開始/終了時刻、所要時間
メトリクス	トークン使用量、リクエスト数、レイテンシ
属性	ユーザーID、プロジェクト名、モデル名

OpenTelemetryの有効化

OpenTelemetryを有効化するには、環境変数を設定します。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# テレメトリを有効化
export CLAUDE_CODE_ENABLE_TELEMETRY=1

# OTLPエンドポイントを設定
export OTEL_EXPORTER_OTLP_ENDPOINT="https://otel-collector.company.com:4317"

# オプション: プロトコルを指定（grpc または http/protobuf）
export OTEL_EXPORTER_OTLP_PROTOCOL="grpc"

# オプション: サービス名を設定
export OTEL_SERVICE_NAME="claude-code"

managed-settings.jsonでの一元設定

組織全体でテレメトリを有効化するには、managed-settings.jsonに環境変数を設定します。

1
2
3
4
5
6
7
8


{
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "https://otel-collector.company.com:4317",
    "OTEL_EXPORTER_OTLP_PROTOCOL": "grpc",
    "OTEL_SERVICE_NAME": "claude-code"
  }
}

OTLPコレクターの構成

OpenTelemetry Collectorを使用してテレメトリデータを収集し、各種バックエンドに転送できます。

flowchart LR
    A[Claude Code] -->|OTLP| B[OTel Collector]
    B --> C[Jaeger<br>トレース]
    B --> D[Prometheus<br>メトリクス]
    B --> E[Elasticsearch<br>ログ]
    B --> F[Grafana<br>可視化]

otel-collector-config.yaml（設定例）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49


receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

processors:
  batch:
    timeout: 1s
    send_batch_size: 1024
  
  attributes:
    actions:
      - key: environment
        value: production
        action: insert

exporters:
  jaeger:
    endpoint: jaeger:14250
    tls:
      insecure: true
  
  prometheus:
    endpoint: 0.0.0.0:8889
    namespace: claude_code
  
  elasticsearch:
    endpoints: ["https://elasticsearch:9200"]
    index: claude-code-telemetry

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch, attributes]
      exporters: [jaeger]
    
    metrics:
      receivers: [otlp]
      processors: [batch]
      exporters: [prometheus]
    
    logs:
      receivers: [otlp]
      processors: [batch]
      exporters: [elasticsearch]

Grafanaダッシュボードの例

Prometheusに収集したメトリクスをGrafanaで可視化できます。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34


{
  "panels": [
    {
      "title": "Claude Code - トークン使用量",
      "type": "timeseries",
      "targets": [
        {
          "expr": "sum(rate(claude_code_tokens_total[5m])) by (user)",
          "legendFormat": "{{user}}"
        }
      ]
    },
    {
      "title": "Claude Code - リクエストレイテンシ",
      "type": "timeseries",
      "targets": [
        {
          "expr": "histogram_quantile(0.95, sum(rate(claude_code_request_duration_seconds_bucket[5m])) by (le))",
          "legendFormat": "p95"
        }
      ]
    },
    {
      "title": "Claude Code - アクティブユーザー数",
      "type": "stat",
      "targets": [
        {
          "expr": "count(count by (user) (claude_code_requests_total{time>now()-1h}))",
          "legendFormat": "Active Users"
        }
      ]
    }
  ]
}

監視アラートの設定

Prometheusのアラートルールを設定して、異常を検知できます。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


# prometheus-alerts.yaml
groups:
  - name: claude-code
    rules:
      - alert: ClaudeCodeHighErrorRate
        expr: |
          sum(rate(claude_code_errors_total[5m])) /
          sum(rate(claude_code_requests_total[5m])) > 0.1
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "Claude Codeのエラー率が高くなっています"
          description: "過去5分間のエラー率が10%を超えています"
      
      - alert: ClaudeCodeHighTokenUsage
        expr: |
          sum(rate(claude_code_tokens_total[1h])) by (user) > 100000
        for: 1h
        labels:
          severity: info
        annotations:
          summary: "高トークン使用量のユーザーを検知"
          description: "ユーザー {{ $labels.user }} の1時間あたりのトークン使用量が10万を超えています"

チーム運用のベストプラクティス

1. 段階的な導入

新規チームへの導入は、以下の段階で進めることを推奨します。

flowchart LR
    A[パイロット<br>2-3名] --> B[チーム展開<br>10-20名] --> C[部門展開] --> D[全社展開]
    
    A -.- A1[設定の調整<br>フィードバック収集]
    B -.- B1[Project設定の確立<br>CLAUDE.mdの整備]
    C -.- C1[managed設定の展開<br>ポリシーの標準化]
    D -.- D1[テレメトリ分析<br>継続的改善]

2. ドキュメントへの投資

Claude Codeの効果を最大化するため、各レベルでのドキュメント整備を推奨します。

レベル	ドキュメント	内容
組織	/Library/…/CLAUDE.md	全社的なコーディング標準、セキュリティポリシー
チーム	.claude/CLAUDE.md	プロジェクト概要、技術スタック、よく使うコマンド
モジュール	.claude/rules/*.md	機能別・ドメイン別のルール

3. セキュリティポリシーの設計

組織のセキュリティ要件に応じて、以下の項目を検討します。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Read(./.aws/**)",
      "Read(./.ssh/**)",
      "Bash(curl:*)",
      "Bash(wget:*)",
      "Bash(sudo:*)",
      "Bash(rm -rf:*)"
    ],
    "disableBypassPermissionsMode": "disable"
  },
  "mcpServers": {
    "allowedMcpServers": [
      "https://api.githubcopilot.com/*",
      "https://mcp.company.com/*"
    ],
    "deniedMcpServers": [
      "http://*"
    ]
  }
}

4. 定期的なレビューと更新

設定とポリシーは定期的にレビューし、以下の観点で更新します。

新しいMCPサーバーの追加/削除
パーミッションルールの見直し
テレメトリデータに基づく最適化
セキュリティインシデントへの対応

トラブルシューティング

managed設定が反映されない

ファイルパスを確認: OSごとに正しいパスに配置されているか確認します
ファイル権限を確認: 読み取り権限が設定されているか確認します
JSON構文を検証: 構文エラーがないか確認します

1
2
3


# macOSでの確認例
ls -la "/Library/Application Support/ClaudeCode/"
cat "/Library/Application Support/ClaudeCode/managed-settings.json" | jq .

MCPサーバーがブロックされる

/mcpコマンドでMCPサーバーのステータスを確認し、ポリシーによるブロックかどうかを特定します。

1

> /mcp

allowedMcpServersまたはdeniedMcpServersのパターンを確認し、必要に応じてIT部門に申請します。

テレメトリが送信されない

環境変数を確認: CLAUDE_CODE_ENABLE_TELEMETRYが設定されているか確認します
エンドポイントを確認: OTLPエンドポイントに到達可能か確認します
ネットワークを確認: ファイアウォールでポート4317/4318がブロックされていないか確認します

1
2


# エンドポイントへの接続確認
curl -v https://otel-collector.company.com:4318/v1/traces

設定の優先順位を確認する

現在適用されている設定を確認するには、/configコマンドを使用します。

1

> /config

まとめ

本記事では、Claude Codeのチーム運用に必要な設定管理とポリシー制御について解説しました。

managed-mcp.jsonとmanaged-settings.jsonを使用することで、IT部門は組織全体のMCPサーバーとセキュリティポリシーを一元管理できます。allowedMcpServers/deniedMcpServersによるポリシー制御により、承認されたサービスのみを使用可能にし、セキュリティリスクを最小化できます。

OpenTelemetryを活用した監視とログ収集により、Claude Codeの利用状況を可視化し、コスト管理やセキュリティ監査に活用できます。

チーム運用の成功には、段階的な導入、ドキュメントへの投資、定期的なレビューが重要です。これらのベストプラクティスを実践することで、チーム全体で統一されたClaude Code環境を構築・維持できます。

はじめに#

実行環境#

前提条件#

チーム運用における設定の階層構造#

各スコープの配置場所#

managed-mcp.jsonによるMCPサーバー一元管理#

managed-mcp.jsonの配置場所#

managed-mcp.jsonの基本構造#

MCPサーバータイプの選択#

環境変数の活用#

allowedMcpServers/deniedMcpServersによるポリシー制御#

ポリシー制御の設定#

ポリシーの評価順序#

パターンマッチングの構文#

実践的なポリシー設定例#

制限的なポリシー（ホワイトリスト方式）#

settings.jsonのチーム展開戦略#

展開レベルの使い分け#

managed-settings.jsonの展開（組織全体）#

Project設定の展開（チーム共有）#

新規プロジェクトへの展開テンプレート#

OpenTelemetryによる監視とログ収集#

テレメトリデータの種類#

OpenTelemetryの有効化#

managed-settings.jsonでの一元設定#

OTLPコレクターの構成#

Grafanaダッシュボードの例#

監視アラートの設定#

チーム運用のベストプラクティス#

1. 段階的な導入#

2. ドキュメントへの投資#

3. セキュリティポリシーの設計#

4. 定期的なレビューと更新#

トラブルシューティング#

managed設定が反映されない#

MCPサーバーがブロックされる#

テレメトリが送信されない#

設定の優先順位を確認する#

まとめ#

参考リンク#