Technical Architecture — For CTOs

System Overview

Two systems, one platform

Agent Accelerator consists of two primary systems that work together: a design-time engine and a production runtime.

                DESIGN TIME                              RUNTIME
        +--------------------------+           +--------------------------+
        |      Build Studio        |           |      MCP Gateway         |
        |  (AI Agent Architect)    |           |  (Enterprise Runtime)    |
        |                          |           |                          |
        |  14-step design wizard   |           |  .NET 10.0 Web API       |
        |  DSL generation          |---------->|  MCP 2025-03-26 spec     |
        |  Platform packages       | generates |  Multi-tenant            |
        |  Compliance validation   | connector |  Plugin architecture     |
        |  Governance planning     | + specs   |  Enterprise auth         |
        |  Engineering specs       |           |  Session management      |
        +--------------------------+           +-------------+------------+
                    |                                        |
                    | generates                              | connects to
                    v                                        v
        +--------------------------+           +--------------------------+
        |   Platform Packages      |           |   Enterprise Systems     |
        |                          |           |                          |
        |  Copilot Studio (.zip)   |           |  ServiceNow              |
        |  Bedrock (scaffolds)     |           |  Microsoft 365           |
        |  Vertex AI (scaffolds)   |           |  OneDrive / SharePoint   |
        |                          |           |  Outlook                 |
        +--------------------------+           |  Custom APIs             |
                                               +--------------------------+

Build Studio Architecture

Design-time engine

Execution Model

Build Studio is a step-file architecture that executes within an AI coding assistant (Claude Code). It's not a hosted SaaS product — it runs in your development environment, reading and writing files to your repository.

Sequential step processing with just-in-time file loading:

● Each of 14 steps is a self-contained instruction file
● Only the current step is loaded into memory
● State is tracked in the output DSL file's YAML frontmatter
● Progress persists across sessions (resume-capable)

AI Research Pipeline

Build Studio uses MCP tools to research recommendations:

microsoft_docs_search Official Microsoft documentation
context7 Library and framework documentation
web_search Industry patterns and best practices

Recommendations are documented in research-notes.md with source citations, making the design process auditable and reproducible.

DSL (Domain-Specific Language)

The core output is a platform-agnostic YAML file that captures the complete agent definition:

version: "1.0"
metadata:
  name: "agent-name"
  target_platforms:
    primary: copilot_studio
    secondary: [bedrock]

identity:
  persona: "..."
  expertise: [...]
  communication_style: professional_friendly

capabilities:
  - name: "Capability Name"
    recommended_by: build_studio_research

tools:
  - name: "tool_name"
    integration:
      type: mcp_gateway
      endpoint: "https://gateway/mcp/agent"

workflows:
  - name: "workflow_name"
    orchestration: generative
    fallback: { behavior: graceful_redirect }

platform_hints:
  copilot_studio:
    channels: [teams, web_chat]

Platform Generators

Each generator reads the DSL and produces platform-specific artifacts:

Copilot Studio Generator Production-ready

› Generates bot.xml from identity + metadata
› Creates AI Action definitions from tools section
› Produces custom connector from MCP Gateway specs
› Generates Power Automate flows from workflows
› Packages into importable .zip solution

Bedrock Generator POC

› Action Group definitions, Lambda stubs, CloudFormation

Vertex AI Generator POC

› Cloud Functions, Terraform templates, Dialogflow CX

Compliance Engine

The compliance validation system uses a data-driven approach with 73 versioned checks:

checks:
  - id: AGT-001
    name: "Authentication Mode"
    domain: agent_level
    severity: FAIL
    source_file: configuration.json
    validation: "authenticationMode == 'entra_id'"
    remediation: "Set authentication to Entra ID"
    frameworks: [GDPR, SOC2, HIPAA, ISO27001]

The engine scans generated artifacts against each check, produces a structured report with pass/fail/warn results, and maps findings to regulatory frameworks.

MCP Gateway Architecture

Production-grade runtime

Technology Stack

Layer	Technology
Runtime	.NET 10.0
Framework	ASP.NET Core Web API
MCP SDK	ModelContextProtocol.AspNetCore 0.4.1-preview.1
Logging	Serilog (structured, with enrichment)
Metrics	OpenTelemetry (App Insights + Prometheus)
IaC	Bicep (Azure Resource Manager)
CI/CD	Azure Pipelines
Container	Docker (multi-stage .NET build)

Project Structure

src/
├── McpGateway.Api/              ASP.NET Core entry point
│   ├── Program.cs               DI, middleware pipeline, MCP registration
│   ├── Middleware/
│   │   ├── ApiKeyAuthenticationMiddleware.cs
│   │   ├── SessionRecoveryMiddleware.cs
│   │   └── RequestLoggingMiddleware.cs
│   ├── McpTools/
│   │   ├── GatewayToolHandler.cs         Tool execution routing
│   │   └── PerRequestTokenResolver.cs    OAuth/SSO token management
│   ├── OAuth/                            OAuth 2.1 + DCR server
│   └── HealthChecks/                     Operational probes
│
├── McpGateway.Core/             Domain logic (no framework dependencies)
│   ├── Tools/
│   │   ├── IToolPlugin.cs       Plugin contract
│   │   ├── IToolRegistry.cs     Tool discovery & routing
│   │   └── ToolDescriptor.cs    Tool metadata + JSON Schema
│   ├── Agents/
│   ├── AccessControl/
│   └── Sessions/
│
├── McpGateway.Transport/        MCP protocol transport
│   ├── StreamableHttpTransport.cs    Modern HTTP/Streaming
│   └── SseTransport.cs              Legacy SSE fallback
│
└── McpGateway.Plugins.*/        Plugin implementations
    ├── ServiceNow/              14 tools, 580+ tests
    ├── Documents/               PDF/Excel generation
    ├── OneDrive/                File operations
    ├── Email/                   Outlook integration
    ├── DateTime/                Time utilities
    ├── Weather/                 Open-Meteo API
    └── Echo/                    Testing tools

Request Flow

1

Client Request

POST /mcp/{agentId} with Bearer token

2

Auth Middleware

Validate API key / JWT / OAuth / mTLS

3

Session Mgmt

Find/create session, apply namespace perms

4

MCP Processing

initialize, tools/list, tools/call

5

Tool Execution

Resolve namespace, check auth, dispatch

6

Plugin Exec

Auth to external system, execute, return

7

Response

Format as MCP response, return to client

Authentication Architecture

                +-----------------------+
                |   Authentication      |
                |   Middleware           |
                +----------+------------+
                           |
          +----------+-----+-----+----------+-----------+
          |          |           |           |           |
     API Key    JWT/Entra   OAuth 2.1    mTLS     User Token
     (SHA256)   (issuer    (+DCR)       (CN      Pass-through
      hash)     validate)               extract)  (OBO flow)
          |          |           |           |           |
          +----------+-----+-----+----------+-----------+
                           |
                +----------v------------+
                |   Agent Identity      |
                |   + Session           |
                |   + Namespace Perms   |
                +-----------------------+

OAuth 2.1 + DCR Flow

For Copilot Studio Dynamic Discovery

1. Discover /.well-known/oauth-protected-resource
2. Follow to /.well-known/oauth-authorization-server
3. Register client via /oauth/register (DCR - RFC 7591)
4. Authorization Code flow with PKCE S256 (mandatory)
5. Token exchange at /oauth/token
6. Refresh tokens (24-hour lifetime)

On-Behalf-Of (OBO) Flow

Delegated access to enterprise APIs

1. User authenticates in Teams (Entra ID SSO)
2. Copilot Studio passes user token in X-User-Token header
3. Gateway validates JWT signature, issuer, audience
4. PerRequestTokenResolver exchanges for OBO token
5. Plugin uses OBO token for delegated operations
6. Token cached in-memory with SHA256 keys, 2-min expiry buffer

Plugin Architecture

Implement one interface, add any integration

Plugins are registered at startup via dependency injection. The IToolRegistry aggregates all plugins and provides tool lookup by name or namespace.

IToolPlugin Interface

// Core contract — implement this to add an integration
public interface IToolPlugin
{
    string Namespace { get; }                    // e.g., "servicenow"
    string DisplayName { get; }                  // Human-readable name
    IReadOnlyList<ToolDescriptor> GetTools();     // Declare available tools
    Task<ToolResult> ExecuteAsync(               // Execute a tool
        string toolName,
        JsonElement arguments,
        CancellationToken cancellationToken
    );
}

Resilience Patterns

Pattern	Purpose
Circuit Breaker	Prevent cascading failures
Retry + Backoff	Handle transient errors
Timeout	Prevent hung requests (30s default)
Rate Limiting	Prevent abuse (per-agent)
Session Recovery	Transparent re-creation on 404
Response Caching	Reduce external API calls

Deployment Architecture

Azure-native deployment

Azure Deployment (Primary)

+--------------------------------------------------+
|                Azure Subscription                 |
|                                                   |
|  +---------------------------------------------+ |
|  |           Resource Group                     | |
|  |                                              | |
|  |  +--------------+  +-------------------+     | |
|  |  | App Service  |  | Application       |     | |
|  |  | Plan         |  | Insights          |     | |
|  |  | (B1/S1/P1)   |  | (Monitoring)      |     | |
|  |  +------+-------+  +-------------------+     | |
|  |         |                                    | |
|  |  +------v-------+  +-------------------+     | |
|  |  | App Service  |  | Key Vault         |     | |
|  |  | (MCP         |  | (Secrets)         |     | |
|  |  |  Gateway)    |  |                   |     | |
|  |  +--------------+  +-------------------+     | |
|  +---------------------------------------------+ |
+--------------------------------------------------+

Infrastructure as Code (Bicep)

main.bicep Root orchestration
app/api.bicep App Service configuration
app/appserviceplan.bicep Compute resources
app/monitoring.bicep Application Insights
app/keyvault.bicep Secrets management

CI/CD Pipeline

azure-pipelines.yml
  │
  ├── Build Stage
  │   ├── dotnet restore
  │   ├── dotnet build
  │   └── dotnet publish → artifact
  │
  ├── Deploy: Development
  │   └── App Service (Dev subscription)
  │
  ├── Deploy: UAT
  │   └── App Service (UAT subscription)
  │
  └── Deploy: Production
      └── App Service (Prod subscription)

Azure Developer CLI

azd up      # Deploy infrastructure + code
azd deploy  # Update code only
azd down    # Teardown resources

Health & Observability

Endpoint	Purpose
GET /health	Overall health (tools, sessions, plugins)
GET /health/ready	K8s readiness probe
GET /health/live	K8s liveness probe

OpenTelemetry Metrics

mcp_gateway_requests_total{agent, tool_namespace, status}
mcp_gateway_request_duration_seconds{agent, tool_namespace}
mcp_gateway_active_sessions{agent}
mcp_gateway_tool_executions_total{tool, status}

Compatible with Application Insights (native) and Prometheus (export).

Testing Architecture

Comprehensive test coverage

Test Pyramid

         +----------+
         |   E2E    |  MCP protocol compliance
         |  Tests   |  McpGateway.E2ETests
         +----------+
         |  Integr. |  Cross-component flows
         |  Tests   |  McpGateway.Integration.Tests
         +----------+
         |          |  Plugin logic, API endpoints
         |   Unit   |  McpGateway.Core.Tests
         |   Tests  |  McpGateway.Api.Tests
         |          |  McpGateway.Plugins.*.Tests
         +----------+

Test Clients

Client	Purpose
ChatClient	AI-powered conversation testing
TestClient	Raw MCP protocol testing
DocumentsTestClient	Document generation testing
PdfClient	PDF handling verification
ExpenseClient	Expense workflow end-to-end

Test Projects

Project	Scope	Scale
McpGateway.Core.Tests	Domain logic	Unit
McpGateway.Api.Tests	Endpoints, middleware	Unit
Plugins.ServiceNow.Tests	ServiceNow integration	580+ tests
Plugins.Documents.Tests	PDF/Excel generation	Integration
Plugins.Email.Tests	Email operations	Unit
Integration.Tests	Cross-component flows	Integration
E2ETests	Protocol compliance	E2E
Evaluation.Tests	Performance benchmarks	Evaluation

Integration Patterns

Three ways to connect

Primary

Copilot Studio + MCP Gateway

User (Teams)
  → Copilot Studio
    → Custom Connector
      → MCP Gateway
        → Plugin
          → Enterprise System

User identity flows end-to-end via Entra ID SSO and OBO token chain.

AWS

Bedrock + MCP Gateway

User (Web/Mobile)
  → Bedrock Agent
    → Action Group (Lambda)
      → MCP Gateway
        → Plugin
          → Enterprise System

Lambda function acts as adapter between Bedrock's action format and MCP protocol.

Direct

Direct MCP Client

Developer (Claude Code)
  → MCP Gateway
    → Plugin
      → Enterprise System

Any MCP-compatible client can connect directly for testing, development, or custom applications.

Extensibility Points

Designed to extend

Extension	How	Effort
New MCP Plugin	Implement `IToolPlugin`, register in DI	Low (days)
New Platform Generator	Add step file + generator logic	Medium (weeks)
New Compliance Checks	Add entries to `compliance-checks.yaml`	Low (hours)
New Governance Domain	Add entries to `governance-checks.yaml`	Low (hours)
New Design Pattern	Add to step files and DSL schema	Medium (days)
New Authentication Method	Add middleware + configuration	Medium (days)

Technology Decisions

Choices and rationale

Decision	Choice	Rationale
Gateway runtime	.NET 10.0	Enterprise ecosystem alignment, performance, Azure native
MCP protocol	2025-03-26 spec	Industry standard for AI-tool communication
DSL format	YAML	Human-readable, machine-parseable, git-friendly
IaC	Bicep	Azure-native, type-safe, no external dependencies
Primary platform	Copilot Studio	Microsoft Teams reach, enterprise licensing alignment
Session storage	In-memory (default)	Zero-dependency for single-instance; Redis path for scale
Token caching	In-memory, SHA256 keys	Security-first (no disk persistence, per-request isolation)
Transport	Streamable HTTP + SSE	Modern default with backward compatibility

For CTOs and Engineering Leaders