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

Claude Desktop

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

Option A: OAuth Credentials

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

Option B: Bearer Token

{
  "mcpServers": {
    "matillion": {
      "command": "npx",
      "args": ["@matillion/mcp-server"],
      "env": {
        "MATILLION_BEARER_TOKEN": "your_bearer_token",
        "MATILLION_REGION": "eu"
      }
    }
  }
}

VS Code MCP Extension

Install the MCP extension and add this to your VS Code settings:

{
  "mcp.servers": {
    "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 capabilities:

| Category | Description | |----------|-------------| | Agents | Manage compute agents (create, update, delete, send commands) | | Artifacts | Manage and promote pipeline artifacts | | Audit Events | Query audit log events | | Connections | Manage data platform connections | | Connectors | List available connectors | | Consumption | View credit usage analytics | | Environments | Create and manage environments | | Lineage | Track data lineage events | | Pipeline Execution | Execute and monitor pipeline runs | | Pipelines | List published pipelines | | Projects | Project operations (create, list, delete) | | Repositories | Manage Git repositories | | Schedules | Create and manage pipeline schedules | | Secret References | Manage secret references | | Streaming Pipelines | Real-time pipeline management |

MCP Protocol Features

• ✅ Tools: All 51 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