altr-mcp-server

ALTR MCP サーバー

ALTR は、Snowflake、Databricks、OLTP データベース向けに、タグベースのデータマスキング、アクセスガバナンス、分類機能を提供します。この MCP サーバーを使うと、AI アシスタント（Claude、Cursor、その他の MCP クライアント）から ALTR プラットフォームのデータセキュリティを管理できます。データベース接続、タグマスキング、ポリシー、分類、アクセス管理、監査、テレメトリー、サイドカー設定に対応しています。

ALTR を初めてお使いですか？ プラットフォームの概要、概念、対応データソースについては、ALTR のドキュメントをご覧ください。

すべてのツールは、構造化された {success, data, error} レスポンスを返し、stdio、SSE、streamable-http トランスポートで実行できます。

目次

• クイックスタート
• 認証情報の取得
• 設定
  • ツールの制限
• セットアップ
  • Claude Desktop
  • Claude Code (CLI)
  • Cursor
  • VS Code (GitHub Copilot)
  • Windsurf
  • ローカルソースから実行
• CLI（オプション）
• ツール
• データソースのサポート
• トラブルシューティング
• 開発
• ライセンス

クイックスタート

1. PyPI からインストールします：

   pip install altr-mcp
   

   または、uvx を使って直接実行できます（インストール不要）：

   uvx altr-mcp
   

   uvx は uv Python パッケージマネージャーに含まれています。pip install uv でインストールするか、uv のインストールガイドをご覧ください。

2. 必要な 3 つの環境変数を設定します（ALTR コンソールで各値を確認する方法については、認証情報の取得をご覧ください）：

   export ORG_ID=your-org-id
   export MAPI_KEY=your-api-key
   export MAPI_SECRET=your-api-secret
   

3. AI クライアントに接続します — Claude Desktop、Claude Code、Cursor、VS Code、Windsurf の設定については、セットアップをご覧ください。同じ 3 つの環境変数を、クライアントの env ブロックに設定します。

4. 検証します。AI アシスタントに読み取り専用ツールを実行するよう依頼してください：

   • 「自分の ALTR データベースを一覧表示して」→ get_databases を呼び出します
   • 「ALTR に接続されているタグを表示して」→ get_tags を呼び出します
   • 「自分の組織の ALTR ロールを一覧表示して」→ get_roles を呼び出します

   データが返されれば、セットアップは正常に完了しています。

認証情報の取得

このサーバーを設定するには、ALTR プラットフォームから 3 つの値を取得する必要があります。詳しくはAPI キーの管理をご覧ください。

認証情報	確認場所
ORG_ID	ALTR コンソールの Settings > Preferences > Organization：「ALTR Organization ID」の値をコピーします
MAPI_KEY	ALTR コンソールの Settings > Preferences > API > Add New：説明を入力し、キーをコピーします
MAPI_SECRET	上記の API キーを作成するときに一度だけ表示されます。コピーして安全に保管してください

設定

サーバーを起動する前に、次の環境変数を設定してください。

変数	必須	説明
ORG_ID	はい	ALTR の組織 ID
MAPI_KEY	はい	ALTR 管理 API キー
MAPI_SECRET	はい	ALTR 管理 API シークレット
MCP_TRANSPORT	いいえ	トランスポートプロトコル：stdio（デフォルト）、sse、または streamable-http
MCP_HOST	いいえ	HTTP トランスポートのバインドアドレス（デフォルト：0.0.0.0）
MCP_PORT	いいえ	HTTP トランスポートのポート（デフォルト：8000）
RESTRICTED_TOOLS	いいえ	クライアントに表示しないツール名をカンマ区切りで指定
LOG_FORMAT	いいえ	ログ出力形式：console（デフォルト）または json
LOG_LEVEL	いいえ	ログレベル（デフォルト：INFO）
MAX_RETRIES	いいえ	諦めるまでの API 呼び出しごとの試行回数（デフォルト：3、最小値：1）
DISABLE_RETRY	いいえ	再試行を完全に無効にするには true を設定（デフォルト：false）
REQUEST_TIMEOUT	いいえ	リクエストごとのタイムアウト（秒、デフォルト：30）
MAX_RETRY_AFTER	いいえ	サーバーから送られる Retry-After の上限（秒、デフォルト：60）

MAX_RETRIES は初回の試行に加えた再試行回数ではなく、合計試行回数です。そのため、1 にすると再試行の仕組み自体は無効にせず、再試行を無効にします。バックオフはジッターを伴う指数関数的な方式です。Retry-After レスポンスヘッダーがある場合はその値が優先されますが、呼び出しが無期限に保留されないよう、MAX_RETRY_AFTER を上限として制限されます。

ログに記録される内容

すべてのツール呼び出しは、セッションを追跡可能にするため、引数とともに INFO レベルで stderr に記録されます。値が認証情報またはユーザーが入力した自由形式のテキストである引数はマスキングされます。対象は values、text、comments、attestation、justification、statement_text_contains、filters、connection_string、認証情報の名前そのもの（password、secret、credentials、passphrase、private_key、api_key、auth_token、access_key）、および _password、_secret、_credential、_credentials、_private_key、_passphrase で終わる引数です。識別子、列挙値、ページネーションカーソルはすべて記録されます。

引数名を基準とするマスキングでは検出できないため、リクエスト URL に含まれた引数がログに記録される可能性もあります。そのため、httpx のリクエストごとのログは WARNING に設定され、デフォルトの INFO では表示されません。

辞書のキーはそのまま残るため、ログの行は values={'ssn': '<redacted>', 'email': '<redacted>'} のようになります。どのフィールドが送信されたかは確認でき、データ自体は表示されません。トークンはマスキングされません。トークンは自由に扱うことを目的としており、ALTR 独自の Shield 監査ログはトークンをキーとしているためです。

マスキングは、呼び出しのログ行、トレースバック、呼び出し元に返される引数の型変換エラーに適用されます。

LOG_FORMAT はこのサーバー自体の出力だけでなく、依存関係の出力にも適用されます。json の場合、ストリーム上の各行は JSON オブジェクトになり、依存関係のログ行には、その行が発生したツール呼び出しの correlation_id が含まれます。ログを参照してください。

0.6.0 以前からアップグレードしますか？ 引数は 0.7.0 より前はマスキングされていませんでした。ツールの引数として渡した認証情報はログで漏えいしたものとして扱い、ローテーションしてください。実際には database_password と connection_string が該当します。ログにはトークン化ツールに渡された平文も含まれている可能性があります。ログを閲覧できるユーザーと保存期間を確認してください。ログ出力の形式も変更されています。CHANGELOG の 0.7.0 の項目を参照してください。

エンドポイントのオーバーライド

ALTR サービスのすべてのエンドポイントは、別の場所を指定できます。これは、本番環境ではない ALTR 環境に接続する場合に便利です。すべて任意の設定です。通常の使用では設定しないでください。

8 つのサービスごとのエンドポイントは、ORG_ID から https://<ORG_ID>.<service>.live.altr.com として導出されます。そのうち 5 つにはパス（バージョン、または /v1/dam-alerting）が追加されます。オーバーライドすると値全体が置き換わるため、デフォルトにパスがある場合はそのパスも含める必要があります。表を参照してください。

変数	デフォルト
ALTR_API_BASE_URL	https://api.live.altr.com
ALTR_ALTRNET_BASE_URL	https://altrnet.live.altr.com
ALTR_CLASSIFICATION_BASE_URL	https://<ORG_ID>.classification.live.altr.com
ALTR_SC_CONTROL_BASE_URL	https://<ORG_ID>.sc-control.live.altr.com
ALTR_SERVICE_USER_BASE_URL	https://<ORG_ID>.service-user.live.altr.com
ALTR_AUDIT_REPORT_BASE_URL	https://<ORG_ID>.audit-report.live.altr.com/v1
ALTR_VAULT_BASE_URL	https://<ORG_ID>.vault.live.altr.com/api/v2
ALTR_CRITICAL_BASE_URL	https://<ORG_ID>.critical.live.altr.com/v2
ALTR_KMA_BASE_URL	https://<ORG_ID>.kma.live.altr.com/v1
ALTR_DAM_ALERTING_BASE_URL	https://<ORG_ID>.dam-alerting.live.altr.com/v1/dam-alerting

ツールの制限

RESTRICTED_TOOLS を使うと、特定のツールを MCP クライアントから非表示にできます。制限されたツールはツール一覧から除外され、直接呼び出された場合もブロックされます。

名前は登録済みのツール名と完全に一致する必要があります。一致する項目がない場合、何も制限されません。また、クライアントが初めてツール一覧を取得したときに警告としてログに記録されます。なお、0.4.0 では 11 個のツール名が delete_* から disconnect_* に変更されました。

たとえば、破壊的な操作を許可せず、チームに読み取り専用アクセスを付与するには、次のようにします。

RESTRICTED_TOOLS=disconnect_database,delete_policy,delete_rule,disconnect_tag,disconnect_tag_by_details,delete_classifier,delete_collection,disconnect_sc_repo,disconnect_sc_sidecar

または、Claude Desktop の設定に次のように記述します。

{
  "mcpServers": {
    "altr": {
      "command": "uvx",
      "args": ["altr-mcp"],
      "env": {
        "ORG_ID": "your-org-id",
        "MAPI_KEY": "your-api-key",
        "MAPI_SECRET": "your-api-secret",
        "RESTRICTED_TOOLS": "disconnect_database,delete_policy,delete_rule,disconnect_tag"
      }
    }
  }
}

これは運用者レベルのセーフティネットです。誤操作や望ましくないツールの使用を防ぎますが、適切な API キーの権限設定に代わるものではありません。

セットアップ

Claude Desktop

claude_desktop_config.json に以下を追加します（Settings > Developer > Edit Config）。

{
  "mcpServers": {
    "altr": {
      "command": "uvx",
      "args": ["altr-mcp"],
      "env": {
        "ORG_ID": "your-org-id",
        "MAPI_KEY": "your-api-key",
        "MAPI_SECRET": "your-api-secret"
      }
    }
  }
}

Claude Code（CLI）

claude mcp add altr -e ORG_ID=your-org-id -e MAPI_KEY=your-api-key -e MAPI_SECRET=your-api-secret -- uvx altr-mcp

これにより、設定が .mcp.json に書き込まれ、チームで共有するためにコミットできます。

Cursor

~/.cursor/mcp.json（グローバル）または .cursor/mcp.json（プロジェクトごと）に追加します。

{
  "mcpServers": {
    "altr": {
      "command": "uvx",
      "args": ["altr-mcp"],
      "env": {
        "ORG_ID": "your-org-id",
        "MAPI_KEY": "your-api-key",
        "MAPI_SECRET": "your-api-secret"
      }
    }
  }
}

VS Code（GitHub Copilot）

ユーザー設定 JSON を開き（Ctrl+Shift+P → "Preferences: Open User Settings (JSON)"）、以下を追加します。

{
  "mcp": {
    "servers": {
      "altr": {
        "command": "uvx",
        "args": ["altr-mcp"],
        "env": {
          "ORG_ID": "your-org-id",
          "MAPI_KEY": "your-api-key",
          "MAPI_SECRET": "your-api-secret"
        }
      }
    }
  }
}

Windsurf

~/.codeium/windsurf/mcp_config.json に追加します。

{
  "mcpServers": {
    "altr": {
      "command": "uvx",
      "args": ["altr-mcp"],
      "env": {
        "ORG_ID": "your-org-id",
        "MAPI_KEY": "your-api-key",
        "MAPI_SECRET": "your-api-secret"
      }
    }
  }
}

ローカルソースからの実行

公開済みの PyPI パッケージではなく、ローカルのクローンから実行するには、次のようにします。

Claude Code:

claude mcp add altr \
  -e ORG_ID=your-org-id \
  -e MAPI_KEY=your-api-key \
  -e MAPI_SECRET=your-api-secret \
  -- uv run --directory /path/to/altr-mcp altr-mcp

Claude Desktop:

{
  "mcpServers": {
    "altr": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/altr-mcp", "altr-mcp"],
      "env": {
        "ORG_ID": "your-org-id",
        "MAPI_KEY": "your-api-key",
        "MAPI_SECRET": "your-api-secret"
      }
    }
  }
}

CLI（任意）

このセクションでは、MCP サーバーからスタンドアロン CLI バイナリをビルドする方法を説明します。Claude Desktop または Claude Code でサーバーを使用するだけの場合は、ツールに進んでください。

スタンドアロン CLI を使うと、MCP クライアントなしでターミナルから ALTR ツールを直接呼び出せます。mcporter を使ってビルドします。これは、MCP サーバーをネイティブ CLI バイナリにコンパイルするオープンソースのツールです。オプションの全容については、mcporter のドキュメントを参照してください。

前提条件

• uv（Python パッケージマネージャー）
• Node.js（npx で mcporter を取得して実行するため）

mcporter を個別にインストールする必要はありません。npx が必要に応じてダウンロードして実行します。

ビルド

リポジトリのルートから実行します。

npx mcporter generate-cli --command "uv run --directory . altr-mcp" --name altr-cli --compile ./altr-cli

これにより、コンパイル済みバイナリが ./altr-cli に生成されます。

使用方法

認証情報を環境変数として設定し、任意のツールを実行します。

export ORG_ID=your-org-id
export MAPI_KEY=your-api-key
export MAPI_SECRET=your-api-secret

# List databases
./altr-cli get-databases

# Get a specific database ID
./altr-cli get-database-id --database-name "my_database"

# Create a masking policy
./altr-cli create-policy --tag "STOPLIGHT"

# Add rules (pass JSON string for complex params)
./altr-cli add-rules --policy-id "TAG#abc123" --rules '[{"masking_policy": 10001, "role": "PUBLIC", "tag_value": "red"}]'

# Search query audits
./altr-cli search-query-audits --limit 10

# JSON output
./altr-cli get-databases --output json

# See all available commands
./altr-cli --help

CLI は uv run を介して MCP サーバーをローカルで実行するため、作業ディレクトリにリポジトリが存在している必要があります。設定セクションに記載されたすべての環境変数が適用されます。

ツール

各ツールのパラメーター、動作、使用例の詳細については、docs/index.md をご覧ください。

ドメイン	ツール	機能
データベース	8	Snowflake、OLTP、Databricks のデータソースに接続します。プラットフォームごとのセットアップ：Snowflake、OLTP、Databricks。
タグ	8	Snowflake のタグ接続を ALTR に管理します。Snowflake タグを ALTR に接続するをご覧ください。
ポリシーとルール	9	マスキングポリシーとロールごとのルールを作成します。タグベース（Snowflake、Databricks）と列ベース（Snowflake のみ）に対応しています。マスキングレベル 10000–10009は、ポリシーの種類（get_supported_masking_types）によって制限されます。ALTR のすべてのロールを一覧表示する get_roles を含みます（ALTR コンソールではユーザーグループと呼ばれます）。
分類	41	自動化されたデータ分類スキャンを実行します。Snowflake（自社開発＋ALTR Native＋GDLP）、OLTP（ALTR Native＋GDLP）、Databricks（GDLP のみ）に対応しています。検出結果ツリーのナビゲーションと人によるレビュー判断も含まれます。
アクセス管理	4	Snowflake と OLTPのアクセス管理ポリシーを扱います。
アクセスリクエスト	6	データアクセスの承認リクエストを送信、承認、拒否、キャンセルします。
監査	6	サイドカー、Snowflake クエリ、プラットフォームのシステム監査を検索します。
監査レポート	17	コメントや承認を含む、構造化された監査レポートの定義とインスタンスを作成、スケジュール設定、確認します。
DAM アラート	10	サイドカーと Snowflake の監査イベントに対する一致条件およびしきい値アラートルールを作成します。発生したアラートをトリアージし、コメントを付けて確認します。
テレメトリ	9	ALTR サイドカープロキシのエージェントとサイドカーインスタンスの健全性を監視します。
サイドカー設定	37	ALTR サイドカープロキシを設定します。対象はエージェント、リポジトリ、リポジトリユーザー、サービスユーザー、サイドカー、リスナー、バインディングです。
ボールトトークン化	4	ALTR のボールト型トークン化を使用して値をトークン化およびデトークン化します。
クリティカルトークン化	4	ALTR のクリティカルトークン化を使用して値をトークン化およびデトークン化します。
キー管理	9	FPE 暗号化キーと tweak を管理します。

重要なポイント

見落としやすいため、ここでいくつかのポイントを取り上げます。

Snowflake タグと Databricks タグ。 Snowflake タグは、ALTR の第一級オブジェクトです。connect_tag で登録すると、tag_group_id が付与され、get_tags、get_tag_details*、update_tag、disconnect_tag* に表示されます。一方、Databricks タグは ALTR オブジェクトではなく、create_policy に渡す単なる文字列です（policy_type="PUSHDOWN" と database_ids=[…] を指定します）。Databricks タグは get_tags に表示されず、tag_group_id もありません。Tags ツールは Databricks には適用されません。

Databricks の create_policy の要件。 Databricks メタストアのマスキングポリシーを作成するときは、データベースが 1 つだけの場合でも、database_ids をリストとして渡し（例：database_ids=[2167]）、policy_type="PUSHDOWN" を設定する必要があります。database_ids を省略するか、policy_type="TAG" を使用すると、API に拒否されます。Snowflake ポリシーの場合は逆に、database_ids を省略し、policy_type はデフォルトの TAG のままにします。

データソースのサポート

ALTR ドキュメントサイトのプラットフォーム設定ガイド：

• Snowflake
• OLTP データベース（PostgreSQL、MySQL、Oracle、SQL Server）
• Databricks

機能	Snowflake	OLTP（サイドカー経由）	Databricks
データベース接続	✅	—	✅
マスキングポリシー	✅	❌	✅
分類	✅	✅	⚠️ 部分対応
アクセス管理ポリシー	✅	✅	❌
アクセスリクエスト	✅	❌	❌
クエリ監査ログ	✅	✅	❌
システム監査ログ	✅	✅	❌
サイドカー設定	—	✅	—
テレメトリとモニタリング	—	✅	—

凡例： ✅ 対応   ⚠️ 部分対応   ❌ 非対応   — 該当なし

分類モードの対応範囲：

モード	Snowflake	OLTP	Databricks
インハウス（ALTR のパターンマッチング）	✅	❌	❌
ALTR ネイティブ分類器	✅	✅	❌
GDLP（Google Cloud DLP）	✅	✅	✅

Databricks の分類 — 部分対応： create_databricks_job 経由の GDLP のみ対応しており、インハウス分類器および ALTR ネイティブ分類器には対応していません。特定の ALTR コレクションの分類器にスキャン対象を限定するために、必要に応じて collection_name を渡せます（condition_types に従います）。省略した場合は、Google DLP のすべてのデフォルトの infoTypes が使用されます。

アクセス管理ポリシー（Databricks）： この MCP サーバーは、現在 Databricks の権限付与 API やアクセス管理 API を公開していません。Databricks のアクセス制御には、Databricks の UI または REST API を直接使用してください。

OLTP は、顧客が管理する ALTR サイドカープロキシ 経由でアクセスするリレーショナルデータベース（PostgreSQL、MySQL、Oracle、SQL Server）を指します。

トラブルシューティング

実行中のバージョンを確認する

uvx altr-mcp --version

この方法は認証情報がなくても機能します。AI クライアントが接続すると、サーバーと同じバージョンを報告するため、クライアントがアップグレードを実際に取り込んだことを最も手早く確認できます。

uvx: command not found

uv をインストールしてください。pip install uv を実行するか、公式インストーラーを使用します。

AI クライアントにサーバーが表示されない

設定ファイルを編集した後、AI クライアントを再起動してください。変更は自動的には反映されません。

ERROR: Missing required environment variables

クライアント設定の env ブロックで ORG_ID、MAPI_KEY、MAPI_SECRET が設定されていることを確認してください。変数名では大文字と小文字が区別されます。

{"success": false, ...} を返すツール

HTTP ステータス	考えられる原因	対処方法
401	認証情報が無効です	ALTR コンソールの Settings > Preferences > API で MAPI_KEY / MAPI_SECRET を確認してください
403	この組織では機能が有効になっていません	エンドポイントは存在しますが、組織で有効になっていない ALTR 機能フラグによって制限されています。アカウントで機能が有効になっているか、ALTR サポートにお問い合わせください。
404	リソースが見つかりません	ID が組織内に存在することを確認してください
429	レート制限に達しました	サーバーはバックオフしながら最大 3 回まで自動的に再試行します。問題が続く場合は、リクエストの頻度を下げてください

ツール一覧にツールが表示されない

クライアント設定の RESTRICTED_TOOLS 環境変数にツール名が含まれているか確認してください。制限されたツールは、ツール一覧に一切表示されません。

制限されたツールが引き続き公開されている

RESTRICTED_TOOLS は名前を完全一致で照合するため、スペルミスや名前変更がある項目では何も制限されません。サーバーログで tool_restriction_middleware.unknown_tools を確認してください。一致する登録済みツールがなかった項目が表示されます。

大きな結果セットでタイムアウトする

監査、テレメトリ、分類の各ツールで使用できるページネーションパラメーター（limit、offset、または cursor）を使用して、応答サイズを小さくしてください。

開発

テストの実行

# Install dependencies
uv sync --extra dev

# Run all tests
uv run pytest

# Run with verbose output
uv run pytest -v

# Run a specific test file
uv run pytest tests/integration/test_database.py

# Run a specific test
uv run pytest tests/integration/test_database.py::test_create_database_with_service_user

# Run with coverage report (terminal)
uv run pytest --cov=altr_mcp --cov-report=term-missing

# Run with coverage and generate an HTML report at htmlcov/index.html
uv run pytest --cov=altr_mcp --cov-report=html

プロジェクト構成

altr_mcp/
  server.py          # MCP server entrypoint and tool registration
  settings.py        # Pydantic settings (env vars)
  instructions.md    # System prompt for LLM tool guidance
  tools/             # Tool definitions (one file per domain)
  utils/             # API client functions (one file per API)
tests/
  unit/              # Unit tests (settings, models, annotations)
  integration/       # Integration tests (httpx mocks per domain)

詳細情報

プラットフォームのセットアップ

• ALTR ドキュメントのホーム
• Snowflake データソース
• OLTP データソース
• Databricks データソース
• API キーの管理

データアクセス制御

• タグベースのアクセス ポリシー — Snowflake と Databricks
• 列ベースのアクセス ポリシー — Snowflake
• マスキングポリシー（10000–10009 タイプ）
• アクセス管理ポリシーとアクセスリクエストの管理

ディスカバリーと可観測性

• データ分類
• データベースアクティビティ監視

プロトコル

• Model Context Protocol の仕様

ライセンス

Copyright (C) 2026 ALTR Solutions, Inc.

GNU General Public License v3.0 以降（GPL-3.0-or-later）。著作権表示とライセンス全文については、 LICENSE.md を参照してください。