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

> Architecture diagram of the GitHub repository fareedkhan-dev/production-grade-mcp-agentic-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fareedkhan-dev/production-grade-mcp-agentic-system
- Repository: https://github.com/fareedkhan-dev/production-grade-mcp-agentic-system

## Overview

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.

Main entry points: [`src/atlas_mcp/tools/atomic`](https://github.com/fareedkhan-dev/production-grade-mcp-agentic-system/tree/master/src/atlas_mcp/tools/atomic) (Atomic Tools), [`src/atlas_mcp/auth/middleware.py`](https://github.com/fareedkhan-dev/production-grade-mcp-agentic-system/blob/master/src/atlas_mcp/auth/middleware.py) (Auth MW), [`src/atlas_mcp/agents/orchestrator.py`](https://github.com/fareedkhan-dev/production-grade-mcp-agentic-system/blob/master/src/atlas_mcp/agents/orchestrator.py) (Orchestrator), [`src/atlas_mcp/tools/registry.py`](https://github.com/fareedkhan-dev/production-grade-mcp-agentic-system/blob/master/src/atlas_mcp/tools/registry.py) (Tool Registry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_control["MCP Control Plane"]
  node_server["MCP Server<br/>runtime<br/>[server.py]"]
  node_auth_mw["Auth MW<br/>middleware<br/>[middleware.py]"]
  node_oauth["OAuth<br/>[oauth.py]"]
  node_policy["Policy<br/>authz<br/>[policy.py]"]
  node_tenant["Tenant Gate<br/>governance<br/>[tenant.py]"]
  node_approval["Approval Gate<br/>governance<br/>[approval.py]"]
  node_validate["Schemas<br/>validation<br/>[schemas.py]"]
  node_errors["Error Contract<br/>errors<br/>[framework.py]"]
  node_cache["Cache<br/>[manager.py]"]
  node_ratelimit["Rate Limit<br/>quota<br/>[limiter.py]"]
  node_retry["Retries<br/>resilience<br/>[retry.py]"]
  node_circuit["Circuit Breaker<br/>resilience<br/>[circuit_breaker.py]"]
  node_atba["Budgeting<br/>resilience<br/>[atba.py]"]
  node_obs["Observability<br/>telemetry<br/>[tracing.py]"]
end

subgraph group_grp_tools["Tool/Data Plane"]
  node_registry["Tool Registry<br/>catalog<br/>[registry.py]"]
  node_base["Tool Base<br/>abstraction<br/>[base.py]"]
  node_atomic["Atomic Tools<br/>integrations"]
  node_composed["Composed Tools<br/>composition"]
  node_workflow["Workflow Tools"]
  node_pg[("Postgres<br/>backend<br/>[postgres.py]")]
  node_es[("Search<br/>backend<br/>[elasticsearch.py]")]
  node_s3[("Object Store<br/>backend<br/>[s3_storage.py]")]
  node_vec[("Vector Search<br/>backend<br/>[vector_search.py]")]
end

subgraph group_grp_agents["Copilot Agents"]
  node_planner["Planner<br/>agent<br/>[planner.py]"]
  node_retriever["Retriever<br/>agent<br/>[retriever.py]"]
  node_synth["Synthesizer<br/>agent<br/>[synthesizer.py]"]
  node_critic["Critic<br/>agent<br/>[critic.py]"]
  node_orch["Orchestrator<br/>orchestration<br/>[orchestrator.py]"]
  node_mcp_client["MCP Client<br/>[mcp_client.py]"]
  node_memory["Agent Memory<br/>[memory.py]"]
end

subgraph group_grp_ops["Ops & Config"]
  node_config["Runtime Config<br/>[config.py]"]
  node_policy_yaml["Policy YAML<br/>config<br/>[policy.yaml]"]
  node_allowlist["HTTP Allowlist<br/>config"]
  node_sql_init["DB Init<br/>bootstrap<br/>[init.sql]"]
end

node_server -->|"incoming request"| node_auth_mw
node_auth_mw -->|"verify identity"| node_oauth
node_auth_mw -->|"authorize"| node_policy
node_auth_mw -->|"scope tenant"| node_tenant
node_auth_mw -->|"validate schema"| node_validate
node_tenant -->|"risk gate"| node_approval
node_auth_mw -->|"throttle"| node_ratelimit
node_auth_mw -->|"lookup"| node_cache
node_auth_mw -->|"trace"| node_obs
node_auth_mw -->|"dispatch"| node_registry
node_registry -->|"implements"| node_base
node_registry -->|"register"| node_atomic
node_registry -->|"register"| node_composed
node_registry -->|"register"| node_workflow
node_composed -->|"chain"| node_atomic
node_workflow -->|"orchestrate"| node_atomic
node_atomic -->|"query"| node_pg
node_atomic -->|"search"| node_es
node_atomic -->|"store"| node_s3
node_atomic -->|"embed"| node_vec
node_atomic -->|"cache results"| node_cache
node_atomic -->|"retry"| node_retry
node_atomic -->|"protect"| node_circuit
node_atomic -->|"budget"| node_atba
node_atomic -->|"observe"| node_obs
node_orch -->|"plan"| node_planner
node_orch -->|"retrieve"| node_retriever
node_orch -->|"synthesize"| node_synth
node_orch -->|"review"| node_critic
node_orch -->|"call server"| node_mcp_client
node_mcp_client -->|"mcp request"| node_server
node_orch -->|"remember"| node_memory
node_memory -->|"vector store"| node_vec
node_memory -->|"short term"| node_cache
node_policy -->|"loads"| node_policy_yaml
node_auth_mw -->|"egress policy"| node_allowlist
node_config -->|"reads"| node_policy_yaml
node_config -->|"reads"| node_allowlist
node_sql_init -->|"bootstrap"| node_pg

click node_server "https://github.com/fareedkhan-dev/production-grade-mcp-agentic-system/blob/master/src/atlas_mcp/server.py"
click node_auth_mw "https://github.com/fareedkhan-dev/production-grade-mcp-agentic-system/blob/master/src/atlas_mcp/auth/middleware.py"
click node_oauth "https://github.com/fareedkhan-dev/production-grade-mcp-agentic-system/blob/master/src/atlas_mcp/auth/oauth.py"
click node_policy "https://github.com/fareedkhan-dev/production-grade-mcp-agentic-system/blob/master/src/atlas_mcp/auth/policy.py"
click node_tenant "https://github.com/fareedkhan-dev/production-grade-mcp-agentic-system/blob/master/src/atlas_mcp/governance/tenant.py"
click node_approval "https://github.com/fareedkhan-dev/production-grade-mcp-agentic-system/blob/master/src/atlas_mcp/governance/approval.py"
click node_validate "https://github.com/fareedkhan-dev/production-grade-mcp-agentic-system/blob/master/src/atlas_mcp/validation/schemas.py"
click node_errors "https://github.com/fareedkhan-dev/production-grade-mcp-agentic-system/blob/master/src/atlas_mcp/errors/framework.py"
click node_cache "https://github.com/fareedkhan-dev/production-grade-mcp-agentic-system/blob/master/src/atlas_mcp/cache/manager.py"
click node_ratelimit "https://github.com/fareedkhan-dev/production-grade-mcp-agentic-system/blob/master/src/atlas_mcp/ratelimit/limiter.py"
click node_retry "https://github.com/fareedkhan-dev/production-grade-mcp-agentic-system/blob/master/src/atlas_mcp/reliability/retry.py"
click node_circuit "https://github.com/fareedkhan-dev/production-grade-mcp-agentic-system/blob/master/src/atlas_mcp/reliability/circuit_breaker.py"
click node_atba "https://github.com/fareedkhan-dev/production-grade-mcp-agentic-system/blob/master/src/atlas_mcp/reliability/atba.py"
click node_obs "https://github.com/fareedkhan-dev/production-grade-mcp-agentic-system/blob/master/src/atlas_mcp/observability/tracing.py"
click node_registry "https://github.com/fareedkhan-dev/production-grade-mcp-agentic-system/blob/master/src/atlas_mcp/tools/registry.py"
click node_base "https://github.com/fareedkhan-dev/production-grade-mcp-agentic-system/blob/master/src/atlas_mcp/tools/base.py"
click node_atomic "https://github.com/fareedkhan-dev/production-grade-mcp-agentic-system/tree/master/src/atlas_mcp/tools/atomic"
click node_composed "https://github.com/fareedkhan-dev/production-grade-mcp-agentic-system/tree/master/src/atlas_mcp/tools/composed"
click node_workflow "https://github.com/fareedkhan-dev/production-grade-mcp-agentic-system/tree/master/src/atlas_mcp/tools/workflow"
click node_pg "https://github.com/fareedkhan-dev/production-grade-mcp-agentic-system/blob/master/src/atlas_mcp/tools/atomic/postgres.py"
click node_es "https://github.com/fareedkhan-dev/production-grade-mcp-agentic-system/blob/master/src/atlas_mcp/tools/atomic/elasticsearch.py"
click node_s3 "https://github.com/fareedkhan-dev/production-grade-mcp-agentic-system/blob/master/src/atlas_mcp/tools/atomic/s3_storage.py"
click node_vec "https://github.com/fareedkhan-dev/production-grade-mcp-agentic-system/blob/master/src/atlas_mcp/tools/atomic/vector_search.py"
click node_planner "https://github.com/fareedkhan-dev/production-grade-mcp-agentic-system/blob/master/src/atlas_mcp/agents/planner.py"
click node_retriever "https://github.com/fareedkhan-dev/production-grade-mcp-agentic-system/blob/master/src/atlas_mcp/agents/retriever.py"
click node_synth "https://github.com/fareedkhan-dev/production-grade-mcp-agentic-system/blob/master/src/atlas_mcp/agents/synthesizer.py"
click node_critic "https://github.com/fareedkhan-dev/production-grade-mcp-agentic-system/blob/master/src/atlas_mcp/agents/critic.py"
click node_orch "https://github.com/fareedkhan-dev/production-grade-mcp-agentic-system/blob/master/src/atlas_mcp/agents/orchestrator.py"
click node_mcp_client "https://github.com/fareedkhan-dev/production-grade-mcp-agentic-system/blob/master/src/atlas_mcp/agents/mcp_client.py"
click node_memory "https://github.com/fareedkhan-dev/production-grade-mcp-agentic-system/blob/master/src/atlas_mcp/agents/memory.py"
click node_config "https://github.com/fareedkhan-dev/production-grade-mcp-agentic-system/blob/master/src/atlas_mcp/config.py"
click node_policy_yaml "https://github.com/fareedkhan-dev/production-grade-mcp-agentic-system/blob/master/config/policy.yaml"
click node_allowlist "https://github.com/fareedkhan-dev/production-grade-mcp-agentic-system/blob/master/config/http_allowlist.yaml"
click node_sql_init "https://github.com/fareedkhan-dev/production-grade-mcp-agentic-system/blob/master/deploy/sql/init.sql"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_server,node_auth_mw,node_oauth,node_policy,node_tenant,node_approval,node_validate,node_errors,node_cache,node_ratelimit,node_retry,node_circuit,node_atba,node_obs toneBlue
class node_registry,node_base,node_atomic,node_composed,node_workflow,node_pg,node_es,node_s3,node_vec toneAmber
class node_planner,node_retriever,node_synth,node_critic,node_orch,node_mcp_client,node_memory toneMint
class node_config,node_policy_yaml,node_allowlist,node_sql_init toneRose
```

## Components

### MCP Control Plane

Runtime boundary for MCP requests, cross-cutting governance, and request validation.

- [MCP Server](https://github.com/fareedkhan-dev/production-grade-mcp-agentic-system/blob/master/src/atlas_mcp/server.py): runtime · Entry point for MCP clients over stdio or Streamable HTTP. · `src/atlas_mcp/server.py`
- [Auth MW](https://github.com/fareedkhan-dev/production-grade-mcp-agentic-system/blob/master/src/atlas_mcp/auth/middleware.py): middleware · Authentication and request-time identity enforcement. · `src/atlas_mcp/auth/middleware.py`
- [OAuth](https://github.com/fareedkhan-dev/production-grade-mcp-agentic-system/blob/master/src/atlas_mcp/auth/oauth.py): auth · OAuth 2.1, JWT, and JWKS validation logic. · `src/atlas_mcp/auth/oauth.py`
- [Policy](https://github.com/fareedkhan-dev/production-grade-mcp-agentic-system/blob/master/src/atlas_mcp/auth/policy.py): authz · Authorization rules driven by YAML policy config. · `src/atlas_mcp/auth/policy.py`
- [Tenant Gate](https://github.com/fareedkhan-dev/production-grade-mcp-agentic-system/blob/master/src/atlas_mcp/governance/tenant.py): governance · Tenant scoping and isolation boundary. · `src/atlas_mcp/governance/tenant.py`
- [Approval Gate](https://github.com/fareedkhan-dev/production-grade-mcp-agentic-system/blob/master/src/atlas_mcp/governance/approval.py): governance · Human-review control for risky or blocked actions. · `src/atlas_mcp/governance/approval.py`
- [Schemas](https://github.com/fareedkhan-dev/production-grade-mcp-agentic-system/blob/master/src/atlas_mcp/validation/schemas.py): validation · Request and tool-call schema definitions. · `src/atlas_mcp/validation/schemas.py`
- [Error Contract](https://github.com/fareedkhan-dev/production-grade-mcp-agentic-system/blob/master/src/atlas_mcp/errors/framework.py): errors · Standardized structured errors and retry metadata. · `src/atlas_mcp/errors/framework.py`
- [Cache](https://github.com/fareedkhan-dev/production-grade-mcp-agentic-system/blob/master/src/atlas_mcp/cache/manager.py): cache · L1 in-process cache plus Redis-backed L2 with stampede protection. · `src/atlas_mcp/cache/manager.py`
- [Rate Limit](https://github.com/fareedkhan-dev/production-grade-mcp-agentic-system/blob/master/src/atlas_mcp/ratelimit/limiter.py): quota · Redis token-bucket throttling per tenant or tool. · `src/atlas_mcp/ratelimit/limiter.py`
- [Retries](https://github.com/fareedkhan-dev/production-grade-mcp-agentic-system/blob/master/src/atlas_mcp/reliability/retry.py): resilience · Retry logic with jitter around backend calls. · `src/atlas_mcp/reliability/retry.py`
- [Circuit Breaker](https://github.com/fareedkhan-dev/production-grade-mcp-agentic-system/blob/master/src/atlas_mcp/reliability/circuit_breaker.py): resilience · Per-tool circuit breaking state machine. · `src/atlas_mcp/reliability/circuit_breaker.py`
- [Budgeting](https://github.com/fareedkhan-dev/production-grade-mcp-agentic-system/blob/master/src/atlas_mcp/reliability/atba.py): resilience · Adaptive timeout budget allocation. · `src/atlas_mcp/reliability/atba.py`
- [Observability](https://github.com/fareedkhan-dev/production-grade-mcp-agentic-system/blob/master/src/atlas_mcp/observability/tracing.py): telemetry · Tracing, metrics, and audit logging. · `src/atlas_mcp/observability/tracing.py`

### Tool/Data Plane

Registered tools and the heterogeneous backend systems they mediate.

- [Tool Registry](https://github.com/fareedkhan-dev/production-grade-mcp-agentic-system/blob/master/src/atlas_mcp/tools/registry.py): catalog · Registers and dispatches tool implementations. · `src/atlas_mcp/tools/registry.py`
- [Tool Base](https://github.com/fareedkhan-dev/production-grade-mcp-agentic-system/blob/master/src/atlas_mcp/tools/base.py): abstraction · Shared tool interface and execution model. · `src/atlas_mcp/tools/base.py`
- [Atomic Tools](https://github.com/fareedkhan-dev/production-grade-mcp-agentic-system/tree/master/src/atlas_mcp/tools/atomic): integrations · Single-backend tools for core storage and retrieval systems. · `src/atlas_mcp/tools/atomic`
- [Composed Tools](https://github.com/fareedkhan-dev/production-grade-mcp-agentic-system/tree/master/src/atlas_mcp/tools/composed): composition · Deterministic multi-step tool chains. · `src/atlas_mcp/tools/composed`
- [Workflow Tools](https://github.com/fareedkhan-dev/production-grade-mcp-agentic-system/tree/master/src/atlas_mcp/tools/workflow): workflow · Business-process tools with multi-step orchestration. · `src/atlas_mcp/tools/workflow`
- [Postgres](https://github.com/fareedkhan-dev/production-grade-mcp-agentic-system/blob/master/src/atlas_mcp/tools/atomic/postgres.py): backend · Transactional data store and schema bootstrap. · `src/atlas_mcp/tools/atomic/postgres.py`
- [Search](https://github.com/fareedkhan-dev/production-grade-mcp-agentic-system/blob/master/src/atlas_mcp/tools/atomic/elasticsearch.py): backend · Elasticsearch-backed retrieval and indexing. · `src/atlas_mcp/tools/atomic/elasticsearch.py`
- [Object Store](https://github.com/fareedkhan-dev/production-grade-mcp-agentic-system/blob/master/src/atlas_mcp/tools/atomic/s3_storage.py): backend · S3-compatible blob storage. · `src/atlas_mcp/tools/atomic/s3_storage.py`
- [Vector Search](https://github.com/fareedkhan-dev/production-grade-mcp-agentic-system/blob/master/src/atlas_mcp/tools/atomic/vector_search.py): backend · Embedding and vector retrieval capability. · `src/atlas_mcp/tools/atomic/vector_search.py`

### Copilot Agents

Internal multi-agent consumer that calls the MCP server through an MCP client.

- [Planner](https://github.com/fareedkhan-dev/production-grade-mcp-agentic-system/blob/master/src/atlas_mcp/agents/planner.py): agent · Creates retrieval plans for the copilot. · `src/atlas_mcp/agents/planner.py`
- [Retriever](https://github.com/fareedkhan-dev/production-grade-mcp-agentic-system/blob/master/src/atlas_mcp/agents/retriever.py): agent · Performs bounded tool calls through the MCP client. · `src/atlas_mcp/agents/retriever.py`
- [Synthesizer](https://github.com/fareedkhan-dev/production-grade-mcp-agentic-system/blob/master/src/atlas_mcp/agents/synthesizer.py): agent · Drafts answers with citations and evidence. · `src/atlas_mcp/agents/synthesizer.py`
- [Critic](https://github.com/fareedkhan-dev/production-grade-mcp-agentic-system/blob/master/src/atlas_mcp/agents/critic.py): agent · Runs a revise-or-approve review pass. · `src/atlas_mcp/agents/critic.py`
- [Orchestrator](https://github.com/fareedkhan-dev/production-grade-mcp-agentic-system/blob/master/src/atlas_mcp/agents/orchestrator.py): orchestration · Ties the four-agent copilot together. · `src/atlas_mcp/agents/orchestrator.py`
- [MCP Client](https://github.com/fareedkhan-dev/production-grade-mcp-agentic-system/blob/master/src/atlas_mcp/agents/mcp_client.py): client · Internal client used by agents to call the MCP server. · `src/atlas_mcp/agents/mcp_client.py`
- [Agent Memory](https://github.com/fareedkhan-dev/production-grade-mcp-agentic-system/blob/master/src/atlas_mcp/agents/memory.py): memory · Short-term and long-term memory backed by Redis and vectors. · `src/atlas_mcp/agents/memory.py`

### Ops & Config

Deployment artifacts and runtime policy/configuration inputs.

- [Runtime Config](https://github.com/fareedkhan-dev/production-grade-mcp-agentic-system/blob/master/src/atlas_mcp/config.py): config · Shared application configuration loader. · `src/atlas_mcp/config.py`
- [Policy YAML](https://github.com/fareedkhan-dev/production-grade-mcp-agentic-system/blob/master/config/policy.yaml): config · Authorization policy definition. · `config/policy.yaml`
- [HTTP Allowlist](https://github.com/fareedkhan-dev/production-grade-mcp-agentic-system/blob/master/config/http_allowlist.yaml): config · Outbound HTTP destination restrictions. · `config/http_allowlist.yaml`
- [DB Init](https://github.com/fareedkhan-dev/production-grade-mcp-agentic-system/blob/master/deploy/sql/init.sql): bootstrap · Database schema and row-level security bootstrap. · `deploy/sql/init.sql`

## Connections

- MCP Server → Auth MW: incoming request · All MCP traffic first passes through authentication middleware.
- Auth MW → OAuth: verify identity · Validate OAuth/JWT/JWKS credentials.
- Auth MW → Policy: authorize · Apply request and tool access policy.
- Auth MW → Tenant Gate: scope tenant · Bind request to tenant context.
- Auth MW → Schemas: validate schema · Reject malformed or adversarial payloads early.
- Tenant Gate → Approval Gate: risk gate · Tenant and risk context can trigger human approval.
- Auth MW → Rate Limit: throttle · Enforce tenant/tool quotas before execution.
- Auth MW → Cache: lookup · Consult cache for repeatable or expensive results.
- Auth MW → Observability: trace · Emit traces, metrics, and audit events around request handling.
- Auth MW → Tool Registry: dispatch · Route approved requests to registered tools.
- Tool Registry → Tool Base: implements · Tools conform to a shared execution abstraction.
- Tool Registry → Atomic Tools: register · Atomic backend integrations are exposed as tools.
- Tool Registry → Composed Tools: register · Composed search tools are exposed as tools.
- Tool Registry → Workflow Tools: register · Workflow tools are exposed as tools.
- Composed Tools → Atomic Tools: chain · Composed tools build on atomic integrations.
- Workflow Tools → Atomic Tools: orchestrate · Workflow tools use atomic capabilities as steps.
- Atomic Tools → Postgres: query · PostgreSQL-backed tools.
- Atomic Tools → Search: search · Elasticsearch-backed tools.
- Atomic Tools → Object Store: store · S3-compatible object operations.
- Atomic Tools → Vector Search: embed · Embedding and vector search operations.
- Atomic Tools → Cache: cache results · Backend calls may be cached.
- Atomic Tools → Retries: retry · Backend failures are retried with jitter.
- Atomic Tools → Circuit Breaker: protect · Circuit breaking wraps backend integrations.
- Atomic Tools → Budgeting: budget · Adaptive timeout budgets constrain calls.
- Atomic Tools → Observability: observe · Instrument tool execution.
- Orchestrator → Planner: plan · Orchestrator starts with retrieval planning.
- Orchestrator → Retriever: retrieve · Planner-guided bounded tool use.
- Orchestrator → Synthesizer: synthesize · Assemble cited answers.
- Orchestrator → Critic: review · One revise-or-approve pass.
- Orchestrator → MCP Client: call server · Agents consume the MCP server through an internal client.
- MCP Client → MCP Server: mcp request · Internal agent calls target the same MCP runtime boundary.
- Orchestrator → Agent Memory: remember · Persist and retrieve short- and long-term context.
- Agent Memory → Vector Search: vector store · Long-term memory uses vector search.
- Agent Memory → Cache: short term · Near-term state can use cache-backed storage.
- Policy → Policy YAML: loads · Policy rules are configured from YAML.
- Auth MW → HTTP Allowlist: egress policy · Outbound HTTP is constrained by an allowlist.
- Runtime Config → Policy YAML: reads · Application config loads policy settings.
- Runtime Config → HTTP Allowlist: reads · Application config loads HTTP restrictions.
- DB Init → Postgres: bootstrap · Database initialization and RLS setup target PostgreSQL.