MCP Server

Status: Live — https://mcp.hybridsolutions.cloud/mcp (v0.3.0, 7 tools). Works in Claude Code, VS Code, Cursor, claude.ai, and Claude Desktop. Source: mcp-server/.

What it is

The HCS Governance MCP server exposes the platform's source of truth — repo registry, standards, validation profiles, and authentication — to any AI client on any machine that speaks MCP (Claude, VS Code/Copilot, Cursor, Gemini CLI).

Architecture

• Custom "HCS Governance MCP" (this server) — the bespoke parts only:
  • Tools: which_standards_apply, find_repos, get_repo, get_standard, validate, get_auth_token, get_guidance
  • Resources: registry://repos, standards://*, profiles://*, rules://hard
• Official MCP servers (compose, zero build): GitHub (https://api.githubcopilot.com/mcp/), Azure DevOps (https://mcp.dev.azure.com/{org}), Azure resources

Hosting

Component	Value
URL	https://mcp.hybridsolutions.cloud/mcp
Container App	ca-hcs-governance-mcp (rg rg-hcs-mcp-eus-01)
Registry	acrhcsmcpeus01.azurecr.io
Auth	OAuth 2.1 + PKCE, brokered to Entra (hcs-governance-mcp, appId 038eb2e4-84c3-47e0-8c4b-f559d4ea2b62)
Replicas	Pinned 1/1 (in-memory OAuth state)

Auth model

• With Entra creds configured (production): /mcp requires a Bearer token. claude.ai and Claude Desktop do a full OAuth 2.1 flow (discovery → DCR → PKCE → Entra login → token).
• Without Entra creds (dev/local): /mcp is open. Claude Code / Cursor / VS Code work directly.

Secrets in KV: mcp-entra-client-secret, mcp-oauth-signing-key.

Connecting

Claude Code / Cursor / VS Code: add https://mcp.hybridsolutions.cloud/mcp as an MCP server. No login required.

claude.ai / Claude Desktop: add https://mcp.hybridsolutions.cloud as a custom connector. It triggers an OAuth flow — sign in with your Entra account (kris@hybridsolutions.cloud).

Building and deploying

The CI/CD pipeline (mcp-server/pipelines/azure-pipelines.yml) triggers on pushes to master that touch mcp-server/**, master-registry.db, profiles/**, or docs/standards/**. It runs: validate → build/smoke-test → az acr build → az containerapp update → /health check.

Pipeline variables to set in ADO (pipeline settings → Variables):

Variable	Value
AZURE_SERVICE_CONNECTION	ADO service connection with Contributor on rg-hcs-mcp-eus-01 and AcrPush on acrhcsmcpeus01
CONTAINER_REGISTRY	acrhcsmcpeus01
IMAGE_NAME	hcs-governance-mcp
DEPLOY_TARGET	https://mcp.hybridsolutions.cloud

For manual builds (no pipeline): mcp-server/infra/Build-McpImage.ps1 -UpdateApp.

Source layout

mcp-server/
├── src/
│   ├── index.ts         — entrypoint (stdio or HTTP)
│   ├── server.ts        — MCP tools + resources
│   ├── httpServer.ts    — Streamable HTTP + OAuth gate
│   ├── oauth.ts         — OAuth 2.1 authorization server (Entra-brokered)
│   ├── auth.ts          — get_auth_token implementation
│   ├── data.ts          — governance content + hard rules
│   ├── validate.ts      — validation logic
│   └── config.ts        — env config
├── infra/               — Bicep + PowerShell deploy scripts
├── pipelines/           — azure-pipelines.yml
├── docs/                — design, operations, auth, connect guides
├── test/smoke.mjs       — stdio smoke test
└── Dockerfile

Full design + decision record: mcp-server/docs/HCS-Platform-MCP-Design.md. Operations runbook: mcp-server/docs/OPERATIONS.md.