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.

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, repositories, 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.

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.