adf-mcp-server
This is a read-only MCP server for Azure Data Factory monitoring and root-cause analysis.
Health & auth:
health_checkconfirms the server is running;check_authvalidates Azure credentials.Factory discovery:
list_factoriesfinds all accessible Data Factories;get_factoryreturns details for one.Pipeline inspection:
list_pipelinesshows pipelines with lightweight activity summaries;get_pipelinegets a full activity list.Pipeline run monitoring:
list_pipeline_runslists runs in a time window with optional filters;get_pipeline_runfetches full run details.Activity-level RCA:
list_activity_runslists all activities in a run;get_failed_activity_detailsreturns only failed activities with extracted error details.Trigger diagnostics:
list_triggersandget_trigger_statusreveal whether triggers are started/stopped;list_trigger_runsshows trigger firing history.Hierarchical RCA:
get_pipeline_run_treerecursively walks Execute Pipeline activities to find failures across master/child pipeline runs.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@adf-mcp-server Show me failed pipeline runs in the last 24 hours"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
adf-mcp-server
Read-only MCP (Model Context Protocol) server for Azure Data Factory monitoring and root-cause analysis, built for use from VS Code / Claude Code.
Status: Step 1 (skeleton + health check). No Azure connectivity yet - that's added in Step 2 (auth) and Step 3 (ADF tools).
Requirements
Python 3.11+
One of:
An Azure AD App Registration (Service Principal) with Reader role on the Data Factory resource(s), or
Your own Entra ID user account with Reader role on the same (see "Auth modes" below)
Related MCP server: adf-mcp-server
Local setup
cd adf-mcp-server
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
cp .env.example .envAuth modes
This server supports two ways to authenticate to Azure, controlled by
ADF_MCP_AUTH_MODE in .env. Both go through the same check_auth /
get_credential() code path - nothing else in the codebase cares which
one is active.
Service Principal (service_principal)
Uses an app registration + client secret. Good for shared/CI use where no human needs to be present.
az ad sp create-for-rbac \
--name "adf-mcp-server-reader" \
--role "Reader" \
--scopes "/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RG_NAME>/providers/Microsoft.DataFactory/factories/<FACTORY_NAME>"Map the output into .env: AZURE_CLIENT_ID (appId), AZURE_CLIENT_SECRET
(password), AZURE_TENANT_ID (tenant).
Interactive Browser (interactive_browser)
Uses your own Entra ID sign-in - the same identity you use to log into the Azure portal - via a browser popup. No app registration or secret to manage. Good fit for solo local/VS Code use.
ADF_MCP_AUTH_MODE=interactive_browser
AZURE_TENANT_ID=<your tenant ID> # recommended - see note below
AZURE_SUBSCRIPTION_ID=<your subscription ID>RBAC note: in this mode, Azure checks your own user account's permissions, not an app registration's. Your account (or a group you're in) needs Reader on the target Data Factory - ask whoever manages RBAC to run:
az role assignment create --assignee <your-email-or-object-id> --role "Reader" \
--scope "/subscriptions/<SUB_ID>/resourceGroups/<RG>/providers/Microsoft.DataFactory/factories/<FACTORY>"Behavior:
The first time any tool needs a token, a browser window opens for you to sign in.
After that, the token is cached in memory for the life of the server process - no repeat popups until it restarts.
By default, the token cache is also persisted (encrypted, via your OS's keychain/credential manager) so restarting the server usually doesn't prompt again either. Set
ADF_MCP_AZURE_USE_PERSISTENT_TOKEN_CACHE=falsein.envto disable this and always use an in-memory-only cache.Setting
AZURE_TENANT_IDis recommended: without it, sign-in uses the multi-tenant "organizations" endpoint, which can prompt you to pick a tenant if your account belongs to more than one (e.g. a personal Microsoft account plus a work Entra ID tenant).
Running the server
python -m adf_mcp.server
# or, after `pip install -e .`:
adf-mcp-serverThe server communicates over stdio - running it directly in a terminal
will look like it hangs; that's expected, it's waiting for an MCP client
(VS Code extension, Claude Code, mcp dev, etc.) to connect via stdin/stdout.
Configuring in VS Code
Point your MCP-capable extension's server config at:
{
"command": "python",
"args": ["-m", "adf_mcp.server"],
"cwd": "/absolute/path/to/adf-mcp-server"
}Once connected:
Call
health_check- should return{"status": "ok", ...}without touching Azure at all.Call
check_auth- this makes one real call to Azure AD to acquire an ARM token. Success looks like:{"authenticated": true, "auth_mode": "service_principal", "token_expires_on": 1735000000}Failure returns a structured (not stack-trace) explanation, e.g. missing env vars or an invalid secret - see Troubleshooting below.
Call
list_factories- this makes a real call to Azure Data Factory. Returns each factory'sresource_group, which every other tool below needs as an input:{"factories": [{"name": "shell-prod-adf", "resource_group": "rg-shell-prod", "location": "eastus"}]}
Available tools (Step 3)
All tools are read-only - none of them can create, modify, trigger, or delete anything in Azure Data Factory.
Tool | Required args | Notes |
| ā | No Azure calls |
| ā | Verifies the Service Principal only |
| ā | Start here - returns |
|
| |
|
| Lightweight: name + activity count/names |
|
| Full activity list for one pipeline |
|
|
|
|
| Full, untruncated run detail - get |
Example RCA flow for an agent: list_factories ā list_pipeline_runs(status="Failed")
ā get_failed_activity_details(run_id=...) for the error breakdown directly.
Available tools (Step 4 additions)
Tool | Required args | Notes |
|
| Full activity list for a run; |
|
| The RCA tool - only failed activities, with |
|
| All triggers + current runtime state (Started/Stopped) |
|
| One trigger's runtime state - catches "pipeline never ran because its trigger was stopped" |
|
|
|
|
| Master/child RCA tool - recursively walks every Execute Pipeline activity to its child run, returning the full nested tree plus a flattened |
Full RCA flow for a failed pipeline: list_pipeline_runs(status="Failed") ā
get_failed_activity_details(run_id=...) for the error, and separately
get_trigger_status(trigger_name=...) to rule out "it never even fired."
For a master pipeline with child pipelines (Execute Pipeline
activities), use get_pipeline_run_tree(run_id=<master's run_id>) instead
of chaining get_failed_activity_details manually level by level - it
walks the whole tree in one call and tells you exactly which child
pipeline (and which activity inside it) actually failed, however deep.
Running tests
pip install -e ".[dev]" pytest-asyncio
pytest -vProject layout
See src/adf_mcp/ - server.py (MCP transport), config.py (settings),
logging_config.py (structured logging). Domain logic and Azure
connectivity are added under src/adf_mcp/domain/ from Step 3 onward.
Troubleshooting
Client shows "server disconnected" immediately: check
python -m adf_mcp.serverruns cleanly on its own first - a startup exception will kill the process before the client ever connects.Client can't parse responses / garbled output: something wrote to stdout other than the MCP protocol itself (e.g. a stray
print()). All logging in this project goes to stderr for exactly this reason.check_authreturns "Missing required Service Principal setting(s)": one ofAZURE_TENANT_ID/AZURE_CLIENT_ID/AZURE_CLIENT_SECRETis empty in.env. Note these three do NOT use theADF_MCP_prefix.check_authreturns "Azure authentication failed": usually an expired/rotated client secret, a disabled App Registration, or a tenant ID typo. Re-verify withaz ad sp show --id <AZURE_CLIENT_ID>.ClientAuthenticationError: AADSTS7000215: invalid client secret - regenerate it in the App Registration and update.env.A tool returns
{"error": "AZURE_SUBSCRIPTION_ID is not set..."}: addAZURE_SUBSCRIPTION_IDto.env- required for every ADF tool (notcheck_auth, which only needs tenant/client/secret).A tool returns
{"error": "Azure API error (403): ..."}: the Service Principal lacks Reader access to that factory/resource group - re-check theaz ad sp create-for-rbac --role Reader --scopes ...assignment from setup.A tool returns
{"error": "Azure API error (404): ..."}: check theresource_group/factory_name/pipeline_namespelling - these are case-sensitive and must match exactly whatlist_factories/list_pipelinesreturned.get_failed_activity_detailsreturns an empty list but you know the pipeline failed: the failure may be at the pipeline level (e.g. an invalid parameter) rather than any single activity - check the parent run's ownmessageviaget_pipeline_runinstead.A pipeline "just didn't run" with no failed runs at all: check
get_trigger_statusfor its trigger -runtime_state: "Stopped"means the trigger was disabled and never fired, which won't show up as a failed run because no run was ever created.check_authopens a browser but sign-in never completes / times out:interactive_browsermode waits 5 minutes by default. If you're on VS Code Remote/SSH or in a container without a reachable local browser, this mode may not work at all - fall back toservice_principalin that environment.Browser popup appears every single time you restart the server: persistence may have silently failed and fallen back to in-memory-only (check server logs for "Persistent token cache unavailable"). This is common on headless Linux without a keyring daemon running - either install/enable one (e.g.
gnome-keyringorkwallet), or accept the repeat prompts as the tradeoff of that environment.check_authsucceeds but every ADF tool returns a 403: ininteractive_browsermode this means your own account lacks Reader on the factory (not an app registration) - see the RBAC note above.get_pipeline_run_treeshows a child's activities as an empty list, but you know it has activities: the child run may have started outside the sharedstart_time/end_timewindow (default: last 7 days) - widen the window explicitly if a master pipeline runs for an unusually long time relative to its children.A deeply nested child pipeline is missing from the tree: check
truncated: trueon its parent node -max_depth(default 5) was reached. Re-run with a highermax_depthif your pipelines nest that deep.
Available Tools
13 toolscheck_authA
Verify Azure Service Principal credentials by acquiring a real ARM token.
Makes no Azure Data Factory calls - it only proves auth is configured correctly (tenant/client/secret valid, SPN enabled) before any ADF connectivity exists. Run this after health_check and before Step 3.
Inputs: no named parameters. Returns: object
get_factoryC
Get details for a single Data Factory instance.
Inputs: factory_name (required), resource_group (required). Returns: object
get_failed_activity_detailsA
RCA convenience tool: returns only the activities that failed within a pipeline run, each with error_code/message/failure_type already extracted. Prefer this over list_activity_runs when you just need "what went wrong" rather than the full activity list.
Inputs: run_id (required), factory_name (required), resource_group (required), end_time, +1 more. Returns: object
get_pipelineC
Get a single pipeline's activity list.
Inputs: factory_name (required), pipeline_name (required), resource_group (required). Returns: object
get_pipeline_runB
Get full, untruncated detail for a single pipeline run.
Get run_id from list_pipeline_runs first.
Inputs: run_id (required), factory_name (required), resource_group (required). Returns: object
get_trigger_statusB
Get a single trigger's current runtime state. A stopped trigger is a common silent cause of "why didn't this pipeline run today" - the pipeline simply was never invoked, so pipeline-run history alone won't show it.
Inputs: factory_name (required), trigger_name (required), resource_group (required). Returns: object
health_checkA
Report that the MCP server is up and configuration loaded correctly.
Useful as a first call from any MCP client (VS Code, Claude Code) to confirm the server started, before any Azure-dependent tools exist.
Inputs: no named parameters. Returns: object
list_activity_runsA
List every activity run within a pipeline run, each with error detail populated if it failed. Time window defaults to the last 7 days. Get run_id from list_pipeline_runs first.
Inputs: run_id (required), factory_name (required), resource_group (required), end_time, +1 more. Returns: object
list_factoriesA
List all Data Factory instances the configured Service Principal can see.
Returns each factory's resource_group, which every other ADF tool below requires as an input - call this first.
Inputs: no named parameters. Returns: object
list_pipeline_runsA
List pipeline runs in a time window (default: last 24 hours).
Time values are ISO 8601 strings, e.g. "2026-08-22T00:00:00Z". Narrow results with pipeline_name and/or status (e.g. "Failed", "Succeeded", "InProgress"). Run messages are truncated to 500 chars here - use get_pipeline_run with a run_id from this result for full detail.
Inputs: factory_name (required), resource_group (required), status, end_time, +2 more. Returns: object
list_pipelinesA
List pipelines in a factory with a lightweight activity summary (count and names only - use get_pipeline for full detail on one).
Inputs: factory_name (required), resource_group (required). Returns: object
list_trigger_runsA
List trigger firing history (default: last 7 days). Omit trigger_name to see every trigger's runs, or narrow to one; filter by status (e.g. "Succeeded", "Failed") to spot triggers that fired but errored.
Inputs: factory_name (required), resource_group (required), status, end_time, +2 more. Returns: object
list_triggersA
List every trigger in a factory with its current runtime state (Started/Stopped).
Inputs: factory_name (required), resource_group (required). Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogā¦
TDQS
Scored across 13 tools
Each tool targets a distinct layer of the ADF workflow: health/auth bootstrap, factory discovery, pipeline inspection, run monitoring, activity diagnostics, and trigger management. Even the closest pair, list_activity_runs and get_failed_activity_details, is clearly separated by scope and purpose.
The naming is overwhelmingly consistent with list_/get_ + resource noun in snake_case, and the run-related tools follow a clear pattern. health_check is a minor convention break compared to check_auth, but this is a small deviation in an otherwise predictable set.
13 tools is well-scoped for an ADF server: each tool maps to a distinct object hierarchy or bootstrap step without unnecessary redundancy. The count is substantial enough to cover real workflows but not bloated.
The set covers the read-only factory, pipeline, run, activity, and trigger diagnostics lifecycle well, including failure RCA. It lacks any management/remediation operations such as stopping or starting triggers, canceling runs, or rerunning pipelines, so it is slightly incomplete for full operational control.
Maintenance
Related MCP Connectors
Read-only MCP access to sessions, funnels, campaigns, errors, live visitors, and anomalies.
Read-only access to a Lumin project's logs, metrics, uptime checks, alerts and infrastructure.
Read-only MCP for identity resolution and write guardrails.
Provides read access to your GKE and Kubernetes resources.
Related MCP Servers
- AlicenseAqualityBmaintenanceEnables read-only querying of Azure Log Analytics and Azure Resource Graph through MCP, supporting KQL queries, workspace discovery, and resource inventory exploration with Azure RBAC authentication.1170 npm2MIT
- FlicenseAqualityDmaintenanceProvides a read-only MCP interface for Azure Data Factory monitoring and root-cause analysis, with a health check for MCP clients.1-
- FlicenseNot gradedqualityDmaintenanceEnables read-only monitoring and root-cause analysis of Azure Data Factory resources through MCP, allowing users to inspect factories, pipelines, and pipeline runs and diagnose failures via natural language.-
- AlicenseBqualityCmaintenanceProvides read-only access to multiple production services with unified status and timeline tools for cross-service monitoring and diagnostics.131MIT