The cp1-solution-architecture-agent and the sa-aws/azure/gcp-cloud MCP servers, a separate stream from the individual and sub-agent patterns. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Solution Architecture Azure
Azure documentation and read-only estate tools for the Solution Architecture agent, through Microsoft Learn, Resource Graph and ARM.
Version: 0.1.0
Server ID: sa-azure-cloud
Port: 8116
🚀 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>:8116.
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_search_documents: Search Microsoft Learn in free text. Queries are sent as written and logged.
- azure_get_documents: Fetch one Microsoft Learn page by URL.
- azure_analyze_access: List role assignments, optionally for one principal or below one scope.
- azure_list_instance_attached_disks: List the disks attached to one virtual machine.
- azure_list_node_pools: List AKS node pools.
- azure_search_subscriptions: List subscriptions.
- azure_list_instances: List virtual machines.
- azure_list_instance_group_managers: List scale sets.
- azure_list_instance_templates: List template specs and gallery images.
- azure_list_disks: List managed disks.
- azure_list_reservations: List capacity reservation groups.
- azure_list_clusters: List AKS clusters.
- azure_list_services: List Container Apps and App Service apps.
- azure_list_sql_instances: List SQL, PostgreSQL and MySQL servers.
- azure_list_buckets: List storage accounts.
- azure_list_topics: List Service Bus, Event Hubs and Event Grid topics.
- azure_list_roles: List role definitions.
- azure_list_alert_policies: List alert rules.
- azure_list_dashboards: List dashboards.
- azure_list_connectivity_tests: List connection monitors.
- azure_get_instance_basic_info: Read one virtual machine.
- azure_get_instance_group_manager_basic_info: Read one scale set.
- azure_get_instance_template_properties: Read one template spec or gallery image.
- azure_get_disk_basic_info: Read one disk.
- azure_get_cluster: Read one AKS cluster.
- azure_get_service: Read one app.
- azure_get_sql_instance: Read one database server.
- azure_get_topic: Read one messaging resource.
- azure_get_role: Read one role definition.
- azure_get_alert_policy: Read one alert rule.
- azure_get_connectivity_test: Read one connection monitor.
- azure_list_assets: List every resource in scope, or one resource type.
- azure_get_node_pool: Read one AKS node pool.
- azure_list_commitments: List reserved capacity orders, Azure's committed-use discounts.
- azure_get_k8s_version: List the Kubernetes versions AKS offers in one location.
- azure_list_subscriptions: List Event Grid event subscriptions.
- azure_list_deny_policies: List deny assignments.
- azure_list_metric_descriptors: List the metrics one resource publishes.
- azure_list_timeseries: Read metric values for one resource.
🔐 Authentication
This server uses Bearer token authentication for MCP protocol messages.
# Test with authentication
curl -X POST http://localhost:8116/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:8116) - 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 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 |
scope_root |
yes | no |
cloud |
no | no |
- In your tool code, read the connection with
get_connection(), and reuse an upstream client withget_upstream_client("<client kind>", build), which keeps one per kind and distinct connection. REQUIRE_VAULT_CONNECTION(defaulttrue): a call that arrives without a connection is refused, instead of using this server's own environment. Set it tofalseonly for local runs.verify_connectionis 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:8116 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 solution-architecture-azure/, then add it to
mcp_servers_to_deploy.yaml in that repository with the instances it should
run on:
- name: "solution-architecture-azure"
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:8116/health
# List tools
curl -X POST http://localhost:8116/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)