# SecureMCP Agent Hub 🔐🤖

> An end-to-end reference project showing how an AI agent can securely retrieve enterprise data, call multiple MCP tools, enforce permissions, request human approval, and write auditable workflow events.

## Why this project exists
Most agent demos focus on tool calling but skip identity, least privilege, tenant isolation, approvals, auditability, and prompt-injection controls. SecureMCP Agent Hub makes those concerns visible in a runnable starter.

## Highlights
- MCP server exposing tools and resources
- Claude-powered agent with deterministic demo fallback
- Multi-tool workflows across customer, order, document, and ticket data
- API-key authentication and tenant-scoped RBAC
- Read-only vs approval-required tool policy
- Human approval queue for consequential actions
- Audit events for every tool decision and execution
- Basic untrusted-content and prompt-injection screening
- FastAPI REST gateway and Swagger UI
- SQLite locally, PostgreSQL-ready configuration
- Docker, tests, GitHub Actions, security policy, and contribution guide

## Safety boundary
This is an educational reference architecture, not a production-certified enterprise platform. It uses synthetic seed data. Before production, add your identity provider, OAuth/OIDC, managed secrets, row-level database security, immutable audit storage, rate limits, recovery plans, formal threat modelling, and independent security review.

## Architecture
```mermaid
flowchart LR
 U[User / Enterprise App] -->|API key + tenant + role| API[FastAPI Gateway]
 API --> AG[Agent Orchestrator]
 AG --> PE[Policy Engine]
 PE -->|allowed| MC[MCP Client]
 PE -->|approval required| AQ[Approval Queue]
 MC --> MS[MCP Tool Server]
 MS --> DB[(Tenant Data)]
 AG --> CL[Claude API optional]
 API --> AU[(Audit Events)]
```

## Tools
- `search_customers`: read-only customer search
- `get_customer_orders`: read-only order retrieval
- `search_knowledge`: read-only document retrieval
- `get_support_tickets`: read-only support retrieval
- `create_support_ticket`: write operation requiring approval
- `export_customer_snapshot`: sensitive export requiring admin approval

## Quick start
```bash
cp .env.example .env
docker compose up --build
```
Open:
- REST docs: http://localhost:8000/docs
- Health: http://localhost:8000/health

Local Python:
```bash
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -r requirements.txt
python -m app.seed
uvicorn app.api:app --reload
```

Run the MCP server independently:
```bash
python -m app.mcp_server
```

Inspect it:
```bash
fastmcp dev app/mcp_server.py
```

## Demo headers
```text
X-API-Key: change-me
X-Tenant-ID: acme
X-Role: analyst
X-Actor-ID: sujal
```
Roles: `viewer`, `analyst`, `operator`, `admin`.

## Ask the agent
```bash
curl -X POST http://localhost:8000/v1/agent/run \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: change-me' \
  -H 'X-Tenant-ID: acme' \
  -H 'X-Role: analyst' \
  -H 'X-Actor-ID: sujal' \
  -d '{"request":"Find customer Asha, show her orders, and retrieve the refund policy."}'
```

The deterministic fallback understands demo intents. Add `ANTHROPIC_API_KEY` for Claude-driven planning.

## Approval workflow
1. An agent requests a write or sensitive tool.
2. The policy engine returns `approval_required`.
3. The API stores a pending approval instead of executing the tool.
4. An admin approves or rejects it.
5. Approved tools are executed explicitly through the approval endpoint.

## Security design
- Credentials only in headers, never query strings
- Constant-time API-key comparison
- Tenant ID bound to every data query
- Role checks before tool execution
- Explicit allowlist of tools and arguments
- Size limits and validation through Pydantic
- Read/write/destructive metadata in one policy registry
- Human approval for writes and exports
- Audit entries for allow, deny, request, approve, reject, execute
- Responses label retrieved documents as untrusted data
- No arbitrary SQL, shell, file, or URL tools

## Test
```bash
pytest -q
ruff check .
```

## Suggested GitHub topics
`mcp` `model-context-protocol` `ai-agents` `tool-calling` `claude` `fastapi` `rbac` `agentic-ai` `python` `enterprise-ai` `llm-security`

## Roadmap
- OAuth2/OIDC and JWKS validation
- PostgreSQL row-level security
- Remote MCP with OAuth
- OpenTelemetry traces and metrics
- RAG with vector and lexical retrieval
- Policy-as-code integration
- Signed approval receipts
- Web console for workflows and audit events

## License
MIT. See `LICENSE`.