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 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.
task management	Teams want to delegate pipeline development and maintenance work to , supervise their progress, and review their decisions without switching tools.	Create and manage ’ tasks through conversation. Ask your AI assistant to start a new task with an instruction and mode, then monitor its status and message history as it works. Review and respond in-line when are waiting on a decision, such as approving a tool call or answering a question. You can also update task permissions, send follow-up messages to adjust a running task, and stop or delete tasks when they’re no longer needed.
Test executions	Teams want to validate pipeline changes by running tests before promoting an artifact or merging changes. They can use these tools to trigger runs, track results, and stop executions without leaving their AI assistant.	Ask your AI assistant to run tests in natural language and monitor the outcome—for example, “run all tests in the Analytics project against the Dev environment and tell me when they finish”. Your AI assistant can trigger runs for specific tests, pipelines, or whole projects, track results, and stop runaway executions on demand.

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.

doesn’t use Node.js as part of its core SaaS platform, so there’s no Node.js version associated with the service. Node.js is only relevant for the Matillion MCP server. Matillion doesn’t manage the Node.js version; you define it based on your deployment environment.

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 .
In the left navigation, click your Profile & Account icon.
Your Matillion region is shown below your account name. The value of the MATILLION_REGION environment variable will be eu if your Matillion region starts with EU, us if it starts with US, or au if it starts with AU.
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 Authenticate to the Maia 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 (`eu`, `us`, or `au`). 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:

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.

For more information, read the Visual Studio Code Configure the mcp.json file guide.

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

Tool name	Type	Description
AI Agents
`create-agent-task`	Write	Create a new task
`list-agent-tasks`	Read	List ’ tasks for the account
`get-agent-task`	Read	Get a task’s status, configuration, and pending decisions
`get-agent-task-messages`	Read	Get the message history and events for a task
`send-agent-task-message`	Write	Send a follow-up message to a running task to grant permissions or update the task configuration
`submit-agent-task-decisions`	Write	Approve or reject tool calls that are waiting on, and answer pending questions
`set-agent-task-permissions`	Write	Replace the full list of granted tool permissions for a task
`wait-for-agent-task`	Read	Monitor a task until it reaches a pending decision, terminal state, or timeout
`stop-agent-task`	Write	Stop a task that is currently running
`delete-agent-task`	Write	Delete a task that has been stopped
Artifacts
`list-artifacts`	Read	Get a list of artifacts
`get-artifact-details`	Read	Get artifact details by version name
`get-artifact-details-v2`	Read	Get artifact with asset details (v2)
`create-artifact`	Write	Create a new artifact
`promote-artifact`	Write	Promote an artifact
`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
`list-flex-connectors`	Read	List flex connector profiles
Consumption
`get-consumption`	Read	Get credit consumption for flat-rated products
`get-consumption-etl-users`	Read	Get credit consumption for ETL users
Environments
`list-environments`	Read	List all environments in a project
`create-environment`	Write	Create a new environment
`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
`list-project-pipeline-executions`	Read	List pipeline executions for a specific project
`get-execution-details`	Read	Get pipeline execution status
`get-execution-steps`	Read	Get pipeline execution steps status
`execute-pipeline`	Write	Execute a published pipeline
`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
`create-project`	Write	Create a new project
`delete-project`	Write	Delete a project
Repositories
`create-repository`	Write	Associate a repository with a project
Runners
`list-agents`	Read	List all s
`get-agent-details`	Read	Get details for a specific
`list-agent-credentials`	Read	List client credentials
`get-agent-access-list`	Read	Get the allow list
`create-agent`	Write	Create a new
`update-agent`	Write	Update an existing
`delete-agent`	Write	Delete a
`send-agent-command`	Write	Trigger a command
`post-agent-credentials`	Write	Perform actions on credentials
`add-to-agent-access-list`	Write	Add project(s)/environment(s) to the allow list
`set-agent-access-list`	Write	Set (replace) the entire allow list
`delete-agent-allowlist-project`	Write	Remove a project from the allow list
Schedules
`list-schedules`	Read	List all schedules for a project
`get-schedule-details`	Read	Get schedule summary by schedule ID
`create-schedule`	Write	Create a new schedule
`update-schedule`	Write	Update an existing schedule
`delete-schedule`	Write	Delete a schedule
Secret References
`list-secret-references`	Read	List all secret references in a project
`create-secret-reference`	Write	Create a secret reference
`delete-secret-reference`	Write	Delete a secret reference
Streaming Pipelines
`list-streaming-pipelines`	Read	List streaming pipeline definitions
`get-streaming-pipeline-details`	Read	Get a streaming pipeline definition
`get-streaming-pipeline-status`	Read	Get a streaming pipeline’s status
`create-streaming-pipeline`	Write	Create a streaming pipeline definition
`update-streaming-pipeline`	Write	Update a streaming pipeline definition
`delete-streaming-pipeline`	Write	Delete a streaming pipeline definition
`send-streaming-pipeline-command`	Write	Execute a streaming pipeline command
Test Execution
`list-test-executions`	Read	List test executions across all projects, with optional filters (project, test name, environment, status, time range)
`get-test-execution-status`	Read	Get the status and details of a specific test execution
`create-test-execution`	Write	Trigger test executions for a project, with the scope TEST (named test files), PIPELINE (tests for given pipelines), or PROJECT (all tests)
`cancel-test-execution`	Write	Cancel a running test execution, with the option to force termination

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.

Overview

Endpoints

Use cases

Prerequisites

Obtaining Matillion credentials

Environment variables

Claude Desktop

JSON configurations

Claude Code

Claude Code with Visual Studio Code

Gemini CLI

JSON configuration

Other MCP-compatible clients

Unsupported clients

Available tools

Debug logging

​Use cases

​Prerequisites

​Obtaining Matillion credentials

​Environment variables

​Claude Desktop

​JSON configurations

​Claude Code

​Claude Code with Visual Studio Code

​Gemini CLI

​JSON configuration

​Other MCP-compatible clients

​Unsupported clients

​Available tools

​Debug logging

Use cases

Prerequisites

Obtaining Matillion credentials

Environment variables

Claude Desktop

JSON configurations

Claude Code

Claude Code with Visual Studio Code

Gemini CLI

JSON configuration

Other MCP-compatible clients

Unsupported clients

Available tools

Debug logging