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+

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

.env currently only needs the server settings block (ADF_MCP_*). The AZURE_* lines are placeholders for Step 2 - leave them commented out for now.

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, call the health_check tool - it should return {"status": "ok", ...} without touching Azure at all.

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.