npm package: @matillion/mcp-server
Description: MCP Server for Matillion Data Productivity Cloud Public API integration
Author: Matillion
Latest version: 1.10.0

# Matillion Public API MCP Server

An MCP (Model Context Protocol) server that enables AI agents to interact with the Matillion Data Productivity Cloud Public API.

## Features

- **Comprehensive API Coverage**: Tools covering all major Matillion API endpoints
- **Flexible Authentication**: OAuth2 client credentials flow OR direct bearer token
- JWT token caching and automatic refresh (OAuth mode)
- Multi-region support (eu/us)
- Read-only mode for safe exploration

## Quick Start

### Installation

The MCP server is published to npm and can be used immediately with npx:

```bash
npx @matillion/mcp-server
```

### Setup Steps

1. **Get your credentials** from the Matillion Data Productivity Cloud
2. **Configure your MCP client** (Claude Desktop, VS Code, etc.)
3. **Start using Matillion API tools** through your AI assistant

## Configuration

### Environment Variables

| Variable | Description | Default | Required |
|----------|-------------|---------|----------|
| `MATILLION_CLIENT_ID` | OAuth client ID | - | Yes* |
| `MATILLION_CLIENT_SECRET` | OAuth client secret | - | Yes* |
| `MATILLION_BEARER_TOKEN` | Pre-existing bearer token (bypasses OAuth) | - | No |
| `MATILLION_REGION` | Region (eu/us) | `eu` | No |
| `READ_ONLY_TOOLS` | Enable only read operations | `true` | No |
| `DEBUG` | Debug logging pattern | `matillion:*` | No |

*Required only if `MATILLION_BEARER_TOKEN` is not provided

### Security Settings

- `READ_ONLY_TOOLS=true` (default) - Only read tools available (list, get operations)
- `READ_ONLY_TOOLS=false` - All tools available including write operations (create, update, delete)

## MCP Client Configuration

### Authentication Methods

All MCP client configurations support two authentication methods:

**Method 1: OAuth Client Credentials (Recommended)**
```json
"env": {
  "MATILLION_CLIENT_ID": "your_client_id",
  "MATILLION_CLIENT_SECRET": "your_client_secret"
}
```

**Method 2: Bearer Token**
```json
"env": {
  "MATILLION_BEARER_TOKEN": "your_bearer_token"
}
```

Use either method in any of the client configurations below by replacing the `env` section with your preferred authentication approach.

### Claude Desktop

Add this configuration to your Claude Desktop MCP settings (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "matillion": {
      "command": "npx",
      "args": ["@matillion/mcp-server"],
      "env": {
        "MATILLION_CLIENT_ID": "your_client_id",
        "MATILLION_CLIENT_SECRET": "your_client_secret",
        "MATILLION_REGION": "eu"
      }
    }
  }
}
```

### VS Code MCP Extension

Enable the MCP extension if not already enabled and add this the following to `.vscode/mcp.json`:

```json
{
  "servers": {
    "matillion": {
      "command": "npx",
      "args": ["@matillion/mcp-server"],
      "env": {
        "MATILLION_CLIENT_ID": "your_client_id",
        "MATILLION_CLIENT_SECRET": "your_client_secret",
        "MATILLION_REGION": "eu"
      }
    }
  }
}
```

### Claude Code

Add this configuration to your Claude Code MCP settings (`~/.claude.json`):

```json
{
  "mcpServers": {
    "matillion": {
      "command": "npx",
      "args": ["@matillion/mcp-server"],
      "env": {
        "MATILLION_CLIENT_ID": "your_client_id",
        "MATILLION_CLIENT_SECRET": "your_client_secret",
        "MATILLION_REGION": "eu"
      }
    }
  }
}
```

### Other MCP Clients

For any MCP-compatible client, use:
- **Command**: `npx`
- **Args**: `["@matillion/mcp-server"]`
- **Environment**: Set the required authentication variables

## Command Line Usage

Run the MCP server directly with npx:

```bash
# Basic usage
npx @matillion/mcp-server

# With environment variables
MATILLION_CLIENT_ID=your_id MATILLION_CLIENT_SECRET=your_secret npx @matillion/mcp-server

# Using bearer token
MATILLION_BEARER_TOKEN=your_token npx @matillion/mcp-server
```

### Command Line Options

```bash
npx @matillion/mcp-server [options]

Options:
  --region <region>        Set region (eu/us) [default: eu]
  --read-only             Enable read-only mode [default: true]
  --debug                 Enable debug logging
  --version               Show version information
  --help                  Show help information
```

## Available Tools

The server provides access to the following Matillion API tools. All tools are categorized by their operation type:
- **Read** tools are always available (list, get operations)
- **Write** tools require `READ_ONLY_TOOLS=false` (create, update, delete operations)

| Category | Tool Name | Type | Description |
|----------|-----------|------|-------------|
| **Agents** | `list-agents` | Read | List all compute agents |
| **Agents** | `get-agent-details` | Read | Get details for a specific agent |
| **Agents** | `list-agent-credentials` | Read | List agent client credentials |
| **Agents** | `get-agent-access-list` | Read | Get the agent allow list |
| **Agents** | `create-agent` | Write | Create a new compute agent |
| **Agents** | `update-agent` | Write | Update an existing agent |
| **Agents** | `delete-agent` | Write | Delete an agent |
| **Agents** | `send-agent-command` | Write | Trigger an agent command |
| **Agents** | `post-agent-credentials` | Write | Perform actions on agent credentials |
| **Agents** | `add-to-agent-access-list` | Write | Add project(s)/environment(s) to the agent allow list |
| **Agents** | `set-agent-access-list` | Write | Set (replace) the entire agent allow list |
| **Agents** | `delete-agent-allowlist-project` | Write | Remove a project from the agent allow list |
| **Artifacts** | `list-artifacts` | Read | Get a list of artifacts |
| **Artifacts** | `get-artifact-details` | Read | Get artifact details by version name |
| **Artifacts** | `get-artifact-details-v2` | Read | Get artifact with asset details (v2) |
| **Artifacts** | `create-artifact` | Write | Create a new artifact |
| **Artifacts** | `promote-artifact` | Write | Promote an artifact |
| **Artifacts** | `patch-artifact` | Write | Flag an artifact to enable or disable |
| **Audit Events** | `get-audit-events` | Read | Query audit events in a time range |
| **Connections** | `create-data-platform-connection` | Write | Create a default data warehouse connection |
| **Connectors** | `list-custom-connectors` | Read | List custom connector profiles |
| **Connectors** | `list-flex-connectors` | Read | List flex connector profiles |
| **Consumption** | `get-consumption` | Read | Get credit consumption for flat-rated products |
| **Consumption** | `get-consumption-etl-users` | Read | Get credit consumption for ETL users |
| **Environments** | `list-environments` | Read | List all environments in a project |
| **Environments** | `create-environment` | Write | Create a new environment |
| **Environments** | `delete-environment` | Write | Delete an environment |
| **Lineage** | `get-lineage-events` | Read | Get OpenLineage events for a specified time period |
| **Pipeline Execution** | `list-pipeline-executions` | Read | List pipeline executions across all projects |
| **Pipeline Execution** | `list-project-pipeline-executions` | Read | List pipeline executions for a specific project |
| **Pipeline Execution** | `get-execution-details` | Read | Get pipeline execution status |
| **Pipeline Execution** | `get-execution-steps` | Read | Get pipeline execution steps status |
| **Pipeline Execution** | `execute-pipeline` | Write | Execute a published pipeline |
| **Pipeline Execution** | `patch-pipeline-execution` | Write | Terminate a pipeline execution |
| **Pipelines** | `list-published-pipelines` | Read | List all published pipelines in a project |
| **Projects** | `list-projects` | Read | List all projects |
| **Projects** | `create-project` | Write | Create a new project |
| **Projects** | `delete-project` | Write | Delete a project |
| **Repositories** | `create-repository` | Write | Associate a repository with a project |
| **Schedules** | `list-schedules` | Read | List all schedules for a project |
| **Schedules** | `get-schedule-details` | Read | Get schedule summary by schedule ID |
| **Schedules** | `create-schedule` | Write | Create a new schedule |
| **Schedules** | `update-schedule` | Write | Update an existing schedule |
| **Schedules** | `delete-schedule` | Write | Delete a schedule |
| **Secret References** | `list-secret-references` | Read | List all secret references in a project |
| **Secret References** | `create-secret-reference` | Write | Create a secret reference |
| **Secret References** | `delete-secret-reference` | Write | Delete a secret reference |
| **Streaming Pipelines** | `list-streaming-pipelines` | Read | List streaming pipeline definitions |
| **Streaming Pipelines** | `get-streaming-pipeline-details` | Read | Get a streaming pipeline definition |
| **Streaming Pipelines** | `get-streaming-pipeline-status` | Read | Get a streaming pipeline's status |
| **Streaming Pipelines** | `create-streaming-pipeline` | Write | Create a streaming pipeline definition |
| **Streaming Pipelines** | `update-streaming-pipeline` | Write | Update a streaming pipeline definition |
| **Streaming Pipelines** | `delete-streaming-pipeline` | Write | Delete a streaming pipeline definition |
| **Streaming Pipelines** | `send-streaming-pipeline-command` | Write | Execute a streaming pipeline command |

### MCP Protocol Features

- ✅ **Tools**: All 54 Matillion API endpoints exposed as MCP tools
- ✅ **Resources**: Pipeline executions, artifacts, and projects as readable resources
- ✅ **Prompts**: Built-in prompt templates for common workflows
- ✅ **Error Handling**: Structured error responses with details
- ✅ **Authentication**: Secure OAuth2 + JWT token management

## Usage Tips

1. **Start with zero-parameter tools**: Use `list-projects`, `list-agents`, etc. to explore your accessible resources
2. **Progressive discovery**: Use `list-projects` → `list-project-environments` → `list-published-pipelines` for hierarchical browsing
3. **Execution monitoring**: Use `list-pipeline-executions` without filters to see recent activity, or add filters for specific searches
4. **UUID format**: All `projectId` parameters must be valid UUIDs (e.g., `123e4567-e89b-12d3-a456-426614174000`)

## Debug Logging

Debug logging is enabled by default with the pattern `matillion:*`. You'll see detailed logs for:

- OAuth token acquisition and refresh
- HTTP requests and responses
- API call details
- Configuration loading
- Tool invocations

To disable debug logging, set `DEBUG=""` or remove the environment variable.

## Development

### Checking API Coverage

A Claude Code skill is included to verify that the MCP server tools remain in
sync with the Matillion Public API spec. Run it from within this project using
Claude Code:

```
/check-api-coverage
```

This will:
1. Download the latest OpenAPI spec and split it into per-tag YAML files under `tmp/`
2. Compare each tag against the corresponding tool implementations in `src/tools/`
3. Report a coverage summary and list any missing or unimplemented endpoints

The `tmp/` directory is gitignored. You can also inspect the downloaded files
directly — `tmp/public-api-endpoint-reference.yaml` contains the full raw spec,
and `tmp/<tag>.yaml` files contain the per-tag path subsets.

To run the parser script on its own (without the full coverage check):

```bash
python3 scripts/parse_api_spec.py
```

## Documentation

For more information:
- [MCP Server Documentation](https://docs.matillion.com/data-productivity-cloud/api/docs/matillion-mcp-server/)