ALTR MCP Server

The ALTR MCP Server connects AI assistants to the ALTR platform using the Model Context Protocol (MCP), an open standard for giving large language models access to external tools. With it, assistants such as Claude, Cursor, and GitHub Copilot can manage tag-based data masking, access controls, and data classification across Snowflake, Databricks, and OLTP databases directly from a conversation.

The server exposes 156 tools across 13 domains, covering database connections, tag masking, policies, classification, access management, audits, telemetry, and sidecar configuration. Every tool returns a structured {success, data, error} response and can run over stdio, Server-Sent Events (SSE), or streamable-http transports.

Note

The ALTR MCP Server is open source (GPL-3.0) and published to PyPI as altr-mcp. The source code is available on GitHub.

Prerequisites

Before you begin, you need:

• An ALTR organization with an API key.
• The uv Python package manager, which provides the uvx command. Install it with pip install uv.

You need three values from the ALTR console to authenticate the server:

Credential	Where to find it
ORG_ID	Settings > Preferences > Organization — copy the value from “ALTR Organization ID”.
MAPI_KEY	Settings > Preferences > API > Add New — enter a description, click Create API Key, then copy the Key Name (the auto-generated username).
MAPI_SECRET	Shown once when you create the API key — copy and store it securely.

For the full reference on creating and managing keys, see Manage API Keys.

Install

Install the server from PyPI:

pip install altr-mcp

Or run it directly with uvx, which requires no separate install:

uvx altr-mcp

Configure your AI client

Add the ALTR MCP Server to your AI client’s configuration, passing your three credentials in the env block. Restart the client after editing its configuration — changes are not picked up automatically.

Claude Desktop

Add the following to your 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

This writes the configuration to .mcp.json, which you can commit to share with your team.

Cursor

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (project-scoped):

{
  "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)

Open your User Settings JSON (Ctrl+Shift+P → Preferences: Open User Settings (JSON)) and add:

{
  "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

Add to ~/.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>"
      }
    }
  }
}

Verify your setup

Confirm the server is working by asking your AI assistant to run a read-only tool:

• “List my ALTR databases” calls get_databases.
• “Show me the tags connected to ALTR” calls get_tags.
• “List the ALTR roles in my org” calls get_roles.

If these return data, your setup is working.

Configuration

Set the following environment variables before starting the server:

Variable	Required	Description
ORG_ID	Yes	ALTR organization ID.
MAPI_KEY	Yes	ALTR management API key.
MAPI_SECRET	Yes	ALTR management API secret.
MCP_TRANSPORT	No	Transport protocol: stdio (default), sse, or streamable-http.
MCP_HOST	No	Bind address for HTTP transports (default: 0.0.0.0).
MCP_PORT	No	Port for HTTP transports (default: 8000).
RESTRICTED_TOOLS	No	Comma-separated tool names to hide from clients.
LOG_FORMAT	No	Log output format: console (default) or json.
LOG_LEVEL	No	Log level (default: INFO).

Restrict tools

Use the RESTRICTED_TOOLS variable to hide specific tools from MCP clients. Restricted tools are removed from the tool list and blocked if called directly. For example, to give a team read-only access without any destructive operations, list the tools to hide as a comma-separated value:

{
  "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"
      }
    }
  }
}

RESTRICTED_TOOLS is an operator-level safety net. It prevents accidental or unwanted tool usage, but it is not a substitute for scoping the permissions of your ALTR API key.

Available tools

The server exposes 156 tools across the following domains:

Domain	Tools	What it does
Databases	8	Connect Snowflake, OLTP, and Databricks data sources.
Tags	8	Manage Snowflake tag connections to ALTR.
Policies & Rules	8	Create masking policies and per-role rules, including Databricks pushdown policies, and list ALTR roles (called user groups in the console).
Classification	36	Run automated data classification scans and manage classifiers.
Access Management	4	Manage access management policies for Snowflake and OLTP.
Access Requests	6	Submit, review, and resolve Snowflake data access requests.
Audits	6	Search sidecar, Snowflake query, and platform system audits.
Audit Reports	17	Create, schedule, and review structured audit report definitions and instances.
Telemetry	9	Monitor ALTR sidecar proxy agent and instance health.
Sidecar Configuration	37	Configure the ALTR sidecar proxy — agents, repos, sidecars, listeners, bindings, and tasks.
Vault Tokenization	4	Tokenize and detokenize values using ALTR vaulted tokenization.
Critical Tokenization	4	Tokenize and detokenize values using ALTR critical tokenization.
Key Management	9	Manage Format-Preserving Encryption (FPE) keys and tweaks.

Caution

Snowflake tags and Databricks tags behave differently. A Snowflake tag is a first-class ALTR object: you register it, it receives a tag group ID, and it appears in the tag tools. A Databricks tag is not an ALTR object at all — it is a raw string passed into a pushdown policy, so it never appears in the tag tools. The Tags domain applies only to Snowflake.

Data source support

The ALTR MCP Server supports Snowflake, Databricks, and OLTP databases (PostgreSQL, MySQL, Oracle, and SQL Server accessed through a customer-managed ALTR sidecar proxy). Feature availability varies by platform. For setup, see the Snowflake, OLTP, and Databricks data source guides.

Troubleshooting

uvx: command not found — Install uv with pip install uv or the official installer.

Server not appearing in your AI client — Restart your AI client after editing the configuration file. Changes are not picked up automatically.

ERROR: Missing required environment variables — Verify that ORG_ID, MAPI_KEY, and MAPI_SECRET are set in the env block of your client configuration. Variable names are case-sensitive.

Tools returning {"success": false, ...} — Check the HTTP status in the error:

HTTP status	Likely cause	Fix
401	Invalid credentials	Verify MAPI_KEY and MAPI_SECRET in the ALTR console under Settings > Preferences > API.
403	Feature not enabled	The endpoint is gated by a feature your organization doesn’t have turned on. Contact ALTR Support to confirm the feature is enabled.
404	Resource not found	Confirm the ID exists in your organization.
429	Rate limited	The server retries automatically with backoff. If the error persists, reduce request frequency.

A tool is missing from the tool list — Check whether the tool name appears in the RESTRICTED_TOOLS environment variable in your client configuration. Restricted tools are hidden from the tool list entirely.

Learn more

• Model Context Protocol specification
• ALTR MCP Server on GitHub
• Manage API Keys
• Data Classification
• Audit Logging