# MCP Agent Security Architecture
## Why The Current Design Is Actually Smart 🧠
### Traditional Approach (What QA Expected)
```
┌─────────────────────────────────────┐
│ Config Files (ENCRYPTED) │
│ ┌─────────────────────────────┐ │
│ │ auth.json: │ │
│ │ { │ │
│ │ "token": "ghp_abc123...", │ ❌ │ <- Actual secrets in files!
│ │ "apiKey": "sk_live_..." │ │
│ │ } │ │
│ └─────────────────────────────┘ │
│ │
│ Must encrypt files (complex!) │
│ Must manage encryption keys │
│ Risk of key exposure │
└─────────────────────────────────────┘
```
### MCP Agent Approach (Current Design)
```
┌─────────────────────────────────────┐ ┌──────────────────────┐
│ Config Files (PLAIN TEXT) │ │ Environment Vars │
│ ┌─────────────────────────────┐ │ │ │
│ │ auth/github.toml: │ │ │ GITHUB_TOKEN=ghp_... │
│ │ [profile] │ │ │ STRIPE_KEY=sk_... │
│ │ name = "github" │ │ │ ADMIN_TOKEN=adm_... │
│ │ token_env = "GITHUB_TOKEN" ─┼───┼────>│ │
│ └─────────────────────────────┘ │ └──────────────────────┘
│ │ 🔒
│ ✅ Can be version controlled │ Never in files!
│ ✅ Can be shared safely │ Never in logs!
│ ✅ Simple to understand │ Never exposed to agents!
└─────────────────────────────────────┘
```
## Security Layers Visualization
```
┌─────────────────────────────────────────────────────────────┐
│ AI Agent Request │
└────────────────────────┬────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Layer 1: MCP Protocol (JSON-RPC) │
│ - Never sees actual secrets │
│ - Only gets operation results │
└────────────────────────┬────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Layer 2: Policy Engine │
│ - Checks if operation is allowed │
│ - Rules are in plain text (by design!) │
│ - "What can be done" not "how to authenticate" │
└────────────────────────┬────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Layer 3: Auth Resolution │
│ - Reads ENV var name from config │
│ - Gets actual value from environment │
│ - Injects into API request │
│ - Agent NEVER sees this! │
└────────────────────────┬────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Layer 4: API Execution │
│ - Makes actual API call with real credentials │
│ - Returns results to agent │
└────────────────────────┬────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Layer 5: Response Filtering │
│ - Redacts any secrets from response │
│ - [REDACTED] replaces sensitive data │
└─────────────────────────────────────────────────────────────┘
```
## File Permissions: Defense in Depth
```
Current State (QA Found): Recommended Fix:
.mrapids/ .mrapids/
├── 📁 (755) auth/ ├── 🔒 (700) auth/
│ └── 📄 (644) github.toml │ └── 🔐 (600) github.toml
├── 📄 (644) policy.yaml ├── 🔐 (600) policy.yaml
└── 📄 (644) config.toml └── 🔐 (600) config.toml
Risk if NOT fixed: Risk AFTER fix:
- Others see ENV var names ❓ - No one else can read ✅
- Others see policy rules 😟 - Only owner access ✅
- BUT no actual secrets! ✅ - Extra security layer ✅
```
## Why This Architecture?
### 1. **Separation of Concerns**
```yaml
What (Policy): How (Auth): Secret (Env):
- "Allow read ops" - "Use GitHub auth" - Actual token
- "Block deletes" - "Bearer token" - Never in files
- "Audit everything" - "From GITHUB_TOKEN" - OS protected
```
### 2. **12-Factor App Compliance**
```
✅ Store config in environment
✅ Strict separation of config from credentials
✅ Can open source the code safely
✅ Different secrets per deployment
```
### 3. **Container/Cloud Native**
```dockerfile
# Dockerfile can include config
COPY .mrapids /app/.mrapids ✅ Safe!
# Secrets injected at runtime
docker run -e GITHUB_TOKEN=$SECRET myapp ✅
```
## Security Comparison
| Version Control | ❌ Dangerous | ✅ Safe |
| Sharing Configs | ❌ Risk of exposure | ✅ Can share freely |
| Audit Trail | ❌ Hard to track access | ✅ Every use logged |
| Agent Access | ❌ Might see secrets | ✅ Never sees secrets |
| Rotation | ❌ Requires file updates | ✅ Just change env var |
| Encryption | ❌ Complex key management | ✅ OS handles it |
## The Real Security Issues
### What QA Found (Lower Risk):
1. **Config files world-readable** → Exposes structure, not secrets
2. **No input validation** → UX issue, not security
3. **No backups** → Data loss risk, not security
### What Would Be Worse:
1. **Storing actual tokens in files** → Instant compromise
2. **Passing secrets to agents** → AI could leak them
3. **No audit logging** → Can't detect abuse
4. **No response filtering** → Leak secrets in output
## Conclusion
The MCP agent architecture prioritizes:
1. **Never storing secrets** > File permissions
2. **Audit everything** > Prevent everything
3. **Simple & secure** > Complex encryption
The QA issues should be fixed for **defense in depth**, but the core architecture is **fundamentally secure**.