fareedkhan-dev/production-grade-mcp-agentic-system

1. System shape

This repo is a Python 3.11+ production-oriented MCP server plus a separate four-agent “support copilot.” The server is the runtime boundary exposed to MCP clients; the agent system is an internal consumer that calls the server through an MCP client. The code is organized so transport/auth/governance are cross-cutting around tool execution, while observability and reliability wrap almost every path.

2. Primary request path

External MCP clients connect to src/atlas_mcp/server.py over stdio or Streamable HTTP. Requests pass through authentication middleware, tenant enforcement, authorization policy checks, rate limiting, caching, and reliability controls before reaching tool handlers. The server then dispatches to a registered tool and returns structured results or structured errors.

3. Identity, access, and tenant isolation

Authentication is handled in src/atlas_mcp/auth/oauth.py and auth/middleware.py, using OAuth 2.1 / JWT / JWKS validation. Authorization lives in auth/policy.py and is driven by YAML config in config/policy.yaml; outbound HTTP restrictions are also governed by config/http_allowlist.yaml. Tenant scoping is a first-class boundary in src/atlas_mcp/governance/tenant.py, so the same server instance can serve multiple tenants with different permissions and data access constraints.

4. Tool surface and execution model

Tools are registered in src/atlas_mcp/tools/registry.py and built on tools/base.py. The tool layer is split into three levels: atomic tools for single backends, composed tools for deterministic chains, and workflow tools for multi-step business procedures. The repository includes atomic integrations for Postgres, Elasticsearch, S3/MinIO, embeddings, HTTP client calls, and vector search; composed tools include semantic and hybrid search; workflow tools include customer-context assembly.

5. Data plane

The data layer is heterogeneous by design: PostgreSQL, Elasticsearch, S3-compatible storage, Redis, and a vector database are all represented in the tool modules. deploy/sql/init.sql suggests the database side includes schema setup plus row-level security policies for tenant isolation. The server does not hide these systems behind a single ORM abstraction; instead it exposes them as controlled tool capabilities.

6. Reliability controls

src/atlas_mcp/reliability/ contains per-tool circuit breaking, retry with jitter, and adaptive timeout budget allocation. This means backend failures are handled at the integration boundary rather than leaking directly into the MCP layer. tests/test_circuit_breaker.py indicates the breaker state machine is load-bearing and explicitly tested.

7. Caching and rate limiting

src/atlas_mcp/cache/manager.py implements a two-tier cache: an in-process L1 and Redis-backed L2, with stampede protection. src/atlas_mcp/ratelimit/limiter.py provides Redis token-bucket rate limiting, likely applied per tenant and per tool. These two subsystems sit in front of backend calls to protect expensive resources and enforce quotas.

8. Validation and error contract

src/atlas_mcp/validation/schemas.py defines the request/tool-call schemas, which is important because the system assumes adversarial or malformed agent input. Errors are standardized in src/atlas_mcp/errors/framework.py, with machine-readable metadata such as retryability and hints. The test suite focuses on these semantics, which suggests error shape is part of the external contract.

9. Observability

src/atlas_mcp/observability/ provides three distinct signals: OpenTelemetry tracing, Prometheus metrics, and structured audit logs. The runtime is wired for end-to-end traceability, and the README shows a single run ID tying MCP tool calls back to Jaeger. This makes observability a first-class architectural layer rather than an add-on.

10. Agentic copilot subsystem

src/atlas_mcp/agents/ is a separate orchestration layer that consumes the MCP server. planner.py creates a retrieval plan, retriever.py performs bounded tool calls through mcp_client.py, synthesizer.py drafts the answer with citations, and critic.py performs one revise/approve pass. orchestrator.py ties the four agents together, and memory.py adds short-term and long-term memory backed by Redis and vector search.

11. Governance and human control

src/atlas_mcp/governance/approval.py introduces an approval gate, which implies some tool or workflow actions can be paused for human review. This is a distinct control plane from authentication and authorization: auth decides who may act, governance decides whether an action should proceed given tenant or risk context. That separation matters when drawing the architecture because approvals are not just another auth check.

12. Deployment and local stack

docker-compose.yml brings up the app plus supporting infrastructure for local development, including observability endpoints and likely database/cache/search/vector dependencies. deploy/otel/config.yaml, deploy/prometheus/prometheus.yml, and deploy/sql/init.sql show that the repo includes sidecar/configuration artifacts for telemetry and database bootstrap. Dockerfile and docs/DEPLOYMENT.md indicate the project is meant to run both locally and in production with swapped managed services.

13. What to show in an architecture diagram

The clearest diagram would have three major planes: the MCP server control plane, the tool/data plane, and the agentic copilot consuming that server. Cross-cutting overlays should show auth/policy, tenant isolation, rate limiting, caching, reliability, and observability around every server request. External dependencies to place outside the boundary are OAuth/JWKS provider, Redis, PostgreSQL, Elasticsearch, S3/MinIO, vector DB, OpenTelemetry/Prometheus stack, and the Anthropic API used by the agents.