ALZ-F01 Discovery as a sub-agent orchestrator (sub-agents/) and as eight individual declarative agents (individual-agents/), with their KAB workflow exports. Shared check, render and import scripts, the alz-discovery-sample MCP server, the crucible-kab-dev deploy profile, deployment docs, platform issue reports and the source material. Agent steps time out at 20 minutes. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
ALZ Discovery Sample
Read-only sample data for Agentic Landing Zone discovery (Meridian Retail Group) - scope, estate scans, CMDB and ITSM, inventory, schemas, dependencies, network and the run's MCP call log.
Version: 0.1.0
Server ID: alz-discovery-sample
Port: 8110
🚀 Quick Start
As a container (recommended)
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>:8110.
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
- get_scope: Return the engagement's scope entries, projected to scope_entry_id, hostname, role and site (never notes).
- list_sources: List the engagement's registered data sources (connectors) and the tool that serves each.
- get_budgets: Return the run's scan-rate, token and tool-call budgets.
- scan_target: Return one scope entry's metadata (agentless, metadata level). Only a scope_entry_id is accepted.
- get_resource_metadata: Read-only provider metadata for one in-scope cloud resource. The sample estate has no cloud resources.
- ingest_cmdb: Pull configuration items through a registered CMDB connector (read-only).
- ingest_itsm: Pull incidents and changes (last 12 months) through a registered ITSM connector (read-only).
- cmdb_query: Find candidate CIs for one canonical inventory record, matched by serial, FQDN or hostname.
- diff_records: Compare one canonical record with one CI attribute by attribute (os, environment, owner, business_service, site, status).
- list_apps: List the assets and applications known to the engagement across the loaded sources.
- get_app: Return all source records for one application - its scope entries' scan metadata and CMDB CIs.
- scan_schema: Return table and column metadata (names, types, comments) for one data store. Never returns row data.
- get_dependencies: Return the declared and CMDB relationships for one scope entry.
- trace_calls: Return observed calls and flows (metadata only) involving one scope entry, and connection strings found in configuration.
- trace: Correlate relationships, configuration and flows into candidate dependency edges for a set of scope entries.
- collect_topology: Read devices, links, routed ranges and IPAM for one in-scope site (read-only).
- map_flows: Aggregate flow-log metadata into a source-destination-port matrix for one site. Metadata only, never payloads.
- analyze_bottlenecks: Return p95 utilisation, latency and loss per link for one site over a window.
- get_call_log: Return this server's MCP call log - tool, argument hash, outcome and evidence_ref of every call - for the critic.
- get_guard_hits: Return the injection-guard hits recorded on tool results - scope entries whose fields carry instructions aimed at an agent.
🔐 Authentication
This server uses Bearer token authentication for MCP protocol messages.
# Test with authentication
curl -X POST http://localhost:8110/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:
- Start the server (see Quick Start) where the MCP Gateway can reach it
- In the MCP Gateway Hub, go to MCP Servers → Add MCP Server
- Enter the server details:
- URL: Use the container name as the hostname (e.g.,
http://weather-mcp-server:8110) - API Key: The
MCP_REGISTRATION_API_KEYfrom your.envfile
- URL: Use the container name as the hostname (e.g.,
- Click the connection test icon to verify connectivity
- 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
This server declares no connection fields, so it holds no credentials for an upstream system. If a tool needs to reach a system with a credential, add connection fields in the MCP Server Builder: each tenant then supplies its own, kept in the Vault Service, instead of one credential in this server's environment.
✅ 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:8110 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 alz-discovery-sample/, then add it to
mcp_servers_to_deploy.yaml in that repository with the instances it should
run on:
- name: "alz-discovery-sample"
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_LEVELsets the level (defaultINFO).LOG_FORMAT=consoleprints 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:8110/health
# List tools
curl -X POST http://localhost:8110/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.0.0)