# MCP Server for IAM Solutions

A production-ready Model Context Protocol (MCP) Server for Identity and Access Management solutions. Currently supports Okta with an extensible architecture for Azure ENTRA ID, Google Workspace, and more.

## Features

- 🔐 **Okta Integration** - Full user and group management
- 📝 **Audit Logging** - Real-time operation tracking
- 🛡️ **Permission Guardrails** - Three-tier access control (admin/operator/viewer)
- 💾 **Local Database** - SQLite for audit trails and user caching
- ⚡ **Async Support** - Built for performance
- 📊 **Web Dashboard** - Flask-based management UI
- 🔄 **SCIM Support** - SCIM 2.0 provisioning server

## 📁 Project Structure

```
MCP_Final/
├── README.md                   # This file
├── requirements.txt            # Python dependencies
├── run_mcp.bat                # Quick start script
│
├── config/                    # 📋 Configuration files
│   ├── .env.example          # Environment template
│   ├── tenants.yaml          # Tenant configurations
│   └── tenants.yaml.example  # Tenant template
│
├── docs/                      # 📚 Documentation
│   ├── ARCHITECTURE.md       # System architecture
│   └── NGROK_SETUP.md        # Ngrok setup guide
│
├── scripts/                   # 🔧 Utility scripts
│   ├── migrations/           # Database migrations
│   ├── testing/              # Test utilities
│   └── utils/                # General utilities
│
├── src/                       # 🎯 Core MCP server
├── scim/                      # 🔐 SCIM 2.0 server
├── dashboard/                 # 📊 Web dashboard
└── data/                      # 💾 Database files
```

## Quick Start

### 1. Install Dependencies
```powershell
pip install -r requirements.txt
```

### 2. Configure Environment
```powershell
# Copy example environment file
cp config/.env.example .env

# Edit .env with your credentials
notepad .env
```

### 3. Configure Tenants
```powershell
# Copy tenant example
cp config/tenants.yaml.example config/tenants.yaml

# Edit with your Okta details
notepad config/tenants.yaml
```

### 4. Initialize Database
```powershell
python -m src.database.init
```

### 5. Run the Server
```powershell
# Quick start
run_mcp.bat

# Or manually
python -m src.server
```

## Configuration

Configuration files are located in the `config/` directory. See [config/README.md](./config/README.md) for details.

### Environment Variables (`.env`)
| Variable | Description | Required |
|----------|-------------|----------|
| `OIDC_CLIENT_ID` | OAuth client ID | Yes |
| `OIDC_CLIENT_SECRET` | OAuth client secret | Yes |
| `OIDC_DISCOVERY_URL` | OIDC discovery endpoint | Yes |
| `SECRET_KEY` | Flask session secret | Yes |
| `DATABASE_URL` | SQLite database path | No (default: `./data/mcp_server.db`) |
| `LOG_LEVEL` | Logging verbosity | No (default: `INFO`) |

### Tenant Configuration (`config/tenants.yaml`)
Configure multiple Okta tenants. See [config/README.md](./config/README.md) for format.

## Available MCP Tools

### User Management
- `list_okta_users` - List all users with optional filters
- `get_okta_user` - Get user by ID or email
- `create_okta_user` - Create new user
- `update_okta_user` - Update user profile
- `delete_okta_user` - Deactivate/delete user (admin only)
- `suspend_okta_user` / `unsuspend_okta_user` - Manage user status

### Group Management
- `list_okta_groups` - List all groups
- `get_okta_group` - Get group details
- `create_okta_group` - Create new group
- `delete_okta_group` - Delete group (admin only)
- `list_group_members` - List users in a group
- `add_user_to_group` / `remove_user_from_group` - Manage membership

### Audit Tools
- `query_audit_logs` - Search audit history
- `get_user_audit_trail` - User-specific activity
- `export_audit_report` - Generate reports

## Permission Levels

| Level | Read | Create | Update | Delete |
|-------|------|--------|--------|--------|
| Viewer | ✅ | ❌ | ❌ | ❌ |
| Operator | ✅ | ✅ | ✅ | ❌ |
| Admin | ✅ | ✅ | ✅ | ✅ |

## Claude Desktop Integration

Add to your Claude Desktop config (`%APPDATA%\Claude\claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "iam-okta": {
      "command": "python",
      "args": ["-m", "src.server"],
      "cwd": "C:\\path\\to\\MCP_Final"
    }
  }
}
```

## Components

### Core MCP Server (`src/`)
Main Model Context Protocol server providing Okta integration tools.

### SCIM Server (`scim/`)
SCIM 2.0 provisioning server for automated user/group management.

### Dashboard (`dashboard/`)
Web-based management UI with user administration, audit logs, and monitoring.
See [dashboard/README.md](./dashboard/README.md).

## Utilities & Scripts

All utility scripts are in the `scripts/` directory:

- **Migrations:** `scripts/migrations/` - Database migration scripts
- **Testing:** `scripts/testing/` - Test utilities
- **Utils:** `scripts/utils/` - General utilities

See [scripts/README.md](./scripts/README.md) for details.

## Documentation

Complete documentation is in the `docs/` directory:

- [ARCHITECTURE.md](./docs/ARCHITECTURE.md) - System architecture
- [NGROK_SETUP.md](./docs/NGROK_SETUP.md) - Ngrok configuration

See [docs/README.md](./docs/README.md) for the full documentation index.

## License

MIT License