Files
cp1-agents/mcp-servers/azure-discovery
Jonathan Boniface f659564208 Platform scripts, MCP servers, deployment and docs for the KAB runs
- Scripts to run workflows from a YAML context or run inputs (kab_run_workflow.py, with
  --input name=@file), store per-project discovery connections, bootstrap agent MCP keys,
  refresh the KAB token, publish reports and build estate snapshots.
- Hyperscaler discovery servers extended in place; cloud-knowledge folded into them.
- deploy/crucible-kab-dev.yaml: the Discovery package agent and the Assessment agents.
- Platform issue write-ups and current-wiring notes under docs/platform-issues/.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-05 22:13:25 +00:00
..

Azure Discovery

Read-only discovery of a customer's Azure estate - servers, workloads, Kubernetes clusters, networks, data stores, policies and Advisor findings - through Azure Resource Graph.

Version: 0.1.6
Server ID: azure-discovery
Port: 8111


🚀 Quick Start

The Dockerfile builds the server's image. Run it on the same network as the MCP Gateway, so the Gateway can reach it by its container name:

cp .env.example .env        # then set MCP_REGISTRATION_API_KEY
podman build -t <image-name> .
podman run -d --name <container-name> --env-file .env --network <gateway-network> <image-name>

Register it with the MCP Gateway at http://<container-name>:8111.

Local Development

# Install dependencies
pip install -r requirements.txt

# Set environment variables
cp .env.example .env
# Edit .env with your configuration

# Run the server
python server.py

📡 API Endpoints

Endpoint Method Description
/health GET Health check (no auth)
/.well-known/mcp-auth GET Authentication requirements
/messages POST MCP JSON-RPC 2.0 endpoint

🔧 Available Tools

  • azure_check_connection: Test the stored connection: sign in and read the scope root. Returns no customer data.
  • azure_list_accounts: List the estate structure: management groups, subscriptions and resource groups.
  • azure_list_resources: List every resource in scope, or one resource type, with id, type, location and tags.
  • azure_query_resources: Run a read-only Azure Resource Graph KQL query over the connection's scope. Secrets and people are removed from the results.
  • azure_get_resource_metadata: Read-only provider metadata for one resource inside the connection's scope.
  • azure_list_servers: List virtual machines, scale sets or managed disks.
  • azure_list_workloads: List App Service, Container Apps or Container Instances workloads.
  • azure_list_kubernetes_clusters: List AKS clusters with version, node pools and networking. Stops at the cloud control plane.
  • azure_get_network_topology: List virtual networks with their subnets and peerings, or route tables, NSGs, gateways, load balancers, private endpoints or public IPs.
  • azure_list_data_stores: List SQL, Cosmos DB, storage account, PostgreSQL, MySQL or Redis metadata. Never rows, documents or blobs.
  • azure_list_organization_policies: List Azure Policy assignments, definitions, initiatives, exemptions or compliance states.
  • azure_list_resource_policies: List Key Vault access policies (never secret values), storage network rules or resource locks. Principals are anonymised.
  • azure_list_recommendations: List Azure Advisor recommendations, each with a common Well-Architected pillar.
  • azure_search_well_architected: Search the Azure Well-Architected Framework's guidance by pillar and topic. Both come from fixed lists, so no customer detail leaves the platform. Microsoft Learn is public, so no credential is used.

🔐 Authentication

This server uses Bearer token authentication for MCP protocol messages.

# Test with authentication
curl -X POST http://localhost:8111/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $MCP_REGISTRATION_API_KEY" \
  -d '{"jsonrpc": "2.0", "id": "1", "method": "tools/list", "params": {}}'

📋 MCP Gateway Registration

To register this server with the MCP Gateway:

  1. Start the server (see Quick Start) where the MCP Gateway can reach it
  2. In the MCP Gateway Hub, go to MCP Servers → Add MCP Server
  3. Enter the server details:
    • URL: Use the container name as the hostname (e.g., http://weather-mcp-server:8111)
    • API Key: The MCP_REGISTRATION_API_KEY from your .env file
  4. Click the connection test icon to verify connectivity
  5. Enable the server

Note: The URL is the one the MCP Gateway uses, so for a container on the Gateway's network use its container name, not localhost.


🔑 Credentials per tenant

This server does not hold credentials for its upstream. The MCP Gateway reads the tenant's credential from the Vault Service and sends it with each call, in params._meta["com.kyndryl.mcp/connection"]. The server advertises what it needs when the gateway calls initialize:

Field Required Secret
tenant_id no no
client_id no no
client_secret no yes
access_token no yes
scope_root yes no
cloud no no
  • In your tool code, read the connection with get_connection(), and reuse an upstream client with get_upstream_client("<client kind>", build), which keeps one per kind and distinct connection.
  • REQUIRE_VAULT_CONNECTION (default true): a call that arrives without a connection is refused, instead of using this server's own environment. Set it to false only for local runs.
  • verify_connection is the tool the gateway calls to test a stored credential. It reports failure until you implement the check against the upstream.

✅ Check it before you push

tests/test_conformance.py checks the running server against what the MCP Gateway expects: it refuses callers without its key, answers JSON-RPC correctly, and, if it declares credential fields, takes the account from each request, refuses a call that carries none, names a missing field, and never repeats a credential in a reply. It needs only pytest and httpx and imports nothing from the server.

pip install pytest httpx
# with the server running (see Quick Start) and its key from .env
MCP_SERVER_URL=http://localhost:8111 MCP_REGISTRATION_API_KEY=<the key> pytest tests/ -v

A check that fails says what to fix. Run it again after you implement your tools, since a tool that reads an environment variable for its credential, or repeats one in an error, fails it. Checks that do not apply (a server with no credential fields) are skipped, not passed. To run it with REQUIRE_VAULT_CONNECTION=false on your own machine, set CONFORMANCE_EXPECT_FAIL_CLOSED=false.


🚢 Deploying through the tools repository

To have CI build and deploy this server, put this folder in the root of the modernization-tools-mcp-servers repository as azure-discovery/, then add it to mcp_servers_to_deploy.yaml in that repository with the instances it should run on:

- name: "azure-discovery"
  instances:
    - az_dev

The pipeline reads kubernetes/configmap.yaml for the server's name and port (MCP_SERVER_NAME, SERVER_PORT), generates the registration key and sets it in the pod, and registers the server with the MCP Gateway.


📝 Logging

Every line the server writes to stdout is one JSON object (timestamp, level, event, logger, server_id, and for a request request_id, method, tool), including uvicorn's and your tools' own. Each request ends with one mcp_request_completed line carrying outcome, duration_ms and error_code.

  • LOG_LEVEL sets the level (default INFO).
  • LOG_FORMAT=console prints readable lines instead, for local work.
  • In your tool code use the module's logger: logger.info("fetched_issue", key=issue_key).
  • Do not log credentials, tokens or Authorization headers.

🛠️ Development

Implementing Tools

Open server.py and find the tool implementation functions. Each tool has a placeholder that needs to be implemented:

async def your_tool_name(arguments: Dict[str, Any]) -> Dict[str, Any]:
    # TODO: Implement this tool
    raise NotImplementedError("Tool 'your_tool_name' needs implementation")

Testing

# Health check
curl http://localhost:8111/health

# List tools
curl -X POST http://localhost:8111/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $MCP_REGISTRATION_API_KEY" \
  -d '{"jsonrpc": "2.0", "id": "1", "method": "tools/list", "params": {}}'

📄 License

Generated by Agent Builder Platform - Kyndryl (template 1.1.0)