メインコンテンツまでスキップ

MCP ツールリファレンス

secretctl MCP サーバーが提供するすべての MCP ツールの完全 API リファレンス。

概要​

secretctl MCP サーバーは、AI エージェントが平文のシークレットを受け取ることがないセキュリティファーストの設計を実装しています。これは 1Password の「Access Without Exposure」哲学に沿った「AI安全設計」アーキテクチャです。

利用可能なツール:

ツール説明
secret_listメタデータ付きでシークレットキーを一覧（値なし）
secret_existsメタデータ付きでシークレットの存在を確認
secret_get_maskedマスクされたシークレット値を取得（例: ****WXYZ）
secret_runシークレットを環境変数としてコマンドを実行
secret_list_fieldsマルチフィールドシークレットのフィールド名を一覧（値なし）
secret_get_field非機密フィールドの値のみを取得
secret_run_with_bindings定義済み環境バインディングで実行

secret_list​

すべてのシークレットキーをメタデータ付きで一覧。キー名、タグ、有効期限、メモ/URL の存在フラグを返します。シークレット値は返しません。

入力スキーマ​

{
  "tag": "string (オプション)",
  "expiring_within": "string (オプション)"
}
フィールド型必須説明
tagstringいいえタグでフィルター
expiring_withinstringいいえ有効期限でフィルター（例: 7d, 30d）

出力スキーマ​

{
  "secrets": [
    {
      "key": "string",
      "field_count": "number",
      "tags": ["string"],
      "expires_at": "string (RFC 3339, オプション)",
      "has_notes": "boolean",
      "has_url": "boolean",
      "created_at": "string (RFC 3339)",
      "updated_at": "string (RFC 3339)"
    }
  ]
}
フィールド型説明
keystringシークレットキー名
field_countnumberフィールド数（レガシー単一値シークレットは1）
tagsarrayシークレットに関連付けられたタグ
expires_atstringRFC 3339 形式の有効期限（オプション）
has_notesbooleanシークレットにメモがあるかどうか
has_urlbooleanシークレットに URL があるかどうか
created_atstringRFC 3339 形式の作成タイムスタンプ
updated_atstringRFC 3339 形式の最終更新タイムスタンプ

例​

すべてのシークレットを一覧:

// 入力
{}

// 出力
{
  "secrets": [
    {
      "key": "AWS_ACCESS_KEY",
      "field_count": 1,
      "tags": ["aws", "prod"],
      "has_notes": false,
      "has_url": true,
      "created_at": "2025-01-15T10:30:00Z",
      "updated_at": "2025-01-15T10:30:00Z"
    },
    {
      "key": "db/prod",
      "field_count": 5,
      "tags": ["db", "prod"],
      "expires_at": "2025-06-15T00:00:00Z",
      "has_notes": true,
      "has_url": false,
      "created_at": "2025-01-10T08:00:00Z",
      "updated_at": "2025-01-10T08:00:00Z"
    }
  ]
}

タグでフィルター:

// 入力
{
  "tag": "prod"
}

// 出力
{
  "secrets": [/* "prod" タグを持つシークレット */]
}

有効期限でフィルター:

// 入力
{
  "expiring_within": "30d"
}

// 出力
{
  "secrets": [/* 30日以内に期限切れになるシークレット */]
}

secret_exists​

シークレットキーが存在するかを確認し、メタデータを返します。シークレット値は返しません。

入力スキーマ​

{
  "key": "string"
}
フィールド型必須説明
keystringはい確認するシークレットキー

出力スキーマ​

{
  "exists": "boolean",
  "key": "string",
  "tags": ["string"],
  "expires_at": "string (RFC 3339, オプション)",
  "has_notes": "boolean",
  "has_url": "boolean",
  "created_at": "string (RFC 3339, オプション)",
  "updated_at": "string (RFC 3339, オプション)"
}

例​

存在するシークレットを確認:

// 入力
{
  "key": "API_KEY"
}

// 出力
{
  "exists": true,
  "key": "API_KEY",
  "tags": ["api", "prod"],
  "has_notes": true,
  "has_url": true,
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-15T10:30:00Z"
}

存在しないシークレットを確認:

// 入力
{
  "key": "NONEXISTENT_KEY"
}

// 出力
{
  "exists": false,
  "key": "NONEXISTENT_KEY",
  "tags": null,
  "has_notes": false,
  "has_url": false
}

secret_get_masked​

シークレット値のマスクされたバージョンを取得（例: ****WXYZ）。実際の値を公開せずにシークレットの形式を確認するのに便利です。

入力スキーマ​

{
  "key": "string"
}
フィールド型必須説明
keystringはい取得するシークレットキー

出力スキーマ​

{
  "key": "string",
  "masked_value": "string",
  "value_length": "integer",
  "field_count": "integer",
  "fields": {
    "field_name": {
      "value": "string",
      "sensitive": "boolean",
      "value_length": "integer"
    }
  }
}
フィールド型説明
keystringシークレットキー
masked_valuestringマスクされたプライマリ値（単一値シークレットのみ；マルチフィールドでは空）
value_lengthintegerプライマリ値の長さ（単一値シークレットのみ；マルチフィールドでは0）
field_countintegerこのシークレットのフィールド数
fieldsobjectフィールド名からマスク済みフィールド情報へのマップ（マルチフィールドシークレットのみ）

注意: マルチフィールドシークレットの場合、masked_value と value_length は空/0になります。 個々のフィールド値にアクセスするには fields マップを使用してください。

マスキング動作​

マスキングアルゴリズム:

  • 9文字以上のシークレットは末尾4文字を表示
  • 5-8文字のシークレットは末尾2文字を表示
  • 1-4文字のシークレットはアスタリスクのみ表示
  • 非機密フィールドは完全に表示（マスクなし）
シークレット長マスク出力
1-4文字****（すべてアスタリスク）
5-8文字******YZ（末尾2文字を表示）
9文字以上*****WXYZ（末尾4文字を表示）

マルチフィールドシークレット:

  • fields マップにはすべてのフィールドのマスク済み/完全な値が含まれます
  • 機密フィールドは上記のアルゴリズムに従ってマスクされます
  • 非機密フィールドは完全な値を表示します

例​

マスク値を取得（単一フィールドシークレット）:

// 入力
{
  "key": "API_KEY"
}

// 出力（API_KEY = "sk-abc123xyz789" の場合）
{
  "key": "API_KEY",
  "masked_value": "**********z789",
  "value_length": 14,
  "field_count": 1
}

短いシークレット:

// 入力
{
  "key": "PIN"
}

// 出力（PIN = "1234" の場合）
{
  "key": "PIN",
  "masked_value": "****",
  "value_length": 4,
  "field_count": 1
}

マルチフィールドシークレット（例: データベース認証情報）:

// 入力
{
  "key": "db/postgres"
}

// 出力（username, password, host を持つマルチフィールドシークレット）
{
  "key": "db/postgres",
  "masked_value": "",
  "value_length": 0,
  "field_count": 3,
  "fields": {
    "username": {
      "value": "dbadmin",
      "sensitive": false,
      "value_length": 7
    },
    "password": {
      "value": "***********5678",
      "sensitive": true,
      "value_length": 16
    },
    "host": {
      "value": "db.example.com",
      "sensitive": false,
      "value_length": 14
    }
  }
}

secret_run​

指定したシークレットを環境変数として注入してコマンドを実行。出力はシークレット漏洩を防ぐために自動的にサニタイズされます。ポリシー承認が必要です。

入力スキーマ​

{
  "keys": ["string"],
  "command": "string",
  "args": ["string"],
  "timeout": "string (オプション)",
  "env_prefix": "string (オプション)",
  "env": "string (オプション)"
}
フィールド型必須説明
keysstring[]はい注入するシークレットキー（glob パターン対応）
commandstringはい実行するコマンド
argsstring[]いいえコマンド引数
timeoutstringいいえ実行タイムアウト（例: 30s, 5m）。デフォルト: 5m
env_prefixstringいいえ環境変数名のプレフィックス
envstringいいえ環境エイリアス（例: dev, staging, prod）

出力スキーマ​

{
  "exit_code": "integer",
  "stdout": "string",
  "stderr": "string",
  "duration_ms": "integer",
  "sanitized": "boolean"
}
フィールド型説明
exit_codeintegerコマンド終了コード（0 = 成功）
stdoutstring標準出力（サニタイズ済み）
stderrstring標準エラー（サニタイズ済み）
duration_msinteger実行時間（ミリ秒）
sanitizedboolean出力がサニタイズされたかどうか

キーパターン構文​

keys フィールドは glob パターンをサポート:

パターンマッチ
API_KEYAPI_KEY に完全一致
aws/*aws/ 配下のすべてのキー（単一レベル）
db/*db/ 配下のすべてのキー（単一レベル）

環境変数の命名​

シークレットキーは環境変数名に変換されます:

  • / は _ に置換
  • - は _ に置換
  • 名前は大文字に変換
シークレットキー環境変数
aws/access_keyAWS_ACCESS_KEY
db-passwordDB_PASSWORD
api/prod/keyAPI_PROD_KEY

出力サニタイズ​

すべてのコマンド出力はシークレット値についてスキャンされます。マッチした箇所は [REDACTED:key] に置換されます:

オリジナル: "Connected to database with password secret123"
サニタイズ後: "Connected to database with password [REDACTED:DB_PASSWORD]"

例​

単一シークレットで実行:

// 入力
{
  "keys": ["API_KEY"],
  "command": "curl",
  "args": ["-H", "Authorization: Bearer $API_KEY", "https://api.example.com"]
}

// 出力
{
  "exit_code": 0,
  "stdout": "{\"status\": \"ok\"}",
  "stderr": "",
  "duration_ms": 245,
  "sanitized": false
}

ワイルドカードパターンで実行:

// 入力
{
  "keys": ["aws/*"],
  "command": "aws",
  "args": ["s3", "ls"]
}

// 出力
{
  "exit_code": 0,
  "stdout": "2025-01-15 10:30:00 my-bucket\n",
  "stderr": "",
  "duration_ms": 1250,
  "sanitized": false
}

環境エイリアスで実行:

// 入力
{
  "keys": ["db/*"],
  "command": "./deploy.sh",
  "env": "prod"
}

// 出力
{
  "exit_code": 0,
  "stdout": "Deployment complete",
  "stderr": "",
  "duration_ms": 5000,
  "sanitized": false
}

プレフィックス付きで実行:

// 入力
{
  "keys": ["API_KEY"],
  "command": "./app",
  "env_prefix": "MYAPP_"
}

// 環境変数:
// MYAPP_API_KEY=<value>

// 出力
{
  "exit_code": 0,
  "stdout": "Application started",
  "stderr": "",
  "duration_ms": 100,
  "sanitized": false
}

secret_list_fields​

マルチフィールドシークレットのすべてのフィールド名とメタデータを一覧。フィールド名、機密フラグ、ヒント、エイリアスを返します。フィールド値は返しません。

入力スキーマ​

{
  "key": "string"
}
フィールド型必須説明
keystringはいフィールドを一覧するシークレットキー

出力スキーマ​

{
  "key": "string",
  "fields": [
    {
      "name": "string",
      "sensitive": "boolean",
      "hint": "string (オプション)",
      "kind": "string (オプション)",
      "aliases": ["string"]
    }
  ]
}

例​

データベースシークレットのフィールドを一覧:

// 入力
{
  "key": "database/production"
}

// 出力
{
  "key": "database/production",
  "fields": [
    {
      "name": "host",
      "sensitive": false,
      "hint": "データベースホスト名"
    },
    {
      "name": "port",
      "sensitive": false,
      "hint": "データベースポート"
    },
    {
      "name": "username",
      "sensitive": false,
      "hint": "データベースユーザー名"
    },
    {
      "name": "password",
      "sensitive": true,
      "hint": "データベースパスワード"
    }
  ]
}

secret_get_field​

マルチフィールドシークレットから特定のフィールド値を取得。非機密フィールドのみ取得可能（AI安全設計ポリシー）。機密フィールドは拒否されます。

入力スキーマ​

{
  "key": "string",
  "field": "string"
}
フィールド型必須説明
keystringはいシークレットキー
fieldstringはい取得するフィールド名

出力スキーマ​

{
  "key": "string",
  "field": "string",
  "value": "string",
  "sensitive": "boolean"
}

例​

非機密フィールドを取得:

// 入力
{
  "key": "database/production",
  "field": "host"
}

// 出力
{
  "key": "database/production",
  "field": "host",
  "value": "db.example.com",
  "sensitive": false
}

機密フィールドの取得を試行（拒否）:

// 入力
{
  "key": "database/production",
  "field": "password"
}

// エラーレスポンス
{
  "error": "フィールド 'password' は機密としてマークされており、MCP 経由で取得できません（AI安全設計ポリシー）"
}

secret_run_with_bindings​

シークレットの定義済みバインディングに基づいて環境変数を注入してコマンドを実行。各バインディングは環境変数名をフィールドにマップします。ポリシー承認が必要です。

入力スキーマ​

{
  "key": "string",
  "command": "string",
  "args": ["string"],
  "timeout": "string (オプション)"
}
フィールド型必須説明
keystringはいバインディングが定義されたシークレットキー
commandstringはい実行するコマンド
argsstring[]いいえコマンド引数
timeoutstringいいえ実行タイムアウト（例: 30s, 5m）。デフォルト: 5m

出力スキーマ​

{
  "exit_code": "integer",
  "stdout": "string",
  "stderr": "string",
  "sanitized": "boolean"
}

バインディングの仕組み​

バインディング付きでシークレットを作成すると、各バインディングが環境変数名をフィールドにマップします:

secretctl set database/production \
  --field host=db.example.com \
  --field port=5432 \
  --field password \
  --binding PGHOST=host \
  --binding PGPORT=port \
  --binding PGPASSWORD=password

このシークレットで secret_run_with_bindings を呼び出すと、以下の環境変数が設定されます:

  • PGHOST=db.example.com
  • PGPORT=5432
  • PGPASSWORD=<password value>

例​

PostgreSQL コマンドを実行:

// 入力
{
  "key": "database/production",
  "command": "psql",
  "args": ["-c", "SELECT 1"]
}

// 出力
{
  "exit_code": 0,
  "stdout": " ?column? \n----------\n        1\n(1 row)\n",
  "stderr": "",
  "sanitized": true
}

ポリシー設定​

secret_run と secret_run_with_bindings ツールにはポリシー承認が必要です。~/.secretctl/mcp-policy.yaml を作成してください:

version: 1
default_action: deny

# 常にブロックされるコマンド（セキュリティ）
# - env, printenv, set, export, cat /proc/*/environ

# ユーザー定義の拒否コマンド
denied_commands: []

# 許可されたコマンド（default_action が deny の場合に必要）
allowed_commands:
  - aws
  - gcloud
  - kubectl
  - curl
  - ./deploy.sh

# キー変換用の環境エイリアス
env_aliases:
  dev:
    - pattern: "db/*"
      target: "dev/db/*"
  prod:
    - pattern: "db/*"
      target: "prod/db/*"

ポリシー評価順序​

  1. デフォルト拒否コマンド（常にブロック）: env, printenv, set, export
  2. ユーザー定義の denied_commands: 明示的にブロックされたコマンド
  3. ユーザー定義の allowed_commands: 明示的に許可されたコマンド
  4. default_action: フォールバックアクション（allow または deny）

セキュリティ要件​

ポリシーファイルは以下の要件を満たす必要があります:

  • ファイルパーミッション: 0600（オーナーのみ読み書き）
  • シンボリックリンク不可（直接ファイルのみ）
  • 現在のユーザーが所有

セキュリティ設計​

AI安全設計アーキテクチャ​

secretctl MCP サーバーは「AI安全設計」セキュリティモデルに従っています:

ツール平文アクセス目的
secret_listなしキーとメタデータのみ一覧
secret_existsなし存在とメタデータを確認
secret_get_maskedなし公開せずに形式を確認
secret_runなし*環境変数経由で注入
secret_list_fieldsなしフィールド名とメタデータのみ一覧
secret_get_fieldなし**非機密フィールドのみ
secret_run_with_bindingsなし*定義済みバインディング経由で注入

* シークレットは子プロセスに環境変数として注入されます。AI エージェントは平文の値を見ることはありません。

** sensitive: false とマークされたフィールドのみ取得可能。機密フィールドはエラーで拒否されます。

なぜ secret_get がないのか？​

平文の値を返す secret_get ツールは意図的に実装されていません。この設計上の選択は以下に準拠しています:

  • 1Password: MCP 経由で生の認証情報を公開することを明示的に拒否
  • HashiCorp Vault: 「生のシークレットは決して公開しない」ポリシー
  • 業界のベストプラクティス: シークレットの露出面を最小化

出力サニタイズ​

secret_run ツールは偶発的なシークレット漏洩を防ぐためにコマンド出力を自動的にサニタイズします:

  • シークレット値の完全一致を検出
  • [REDACTED:key] プレースホルダーに置換
  • stdout と stderr の両方に適用

制限事項:

  • Base64 や hex エンコードされたシークレットは検出されません
  • 部分一致は検出されません
  • 難読化または変換された値は検出されません

エラー処理​

一般的なエラー​

エラー説明
secret not found要求されたシークレットキーが存在しない
policy not foundMCP ポリシーファイルが存在しない
command not allowedコマンドがポリシーでブロックされた
timeout exceededコマンド実行がタイムアウトを超過

エラーレスポンス形式​

{
  "error": {
    "code": -32000,
    "message": "secret not found: API_KEY"
  }
}

連携例​

Claude Code (~/.claude.json) で設定:

{
  "mcpServers": {
    "secretctl": {
      "command": "/path/to/secretctl",
      "args": ["mcp-server"],
      "env": {
        "SECRETCTL_PASSWORD": "your-master-password"
      }
    }
  }
}

詳細なセットアップ手順は MCP 連携ガイド を参照してください。