altr-mcp-server

ALTR MCP 服务

ALTR 为 Snowflake、Databricks 和 OLTP 数据库提供基于标签的数据屏蔽、访问治理和分类功能。此 MCP 服务使 AI 助手（Claude、Cursor 和其他 MCP 客户端）能够在 ALTR 平台上管理数据安全，涵盖数据库连接、标签屏蔽、策略、分类、访问管理、审计、遥测和 sidecar 配置。

刚接触 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. 设置三个必需的环境变量（有关在 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 的设置方法请参阅设置。将相同的三个环境变量填入客户端的 env 块中。

4. 验证：请 AI 助手运行一个只读工具：

   • “列出我的 ALTR 数据库” → 调用 get_databases
   • “显示连接到 ALTR 的标签” → 调用 get_tags
   • “列出我组织中的 ALTR 角色” → 调用 get_roles

   如果这些操作返回了数据，则说明设置已生效。

获取凭据

你需要从 ALTR 平台获取三个值，以配置此服务。完整参考请参阅管理 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。这些日志还可能包含传给 tokenize 工具的明文，因此请检查 谁可以读取这些日志，以及日志会保留多久。日志输出格式也已更改；请参阅 CHANGELOG 中的 0.7.0 条目。

终结点覆盖

每个 ALTR 服务终结点都可以指向其他地址，这在连接到非生产环境中的 ALTR 时很有用。所有变量均为可选项——正常使用时请留空。

八个按服务划分的终结点根据你的 ORG_ID 生成，格式为 https://<ORG_ID>.<service>.live.altr.com，其中五个会追加路径（版本号或 /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）

打开 User Settings 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 可让你直接在终端中调用 ALTR 工具，无需 MCP 客户端。它使用 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）。包含 get_roles，用于列出所有 ALTR 角色（在 ALTR 控制台中称为用户组）。
分类	41	运行自动化的数据分类扫描。Snowflake（自研 + ALTR Native + GDLP）、OLTP（ALTR Native + GDLP）、Databricks（仅限 GDLP）。包含发现结果树导航和人工审核决策。
访问管理	4	适用于 Snowflake 和 OLTP 的访问管理策略。
访问请求	6	提交、批准、拒绝和取消数据访问审批请求。
审计	6	搜索 sidecar、Snowflake 查询和平台系统审计。
审计报告	17	创建、安排和审核结构化审计报告定义及实例，包括评论和签字确认。
DAM 告警	10	根据 sidecar 和 Snowflake 审计事件创建匹配与阈值告警规则；对触发的告警进行分类处理、评论和确认。
遥测	9	监控 ALTR sidecar 代理 Agent 和 sidecar 实例的运行状况。
Sidecar 配置	37	配置 ALTR sidecar 代理：Agent、仓库、仓库用户、服务用户、sidecar、监听器和绑定。
Vault 令牌化	4	使用 ALTR Vault 令牌化对值进行令牌化和反令牌化。
关键令牌化	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。所有标签工具都不适用于 Databricks。

Databricks 的 create_policy 要求。 为 Databricks metastore 创建掩码策略时，必须将 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（通过 sidecar）	Databricks
数据库连接	✅	—	✅
掩码策略	✅	❌	✅
分类	✅	✅	⚠️ 部分支持
访问管理策略	✅	✅	❌
访问请求	✅	❌	❌
查询审计日志记录	✅	✅	❌
系统审计日志记录	✅	✅	❌
Sidecar 配置	—	✅	—
遥测与监控	—	✅	—

图例： ✅ 支持   ⚠️ 部分支持   ❌ 不支持   — 不适用

分类模式支持情况：

模式	Snowflake	OLTP	Databricks
内部（ALTR 模式匹配）	✅	❌	❌
ALTR 原生分类器	✅	✅	❌
GDLP（Google Cloud DLP）	✅	✅	✅

Databricks 分类——部分支持： 仅通过 create_databricks_job 使用 GDLP；不支持内部或 ALTR 原生分类器。可以选择传入 collection_name，将扫描范围限定为特定 ALTR 集合的分类器（受 condition_types 限制）；省略时将使用所有默认的 Google DLP infoTypes。

访问管理策略（Databricks）： 此 MCP 服务目前不提供 Databricks 授权或访问管理 API。要管理 Databricks 访问控制，请直接使用 Databricks UI 或 REST API。

OLTP 指关系数据库（PostgreSQL、MySQL、Oracle、SQL Server），通过客户管理的 ALTR sidecar 代理访问。

故障排除

检查正在运行的版本

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。