Agent Atlas — MCP Mesh

Agent Atlas is an enterprise MCP (Model Context Protocol) gateway built with ASP.NET Core 10 and .NET Aspire. It turns a messy internal API estate into a governed, searchable catalog of tools that both humans and AI agents can discover and invoke safely.

What it does

Capability	Description
Catalog	Reads OpenAPI specs from a GitOps data-plane repository. Teams annotate operations with `x-mcp` vendor extensions to mark them as agent tools.
MCP Server	Exposes three MCP tools — `SearchTools`, `DescribeTool`, `ExecutePlan` — via Streamable HTTP transport at `/mcp`.
Execution Engine	Interprets a JSON plan DSL (`call`, `foreach`, `if`, `return` steps) and proxies requests to downstream APIs, forwarding the caller’s JWT.
React UI	A read-only capability map for developers and operators.

Quick start

# 1. Trust the HTTPS development certificate (required once per environment)
dotnet dev-certs https --clean
dotnet dev-certs https
dotnet dev-certs https --trust

# 2. Run with Aspire (starts all services including Keycloak)
aspire run --project src/Atlas.AppHost

Note: Aspire uses a local HTTPS certificate for service-to-service communication via its internal DCP process manager. Without a trusted certificate the AppHost times out after 20 seconds. On Linux, dotnet dev-certs https --trust may exit with code 4 when it cannot register with browser trust stores — this is non-fatal; the certificate is still trusted for .NET clients.

Note: On first run, Docker pulls the Keycloak and MCP Inspector images. atlas-host will show as Running in the Aspire dashboard only after Keycloak has finished starting (allow 2–5 minutes).

Documentation

Browse the full documentation using the navigation on the left (or above on mobile).

Page	Description
UI Walkthrough	Screenshots and tour of the Tools, APIs, Use MCP, and About pages
Security Model	Two-layer auth model — platform permissions + downstream API auth
GitOps Data Plane	Catalog repo structure and `x-mcp` extension reference
Deploy with Docker	Docker deployment guide including published image details
Deploy with Helm	Kubernetes / Helm deployment guide including AKS, GitLab CI, Calico, and Key Vault
CI/CD Pipelines	Full pipeline setup guide — secrets, branch model, GitHub Pages, and first release

Architecture

┌─────────────────────────────────────────────────────────────┐
│  AI Agent (Claude, Copilot, custom orchestrator, …)         │
│  ─ connects via MCP Streamable HTTP transport               │
└──────────────────────┬──────────────────────────────────────┘
                       │  Bearer JWT (Keycloak / any OIDC IdP)
                       ▼
┌─────────────────────────────────────────────────────────────┐
│  Atlas.Host  (ASP.NET Core 10, .NET Aspire)                 │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │  MCP Server  (/mcp — ModelContextProtocol SDK)      │   │
│  │  • SearchTools   • DescribeTool   • ExecutePlan     │   │
│  └──────────────────────┬──────────────────────────────┘   │
│                          │                                  │
│  ┌─────────────────────┐ │ ┌──────────────────────────┐    │
│  │  Catalog REST API   │ │ │  Execution Engine         │    │
│  │  /v1/apis           │ │ │  (plan DSL interpreter)   │    │
│  │  /v1/tools          │ │ └──────────────────────────┘    │
│  └─────────────────────┘ │                                  │
│                          │                                  │
│  ┌─────────────────────────────────────────────────────┐   │
│  │  Catalog Loader  (reads GitOps data-plane repo)     │   │
│  │  OpenAPI + x-mcp vendor extension → ToolDefinition  │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
│  React UI (browse APIs & tools, dark/light mode)            │
└──────────────────────┬──────────────────────────────────────┘
                       │  Bearer JWT forwarded as-is
                       ▼
        Your existing REST APIs (unchanged)

MCP tools exposed to AI agents

Tool	Purpose
`SearchTools`	Search the catalog by query, API ID, safety tier, or access filter
`DescribeTool`	Get full metadata for a specific tool (schema, permissions, examples)
`ExecutePlan`	Run (or dry-run) a JSON plan against one or more tools

Example plan

{
  "steps": [
    { "type": "call",    "toolId": "my-api.customers.list", "args": {}, "saveAs": "customers" },
    { "type": "foreach", "items": "customers", "as": "item", "do": [
        { "type": "call", "toolId": "my-api.customers.get",
          "args": { "id": "{{item.id}}" }, "saveAs": "detail" }
    ]},
    { "type": "return",  "from": "customers" }
  ]
}

Projects in this solution

Project	Description
Atlas.AppHost	.NET Aspire orchestration host — wires all services together for local dev
Atlas.Host	Main service: MCP server, catalog REST API, React UI, execution engine
SampleApi.ToolEnabled	Demo customer API whose operations are registered as MCP tools
SampleApi.NotToolEnabled	Demo products API intentionally not registered as tools

Configuration reference

Variable	Default	Description
`Atlas__CatalogPath`	`/catalog`	Path to the GitOps data-plane repo
`Atlas__CatalogStrict`	`true`	Fail hard on catalog parse errors
`Atlas__Oidc__Issuer`	(required)	OIDC issuer URL
`Atlas__Oidc__Audience`	`api://agent-atlas`	Expected JWT audience
`Atlas__PlatformPermissions__Claim`	`scp`	JWT claim for permissions
`Atlas__ExecLimits__MaxSteps`	`50`	Max steps per plan
`Atlas__ExecLimits__MaxCalls`	`50`	Max downstream HTTP calls per plan
`Atlas__ExecLimits__MaxSeconds`	`30`	Wall-clock timeout for plan execution
`Atlas__ExecLimits__MaxBytes`	`10485760`	Max cumulative response bytes
`Atlas__Cors__AllowedOrigins`	(localhost in dev)	Allowed CORS origins for the UI