# ramani01/securemcp architecture

> Architecture diagram of the GitHub repository ramani01/securemcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ramani01/securemcp
- Repository: https://github.com/ramani01/securemcp

## Overview

SecureMCP is a defensive MCP server framework: an agent submits a tool request, runtime security controls decide whether it may proceed, and the server runs a safe calculator or workspace reader. The README documents a fail-closed sequence from identity and session checks through policy, resource controls, approval, secret handling, and audit. Separate capabilities include adversarial evaluation and a read-only local dashboard. The security pipeline and dashboard observations follow README documentation; sampled excerpts do not show every integration call.

Main entry points: [`src/securemcp/security/allowlist.py`](https://github.com/ramani01/securemcp/blob/main/src/securemcp/security/allowlist.py) (Tool Allowlist), [`src/securemcp/dashboard/service.py`](https://github.com/ramani01/securemcp/blob/main/src/securemcp/dashboard/service.py) (Dashboard Service), [`src/securemcp/server.py`](https://github.com/ramani01/securemcp/blob/main/src/securemcp/server.py) (MCP Server Tools), [`src/securemcp/security/audit.py`](https://github.com/ramani01/securemcp/blob/main/src/securemcp/security/audit.py) (Audit Logger)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["MCP Runtime"]
  node_mcp["MCP Server Tools<br/>[server.py]"]
  node_calculator["Safe Calculator<br/>[server.py]"]
  node_workspace["Workspace Reader<br/>[filesystem.py]"]
end

subgraph group_controls["Security Controls"]
  node_identity["Agent Identity<br/>[identity.py]"]
  node_session["Session Binding<br/>[session.py]"]
  node_verification["Server Verification"]
  node_dependencies["Dependency Security<br/>[dependencies.py]"]
  node_authorization["Authorization Engine<br/>[authorization.py]"]
  node_allowlist["Tool Allowlist<br/>[allowlist.py]"]
  node_validation["Input Validation<br/>[validation.py]"]
  node_filesystem["Filesystem Boundary<br/>[filesystem.py]"]
  node_rate["Rate Limiting<br/>[rate_limit.py]"]
  node_kill["Kill Switch<br/>[kill_switch.py]"]
  node_approval["Human Approval<br/>[approval.py]"]
  node_secrets["Secret Broker<br/>[secrets.py]"]
end

subgraph group_assurance["Assurance &amp; Audit"]
  node_audit["Audit Logger<br/>[audit.py]"]
  node_database[("Audit Database<br/>[database.py]")]
  node_evaluator["Adversarial Evaluator<br/>[adversarial.py]"]
end

subgraph group_dashboard["Local Dashboard"]
  node_dashboard_service["Dashboard Service<br/>[service.py]"]
  node_dashboard_app["Local HTTP Dashboard<br/>[app.py]"]
  node_dashboard_models["Dashboard Models<br/>[models.py]"]
end

node_agent(("AI Agent"))

node_agent -->|"submits tool request"| node_mcp
node_mcp -->|"checks tool access"| node_allowlist
node_allowlist -->|"resolves identity"| node_identity
node_allowlist -->|"validates session"| node_session
node_allowlist -->|"verifies server"| node_verification
node_allowlist -->|"checks dependencies"| node_dependencies
node_allowlist -->|"authorizes action"| node_authorization
node_allowlist -->|"validates input"| node_validation
node_allowlist -->|"checks workspace path"| node_filesystem
node_allowlist -->|"limits requests"| node_rate
node_allowlist -->|"checks execution state"| node_kill
node_allowlist -->|"requests approval"| node_approval
node_allowlist -->|"brokers credentials"| node_secrets
node_allowlist -->|"records decisions"| node_audit
node_mcp -->|"evaluates expression"| node_calculator
node_mcp -->|"reads workspace file"| node_workspace
node_workspace -->|"enforces boundary"| node_filesystem
node_audit -->|"persists events"| node_database
node_dashboard_app -->|"requests snapshots"| node_dashboard_service
node_dashboard_service -->|"builds status data"| node_dashboard_models
node_dashboard_service -->|"observes security state"| node_identity
node_dashboard_service -->|"observes security state"| node_session
node_dashboard_service -->|"observes security state"| node_verification
node_dashboard_service -->|"observes security state"| node_dependencies
node_dashboard_service -->|"observes security state"| node_authorization
node_dashboard_service -->|"reads audit status"| node_audit
node_dashboard_service -->|"reads evaluation results"| node_evaluator

click node_mcp "https://github.com/ramani01/securemcp/blob/main/src/securemcp/server.py"
click node_identity "https://github.com/ramani01/securemcp/blob/main/src/securemcp/security/identity.py"
click node_session "https://github.com/ramani01/securemcp/blob/main/src/securemcp/security/session.py"
click node_verification "https://github.com/ramani01/securemcp/blob/main/src/securemcp/security/server_verification.py"
click node_dependencies "https://github.com/ramani01/securemcp/blob/main/src/securemcp/security/dependencies.py"
click node_authorization "https://github.com/ramani01/securemcp/blob/main/src/securemcp/security/authorization.py"
click node_allowlist "https://github.com/ramani01/securemcp/blob/main/src/securemcp/security/allowlist.py"
click node_validation "https://github.com/ramani01/securemcp/blob/main/src/securemcp/security/validation.py"
click node_filesystem "https://github.com/ramani01/securemcp/blob/main/src/securemcp/security/filesystem.py"
click node_rate "https://github.com/ramani01/securemcp/blob/main/src/securemcp/security/rate_limit.py"
click node_kill "https://github.com/ramani01/securemcp/blob/main/src/securemcp/security/kill_switch.py"
click node_approval "https://github.com/ramani01/securemcp/blob/main/src/securemcp/security/approval.py"
click node_secrets "https://github.com/ramani01/securemcp/blob/main/src/securemcp/security/secrets.py"
click node_calculator "https://github.com/ramani01/securemcp/blob/main/src/securemcp/server.py"
click node_workspace "https://github.com/ramani01/securemcp/blob/main/src/securemcp/security/filesystem.py"
click node_audit "https://github.com/ramani01/securemcp/blob/main/src/securemcp/security/audit.py"
click node_database "https://github.com/ramani01/securemcp/blob/main/src/securemcp/storage/database.py"
click node_evaluator "https://github.com/ramani01/securemcp/blob/main/src/securemcp/security/adversarial.py"
click node_dashboard_service "https://github.com/ramani01/securemcp/blob/main/src/securemcp/dashboard/service.py"
click node_dashboard_app "https://github.com/ramani01/securemcp/blob/main/src/securemcp/dashboard/app.py"
click node_dashboard_models "https://github.com/ramani01/securemcp/blob/main/src/securemcp/dashboard/models.py"

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_mcp,node_calculator,node_workspace toneBlue
class node_identity,node_session,node_verification,node_dependencies,node_authorization,node_allowlist,node_validation,node_filesystem,node_rate,node_kill,node_approval,node_secrets toneAmber
class node_audit,node_database,node_evaluator toneMint
class node_dashboard_service,node_dashboard_app,node_dashboard_models toneRose
class node_agent toneIndigo
```

## Components

### MCP Runtime

- [MCP Server Tools](https://github.com/ramani01/securemcp/blob/main/src/securemcp/server.py): `src/securemcp/server.py`
- [Safe Calculator](https://github.com/ramani01/securemcp/blob/main/src/securemcp/server.py): `src/securemcp/server.py`
- [Workspace Reader](https://github.com/ramani01/securemcp/blob/main/src/securemcp/security/filesystem.py): `src/securemcp/security/filesystem.py`

### Security Controls

- [Agent Identity](https://github.com/ramani01/securemcp/blob/main/src/securemcp/security/identity.py): `src/securemcp/security/identity.py`
- [Session Binding](https://github.com/ramani01/securemcp/blob/main/src/securemcp/security/session.py): `src/securemcp/security/session.py`
- [Server Verification](https://github.com/ramani01/securemcp/blob/main/src/securemcp/security/server_verification.py): `src/securemcp/security/server_verification.py`
- [Dependency Security](https://github.com/ramani01/securemcp/blob/main/src/securemcp/security/dependencies.py): `src/securemcp/security/dependencies.py`
- [Authorization Engine](https://github.com/ramani01/securemcp/blob/main/src/securemcp/security/authorization.py): `src/securemcp/security/authorization.py`
- [Tool Allowlist](https://github.com/ramani01/securemcp/blob/main/src/securemcp/security/allowlist.py): `src/securemcp/security/allowlist.py`
- [Input Validation](https://github.com/ramani01/securemcp/blob/main/src/securemcp/security/validation.py): `src/securemcp/security/validation.py`
- [Filesystem Boundary](https://github.com/ramani01/securemcp/blob/main/src/securemcp/security/filesystem.py): `src/securemcp/security/filesystem.py`
- [Rate Limiting](https://github.com/ramani01/securemcp/blob/main/src/securemcp/security/rate_limit.py): `src/securemcp/security/rate_limit.py`
- [Kill Switch](https://github.com/ramani01/securemcp/blob/main/src/securemcp/security/kill_switch.py): `src/securemcp/security/kill_switch.py`
- [Human Approval](https://github.com/ramani01/securemcp/blob/main/src/securemcp/security/approval.py): `src/securemcp/security/approval.py`
- [Secret Broker](https://github.com/ramani01/securemcp/blob/main/src/securemcp/security/secrets.py): `src/securemcp/security/secrets.py`

### Assurance & Audit

- [Audit Logger](https://github.com/ramani01/securemcp/blob/main/src/securemcp/security/audit.py): `src/securemcp/security/audit.py`
- [Audit Database](https://github.com/ramani01/securemcp/blob/main/src/securemcp/storage/database.py): `src/securemcp/storage/database.py`
- [Adversarial Evaluator](https://github.com/ramani01/securemcp/blob/main/src/securemcp/security/adversarial.py): `src/securemcp/security/adversarial.py`

### Local Dashboard

- [Dashboard Service](https://github.com/ramani01/securemcp/blob/main/src/securemcp/dashboard/service.py): `src/securemcp/dashboard/service.py`
- [Local HTTP Dashboard](https://github.com/ramani01/securemcp/blob/main/src/securemcp/dashboard/app.py): `src/securemcp/dashboard/app.py`
- [Dashboard Models](https://github.com/ramani01/securemcp/blob/main/src/securemcp/dashboard/models.py): `src/securemcp/dashboard/models.py`

### Other components

- **AI Agent**

## Connections

- AI Agent → MCP Server Tools: submits tool request
- MCP Server Tools → Tool Allowlist: checks tool access
- Tool Allowlist → Agent Identity: resolves identity
- Tool Allowlist → Session Binding: validates session
- Tool Allowlist → Server Verification: verifies server
- Tool Allowlist → Dependency Security: checks dependencies
- Tool Allowlist → Authorization Engine: authorizes action
- Tool Allowlist → Input Validation: validates input
- Tool Allowlist → Filesystem Boundary: checks workspace path
- Tool Allowlist → Rate Limiting: limits requests
- Tool Allowlist → Kill Switch: checks execution state
- Tool Allowlist → Human Approval: requests approval
- Tool Allowlist → Secret Broker: brokers credentials
- Tool Allowlist → Audit Logger: records decisions
- MCP Server Tools → Safe Calculator: evaluates expression
- MCP Server Tools → Workspace Reader: reads workspace file
- Workspace Reader → Filesystem Boundary: enforces boundary
- Audit Logger → Audit Database: persists events
- Local HTTP Dashboard → Dashboard Service: requests snapshots
- Dashboard Service → Dashboard Models: builds status data
- Dashboard Service → Agent Identity: observes security state
- Dashboard Service → Session Binding: observes security state
- Dashboard Service → Server Verification: observes security state
- Dashboard Service → Dependency Security: observes security state
- Dashboard Service → Authorization Engine: observes security state
- Dashboard Service → Audit Logger: reads audit status
- Dashboard Service → Adversarial Evaluator: reads evaluation results