# Enterprise MCP Server

A single MCP server that exposes safe, permission-checked "tools" for AI
assistants (Claude, ChatGPT, etc.) to reach:

- **File systems** (local / mounted directories)
- **Databases** (SQL, via SQLAlchemy — works with Postgres/MySQL/SQLite)
- **APIs** (generic authenticated REST calls)
- **Git repositories** (read commits, files, branches; create branches/commits)
- **Cloud services** (AWS S3 example, swappable for Azure Blob / GCS)
- **Business applications** (Jira example, template for SAP/Salesforce)

The AI never talks to SAP, Postgres, GitHub, or S3 directly. It only talks to
**this server**, and this server enforces auth, permissions, and logging
before touching the real system.

```
Claude / ChatGPT
      │  (MCP protocol, stdio or HTTP)
      ▼
 Enterprise MCP Server  (this project)
      │
      ├── auth.py        → who is calling, what can they do
      ├── logger.py       → audit trail of every tool call
      └── tools/
            ├── filesystem_tools.py
            ├── database_tools.py
            ├── api_tools.py
            ├── git_tools.py
            ├── cloud_tools.py
            └── business_tools.py   (Jira example)
```

## 1. Install

```bash
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env   # then fill in real credentials
```

## 2. Configure

Edit `.env`:

```
# Filesystem
FS_ROOT=/data/shared            # AI can only read/write inside this folder

# Database
DB_URL=postgresql://user:pass@host:5432/dbname

# Generic API
API_BASE_URL=https://api.example.com
API_TOKEN=xxxxx

# Git
GIT_REPO_PATH=/data/repos/my-repo

# Cloud (AWS S3 example)
AWS_ACCESS_KEY_ID=xxxx
AWS_SECRET_ACCESS_KEY=xxxx
AWS_BUCKET=my-bucket
AWS_REGION=us-east-1

# Jira (business app example)
JIRA_BASE_URL=https://yourcompany.atlassian.net
JIRA_EMAIL=bot@yourcompany.com
JIRA_API_TOKEN=xxxx

# Server auth — tokens allowed to call this MCP server, mapped to roles
MCP_TOKENS_JSON={"finance-token-123":"finance","hr-token-456":"hr","admin-token-789":"admin"}
```

Never commit `.env`. Only `.env.example` (with fake values) goes into git.

## 3. Run

```bash
python server.py
```

By default this runs over **stdio** — the standard way Claude Desktop / Claude
Code launch local MCP servers. To expose it over HTTP for remote clients,
see `server.py` — there's a commented-out `mcp.run(transport="streamable-http")` block.

## 4. Point an MCP client at it

**Claude Desktop / Claude Code** (`claude_desktop_config.json` or `.mcp.json`):

```json
{
  "mcpServers": {
    "enterprise": {
      "command": "python",
      "args": ["/absolute/path/to/mcp-enterprise-server/server.py"],
      "env": {
        "MCP_CALLER_TOKEN": "finance-token-123"
      }
    }
  }
}
```

## 5. How permissions work here

Every tool call goes through `auth.require_permission(role, action)` before
touching a real system. Roles and their allowed actions live in
`auth.py -> ROLE_PERMISSIONS`. This is intentionally simple (a Python dict) —
swap it for OAuth2/Entra ID + a real policy engine (OPA, Casbin) once you move
past prototyping. See "Hardening for production" below.

Every call is also written to `audit.log` via `logger.py`, with: timestamp,
caller role, tool name, arguments (redacted), and result status.

## 6. Adding a new connector (e.g. Salesforce, SAP)

1. Create `tools/salesforce_tools.py`, following the pattern in
   `tools/business_tools.py` (Jira). Wrap the vendor SDK/REST calls in plain
   Python functions that return JSON-serializable data.
2. In `server.py`, import the module and register each function with
   `@mcp.tool()`.
3. Add required permission checks (`auth.require_permission(...)`) inside
   each function, *not* just at the top-level route — defense in depth.
4. Add new env vars to `.env.example` and `config.py`.
5. Add an entry to `auth.ROLE_PERMISSIONS` for who can call it.

## 7. Hardening for production (do this before connecting real enterprise data)

- [ ] Replace the static token map in `auth.py` with real **OAuth 2.0 /
      Microsoft Entra ID / SAML**, validating short-lived JWTs.
- [ ] Terminate the server behind **HTTPS/TLS** (reverse proxy: nginx/Caddy),
      never plain HTTP.
- [ ] Move `audit.log` into a real log pipeline (ELK, Splunk, CloudWatch) with
      tamper-evidence / write-once storage.
- [ ] Add **rate limiting** per caller (e.g. `slowapi` if using HTTP transport).
- [ ] Store secrets in a vault (AWS Secrets Manager, HashiCorp Vault, Azure
      Key Vault) — not in `.env` on disk.
- [ ] Restrict `FS_ROOT` and DB credentials to least privilege — a read-only
      DB user for read tools, a separate write-scoped user for write tools.
- [ ] Add automated tests per tool (see `tests/` — start one per connector).
- [ ] Run periodic dependency updates + a security scan (`pip-audit`, `npm audit`).
- [ ] Penetration test before go-live, especially the auth boundary.

## Project layout

```
mcp-enterprise-server/
├── README.md
├── requirements.txt
├── .env.example
├── config.py            # loads env vars
├── auth.py               # token → role, role → permissions
├── logger.py              # audit logging
├── server.py               # MCP server entrypoint, registers all tools
└── tools/
    ├── __init__.py
    ├── filesystem_tools.py
    ├── database_tools.py
    ├── api_tools.py
    ├── git_tools.py
    ├── cloud_tools.py
    └── business_tools.py
```