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+
• An Azure AD App Registration (Service Principal) with Reader role on the Data Factory resource(s) you want to inspect (Reader is sufficient - this server is read-only end to end, so it never needs Contributor)

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 .env

Creating the Service Principal (one-time, via az-cli)

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

This prints appId, password, and tenant - map those into .env as AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, and AZURE_TENANT_ID respectively. Scope the role assignment to the specific factory (or at most the resource group) rather than the whole subscription - least privilege, and this SPN never needs to touch anything outside ADF.

Running the server

python -m adf_mcp.server
# or, after `pip install -e .`:
adf-mcp-server

The 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:

1. Call health_check - should return {"status": "ok", ...} without touching Azure at all.
2. 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.
3. Call list_factories - this makes a real call to Azure Data Factory. Returns each factory's resource_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
health_check	—	No Azure calls
check_auth	—	Verifies the Service Principal only
list_factories	—	Start here - returns resource_group for each factory
get_factory	resource_group, factory_name
list_pipelines	resource_group, factory_name	Lightweight: name + activity count/names
get_pipeline	resource_group, factory_name, pipeline_name	Full activity list for one pipeline
list_pipeline_runs	resource_group, factory_name	start_time/end_time optional (default: last 24h), plus optional pipeline_name/status filters. Messages truncated to 500 chars.
get_pipeline_run	resource_group, factory_name, run_id	Full, untruncated run detail - get run_id from list_pipeline_runs first

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
list_activity_runs	resource_group, factory_name, run_id	Full activity list for a run; start_time/end_time optional (default: last 7 days)
get_failed_activity_details	resource_group, factory_name, run_id	The RCA tool - only failed activities, with error_code/message/failure_type already extracted
list_triggers	resource_group, factory_name	All triggers + current runtime state (Started/Stopped)
get_trigger_status	resource_group, factory_name, trigger_name	One trigger's runtime state - catches "pipeline never ran because its trigger was stopped"
list_trigger_runs	resource_group, factory_name	trigger_name optional (omit for all triggers); default window last 7 days; optional status filter

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

Running tests

pip install -e ".[dev]" pytest-asyncio
pytest -v

Project 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.server runs 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_auth returns "Missing required Service Principal setting(s)": one of AZURE_TENANT_ID / AZURE_CLIENT_ID / AZURE_CLIENT_SECRET is empty in .env. Note these three do NOT use the ADF_MCP_ prefix.
• check_auth returns "Azure authentication failed": usually an expired/rotated client secret, a disabled App Registration, or a tenant ID typo. Re-verify with az 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..."}: add AZURE_SUBSCRIPTION_ID to .env - required for every ADF tool (not check_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 the az ad sp create-for-rbac --role Reader --scopes ... assignment from setup.
• A tool returns {"error": "Azure API error (404): ..."}: check the resource_group/factory_name/pipeline_name spelling - these are case-sensitive and must match exactly what list_factories/ list_pipelines returned.
• get_failed_activity_details returns 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 own message via get_pipeline_run instead.
• A pipeline "just didn't run" with no failed runs at all: check get_trigger_status for 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.