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:

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)

"env": {
  "MATILLION_CLIENT_ID": "your_client_id",
  "MATILLION_CLIENT_SECRET": "your_client_secret"
}

Method 2: Bearer Token

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

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

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

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

# 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

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 | get-agent-credentials | Read | Get agent client credentials | | 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 | | 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 50 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.

Documentation

For more information:

• MCP Server Documentation