Matillion's MCP server🔗

Matillion's Model Context Protocol (MCP) server offers a secure, standardized way for Large Language Models (LLMs) to interact with your Data Productivity Cloud resources. By configuring the MCP server, you can enable AI assistants to help with tasks such as monitoring pipeline executions, analyzing credit consumption, and triggering pipeline runs.

You can configure popular AI assistant clients to use the Matillion MCP server (@matillion/mcp-server). The server is distributed as an NPM package and launched using npx, which works with clients that can start local processes.

Use cases🔗

Use case	Scenario	MCP server solution
Pipeline monitoring	Data engineers need to quickly investigate pipeline failures and understand execution history.	Ask your AI assistant to investigate failed pipelines in natural language. It can search through recent executions, identify failures, drill into specific step-level errors, and explain what went wrong. You can query by time range, pipeline name, or execution status, and see comprehensive failure analysis, including step-by-step breakdowns and data lineage impact assessment.
Cost optimization	Finance and data teams need to understand credit consumption patterns and optimize spending.	Ask your AI assistant to analyze your credit consumption and identify optimization opportunities. See breakdowns of credit usage by pipeline and execution frequency. Your AI assistant can identify your most expensive pipelines, suggest scheduling optimizations, and correlate execution patterns with costs to help you make informed decisions about resource allocation.
Pipeline execution	Data engineers need to manually trigger pipeline runs with custom parameters.	Execute pipelines on demand with custom parameters through natural language requests like "run the customer_data pipeline with start_date=2025-01-01." Your AI assistant can trigger manual runs with custom variables and monitor execution progress. This gives you flexible control over pipeline execution without needing to remember complex parameter formats.
Streaming pipelines	Teams managing streaming pipelines need to monitor their status and control execution dynamically.	Check the status of streaming pipelines and run them through conversation. Ask your AI assistant questions like "is the Kafka to Snowflake pipeline running?" to get real-time status updates, performance metrics, and event processing statistics. You can also request actions like "stop the streaming pipeline temporarily" to dynamically control execution.

Prerequisites🔗

Before setting up the Matillion MCP server, ensure you meet the following prerequisites:

Node.js is installed on your system. We recommend at least v24.
npm is installed on your system. Version 11 (minimum recommended) should come with Node.js v24 and above.
The npx command must be available in your system's global PATH.
You have your Matillion region, client ID, and client secret.
At least one installed AI client, such as Claude Desktop or the Gemini CLI.

Obtaining Matillion credentials🔗

To find your Matillion region, and to create your Matillion API credentials (client ID and client secret):

Log in to the Data Productivity Cloud.
In the left navigation, click your Profile & Account icon.

Note

Your Matillion region is shown below your account name. Enter eu if your Matillion region starts with EU, or us if it starts with US.
Then, select API credentials from the menu.
If you don't have credentials, click Set an API Credential to create a Client ID and Client Secret. Read Authenticating to the API to learn how to create API credentials.
Give your credential set a descriptive Name. We recommend that you use a name that suits the application or purpose the credentials will be used for.
Click Save to create the Client ID and Secret.
Copy the secret immediately. You are not able to view the secret again after this point. If you do not copy it, or otherwise lose it, you will need to delete these credentials and generate a new set. The Secret window will close automatically after this point.

Environment variables🔗

Variable	Description	Default value	Required
`MATILLION_CLIENT_ID`	OAuth client ID. To create your API credentials, read Obtaining Matillion credentials.	-	Yes (if `MATILLION_BEARER_TOKEN` is not provided)
`MATILLION_CLIENT_SECRET`	OAuth client secret. To create your API credentials, read Obtaining Matillion credentials.	-	Yes (if `MATILLION_BEARER_TOKEN` is not provided)
`MATILLION_BEARER_TOKEN`	A pre-existing bearer token (bypasses OAuth).	-	No
`MATILLION_REGION`	Your region (either `eu` or `us`). To find your region, read Obtaining Matillion credentials.	`eu`	No
`READ_ONLY_TOOLS`	Enable only read operations. Set to `false` to enable all tools, including write operations. For more information, see Available tools.	`true`	No
`DEBUG`	Debug logging pattern.	`matillion:*`	No

Claude Desktop🔗

Claude Desktop uses a global configuration file to launch MCP servers. Find your Claude Desktop configuration file. If it doesn't exist, create it at the following location:

For macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
For Windows: %APPDATA%\Claude\claude_desktop_config.json

To use the MCP server with Claude Desktop:

Choose which authentication method to use, then replace the placeholders in the corresponding JSON configuration below with your credentials.
Copy your chosen JSON configuration, including the opening and closing {}, into the Claude Desktop configuration file. If the file already has content, merge the mcpServers object into the existing content.
Quit the Claude Desktop app by right-clicking the Claude icon and then clicking Quit. Closing the window will not quit the app completely.
Restart Claude Desktop. The Matillion MCP server will now be available.

JSON configurations🔗

To authenticate using 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": "your_region"
      }
    }
  }
}

To authenticate using a bearer token:

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

Claude Code🔗

There are two ways to configure the MCP server for use with Claude Code. Choose one of the following methods:

Replace the placeholders in one of the JSON configurations in the Claude Desktop section with your credentials, then copy the mcpServers block into the ~/.claude.json file.

Replace the placeholders in the following command with your credentials, then run the command.

claude mcp add matillion \
  --scope "user" \
  --env MATILLION_CLIENT_ID="your_client_id" \
  --env MATILLION_CLIENT_SECRET="your_client_secret" \
  --env MATILLION_REGION="your_region" \
  -- npx -y @matillion/mcp-server

Claude Code with Visual Studio Code🔗

To use the MCP server with Claude Code and Visual Studio Code:

Enable the MCP extension, if this is not already enabled.
Open your project workspace in Visual Studio Code.
Create or open the .vscode/mcp.json file.
Replace the placeholders in the JSON configuration below with your credentials.
Copy the JSON configuration, including the opening and closing {}, into the .vscode/mcp.json file. If the file already has content, merge the servers object into the existing content.
Restart Visual Studio Code. The Matillion MCP server will now be available.

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

Gemini CLI🔗

The Gemini CLI uses a global settings.json file in your user profile. Find your Gemini CLI configuration file. If it doesn't exist, create it at the following location:

For macOS or Linux: ~/.gemini/settings.json
For Windows: $HOME/.gemini/settings.json (where $HOME is your user profile directory, e.g. C:\Users\YourName)

To use the MCP server with Gemini:

Replace the placeholders in the JSON configuration below with your credentials.
Copy the JSON configuration, including the opening and closing {}, into the Gemini CLI configuration file. If the file already has content, merge the mcpServers object into the existing content.
If the Gemini CLI is currently running in your terminal, use the /quit command to quit the CLI.
Restart the Gemini CLI. The Matillion MCP server will now be available.

JSON configuration🔗

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

Other MCP-compatible clients🔗

For any other MCP-compatible client, use:

Command: npx
Args: ["@matillion/mcp-server"]
Environment: Set the required authentication variables

Unsupported clients🔗

The Matillion MCP server cannot currently be configured for the following clients:

ChatGPT (Desktop and Web)
Claude.ai (Web)
Browser-based AI clients

Available tools🔗

The server provides access to the following Matillion API tools. Read tools are always available, while Write tools require READ_ONLY_TOOLS to be set to false.

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

Debug logging🔗

Debug logging is enabled by default with the pattern matillion:*. This provides 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.

Got feedback or spotted something we can improve?

We'd love to hear from you. Join the conversation in the Documentation forum!