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.

Example RCA flow for an agent: list_factories → list_pipeline_runs(status="Failed") → get_pipeline_run(run_id=...) for the full error message.

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.