Files
Jonathan Boniface 416c66ced4
All checks were successful
check agents / check (push) Successful in 10s
Add CP1 Discovery agents in both patterns
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>
2026-10-29 18:25:57 +00:00
..

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

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:

  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:8110)
    • 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

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_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: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)