altr-mcp-server

# ALTR MCP Server

<!-- mcp-name: io.github.altrsoftware/altr-mcp-server -->

[![PyPI](https://img.shields.io/pypi/v/altr-mcp.svg)](https://pypi.org/project/altr-mcp/)
[![Python](https://img.shields.io/pypi/pyversions/altr-mcp)](https://pypi.org/project/altr-mcp/)
[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](LICENSE.md)
[![CI](https://github.com/altrsoftware/altr-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/altrsoftware/altr-mcp-server/actions/workflows/ci.yml)
[![Security](https://github.com/altrsoftware/altr-mcp-server/actions/workflows/security.yml/badge.svg)](https://github.com/altrsoftware/altr-mcp-server/actions/workflows/security.yml)

[ALTR](https://www.altr.com) provides tag-based data masking, access governance, and classification for Snowflake, Databricks, and OLTP databases. This MCP server enables AI assistants (Claude, Cursor, and other MCP clients) to manage data security on the ALTR platform, covering database connections, tag masking, policies, classification, access management, audits, telemetry, and sidecar configuration.

> **New to ALTR?** See the [ALTR documentation](https://docs.altr.com) for an overview of the platform, concepts, and supported data sources.

All tools return structured `{success, data, error}` responses and can run over stdio, SSE, or streamable-http transports.

## Table of Contents

- [Quick Start](#quick-start)
- [Getting Credentials](#getting-credentials)
- [Configuration](#configuration)
  - [Restricting Tools](#restricting-tools)
- [Setup](#setup)
  - [Claude Desktop](#claude-desktop)
  - [Claude Code (CLI)](#claude-code-cli)
  - [Cursor](#cursor)
  - [VS Code (GitHub Copilot)](#vs-code-github-copilot)
  - [Windsurf](#windsurf)
  - [Running from Local Source](#running-from-local-source)
- [CLI](#cli-optional)
- [Tools](#tools)
- [Data Source Support](#data-source-support)
- [Troubleshooting](#troubleshooting)
- [Development](#development)
- [License](#license)

## Quick Start

1. **Install from PyPI:**

   ```bash
   pip install altr-mcp
   ```

   Or run directly with [uvx](https://docs.astral.sh/uv/guides/tools/) (no install required):

   ```bash
   uvx altr-mcp
   ```

   > `uvx` is part of the [uv](https://docs.astral.sh/uv/) Python package manager. Install it with `pip install uv` or see the [uv installation guide](https://docs.astral.sh/uv/getting-started/installation/).

2. **Set the three required environment variables** (see [Getting Credentials](#getting-credentials) for where to find each in the ALTR console):

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

3. **Wire it into your AI client** — see [Setup](#setup) for Claude Desktop, Claude Code, Cursor, VS Code, and Windsurf. The same three env vars go into the client's `env` block.

4. **Verify** 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.

## Getting Credentials

You need three values from the ALTR platform to configure this server. See [Manage API keys](https://docs.altr.com/account-and-api/api/api-keys/) for the full reference.

| Credential | Where to find it |
|---|---|
| `ORG_ID` | In the ALTR console: **Settings > Preferences > Organization** — copy the value from "ALTR Organization ID" |
| `MAPI_KEY` | In the ALTR console: **Settings > Preferences > API > Add New** — give it a description, then copy the key |
| `MAPI_SECRET` | Shown once when you create the API key above — copy and store it securely |

## 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`) |
| `MAX_RETRIES` | No | Attempts per API call before giving up (default: `3`, minimum `1`) |
| `DISABLE_RETRY` | No | Set `true` to disable retries entirely (default: `false`) |
| `REQUEST_TIMEOUT` | No | Per-request timeout in seconds (default: `30`) |
| `MAX_RETRY_AFTER` | No | Ceiling in seconds on a server-sent `Retry-After` (default: `60`) |

`MAX_RETRIES` counts total attempts, not retries on top of the first, so `1`
disables retrying without disabling the retry path. Backoff is exponential with
jitter; a `Retry-After` response header overrides it, clamped to
`MAX_RETRY_AFTER` so a server cannot park a call indefinitely.

#### What gets logged

Every tool call is logged to stderr at `INFO` with its arguments, which is what
makes a session traceable. An argument is redacted when its value is a
credential or user-supplied free text — `values`, `text`, `comments`,
`attestation`, `justification`, `statement_text_contains`, `filters`,
`connection_string`, the bare credential names (`password`, `secret`,
`credentials`, `passphrase`, `private_key`, `api_key`, `auth_token`,
`access_key`), and anything ending `_password`, `_secret`, `_credential`,
`_credentials`, `_private_key` or `_passphrase`. Identifiers, enums and
pagination cursors are logged in full.

An argument can also reach a log by travelling in a request URL, which
redaction keyed on argument names cannot see. httpx's per-request line is
therefore held at `WARNING`, so it does not appear at the default `INFO`.

Dictionary keys survive, so a line reads
`values={'ssn': '<redacted>', 'email': '<redacted>'}`: you keep which fields
were sent and lose the data. Tokens are not redacted — a token exists to be
handled freely, and ALTR's own Shield audit log is keyed by token.

Redaction covers the invocation line, tracebacks, and the argument-coercion
error returned to the caller.

`LOG_FORMAT` applies to dependency output as well as this server's own — under
`json`, every line on the stream is a JSON object, and dependency lines carry
the `correlation_id` of the tool call they occurred inside. See
[Logging](./docs/logging.md).

> **Upgrading from 0.6.0 or earlier?** Arguments were not redacted before
> 0.7.0. Treat any credential passed as a tool argument as exposed in your
> logs and rotate it — in practice `database_password` and
> `connection_string`. Those logs may also hold plaintext passed to the
> tokenize tools, so review who can read them and how long they are kept. Log
> output also changed shape; see the 0.7.0 entry in the
> [CHANGELOG](./CHANGELOG.md).

#### Endpoint overrides

Every ALTR service endpoint can be pointed elsewhere, which is useful against
a non-production ALTR environment. All are optional — leave them unset in
normal use.

The seven per-service endpoints are derived from your `ORG_ID` as
`https://<ORG_ID>.<service>.live.altr.com`, four of them with a version path
segment appended. An override replaces the whole value, so it must include that
path segment where the default has one — see the table.

| Variable | Default |
|---|---|
| `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` |

### Restricting Tools

Use `RESTRICTED_TOOLS` to hide specific tools from MCP clients. Restricted tools are removed from the tool list and blocked if called directly.

Names must match the registered tool name exactly. An entry that matches nothing restricts nothing, and is logged as a warning the first time a client lists tools. Note that 11 tools were renamed from `delete_*` to `disconnect_*` in 0.4.0.

For example, to give a team read-only access without any destructive operations:

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

Or in the Claude Desktop 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",
        "RESTRICTED_TOOLS": "disconnect_database,delete_policy,delete_rule,disconnect_tag"
      }
    }
  }
}
```

This is an operator-level safety net — it prevents accidental or unwanted tool usage but is not a substitute for proper API key permissions.

## Setup

### Claude Desktop

Add the following to your `claude_desktop_config.json` (Settings > Developer > Edit 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"
      }
    }
  }
}
```

### Claude Code (CLI)

```bash
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 config to `.mcp.json` which can be committed to share with your team.

### Cursor

Add to `~/