SSO MCP Server

# Quickstart: SSO MCP Checklist Server **Time to complete**: ~5 minutes ## Prerequisites - Python 3.11 or later - uv package manager (`pip install uv` or `curl -LsSf https://astral.sh/uv/install.sh | sh`) - Azure Entra ID account in your organization (for LOCAL mode) - Azure App Registration (client ID and tenant ID from your admin) - VSCode with GitHub Copilot extension OR Claude Code CLI ## Installation ```bash # Clone the repository git clone <repository-url> cd sso-mcp-server # Install dependencies uv sync ``` ## Authentication Modes The server supports two authentication modes: | Mode | Use Case | Auth Method | |------|----------|-------------| | **LOCAL** (default) | Desktop/developer use | Browser-based Azure SSO | | **CLOUD** | Server/multi-tenant deployment | Bearer token validation | | **AUTO** | Flexible deployment | Detects from request context | ## Configuration ### Option A: Local Mode (Default) For local development and single-user desktop use. Opens browser for Azure SSO. ```bash # Required: Azure credentials (get from your admin) export AUTH_MODE="local" export AZURE_CLIENT_ID="your-app-registration-client-id" export AZURE_TENANT_ID="your-tenant-id" # Required: Path to your checklists export CHECKLIST_DIR="./checklists" # Optional: Server port (default: 8080) export MCP_PORT="8080" ``` ### Option B: Cloud Mode For server deployment where clients provide Bearer tokens. ```bash # Required: Cloud mode settings export AUTH_MODE="cloud" export RESOURCE_IDENTIFIER="https://your-mcp-server.example.com" export ALLOWED_ISSUERS="https://login.microsoftonline.com/your-tenant-id/v2.0" # Required: Path to your checklists export CHECKLIST_DIR="./checklists" # Optional: JWKS cache TTL in seconds (default: 3600) export JWKS_CACHE_TTL="3600" # Optional: Supported scopes for metadata export SCOPES_SUPPORTED="checklist:read,checklist:list" ``` ### Option C: Auto Mode Automatically detects mode based on request context. ```bash # Auto mode - tries cloud first if Bearer token present, falls back to local export AUTH_MODE="auto" # Local mode settings (for fallback) export AZURE_CLIENT_ID="your-app-registration-client-id" export AZURE_TENANT_ID="your-tenant-id" # Cloud mode settings (optional, for Bearer token validation) export RESOURCE_IDENTIFIER="https://your-mcp-server.example.com" export ALLOWED_ISSUERS="https://login.microsoftonline.com/your-tenant-id/v2.0" # Required: Path to your checklists export CHECKLIST_DIR="./checklists" ``` ## Add Checklist Files Create markdown files in your checklist directory: ```bash mkdir -p checklists cat > checklists/coding.md << 'EOF' --- name: Coding Standards description: Code quality checklist for reviews --- # Coding Standards Checklist ## Naming - [ ] Variables use descriptive names - [ ] Functions follow verb_noun pattern ## Structure - [ ] Single responsibility per function - [ ] No code duplication EOF ``` ## Start the Server ### Local Mode ```bash # Start with environment variables uv run sso-mcp-server # Or with explicit settings AUTH_MODE=local AZURE_CLIENT_ID=xxx AZURE_TENANT_ID=xxx CHECKLIST_DIR=./checklists uv run sso-mcp-server ``` The server will: 1. Start on port 8080 (or MCP_PORT) 2. Open your browser for Azure SSO login (on first tool call) 3. After login, cache tokens for future sessions ### Cloud Mode ```bash AUTH_MODE=cloud \ RESOURCE_IDENTIFIER=https://api.example.com \ ALLOWED_ISSUERS=https://login.microsoftonline.com/tenant/v2.0 \ CHECKLIST_DIR=./checklists \ uv run sso-mcp-server ``` In cloud mode: 1. No browser login required 2. Clients must provide `Authorization: Bearer <token>` header 3. Tokens are validated against the configured issuer(s) ## Connect Your AI Assistant ### VSCode with GitHub Copilot Add to `.vscode/mcp.json`: ```json { "mcpServers": { "sso-checklist": { "url": "http://localhost:8080/mcp", "transport": "http-streamable" } } } ``` ### Claude Code Add to `~/.claude/claude_desktop_config.json`: ```json { "mcpServers": { "sso-checklist": { "url": "http://localhost:8080/mcp", "transport": "http-streamable" } } } ``` ## Verify Installation In your AI assistant, try: ``` List all available development checklists ``` Expected response: List of your configured checklists ``` Get the coding checklist ``` Expected response: Full content of your coding checklist ## Troubleshooting ### "Port 8080 is already in use" Change the port: ```bash export MCP_PORT=8081 uv run sso-mcp-server ``` Update your MCP config to use the new port. ### "Authentication failed" (Local Mode) 1. Check AZURE_CLIENT_ID and AZURE_TENANT_ID are correct 2. Ensure your Azure App Registration has redirect URI: `http://localhost` 3. Verify you have access in your organization's Azure tenant ### "Invalid token" (Cloud Mode) 1. Verify the token's `aud` claim matches `RESOURCE_IDENTIFIER` 2. Verify the token's `iss` claim is in `ALLOWED_ISSUERS` 3. Check token is not expired 4. Ensure token is properly signed by the issuer ### "No checklists found" 1. Check CHECKLIST_DIR points to existing directory 2. Ensure checklist files have `.md` extension 3. Verify files have valid YAML frontmatter ### Server not responding 1. Check server is running (terminal shows "Server ready") 2. Verify correct URL in MCP config 3. Try `curl http://localhost:8080/mcp` to test connectivity ## Environment Variables Reference | Variable | Mode | Required | Default | Description | |----------|------|----------|---------|-------------| | `AUTH_MODE` | All | No | `local` | Authentication mode: `local`, `cloud`, `auto` | | `AZURE_CLIENT_ID` | Local | Yes* | - | Azure app client ID | | `AZURE_TENANT_ID` | Local | Yes* | - | Azure tenant ID | | `RESOURCE_IDENTIFIER` | Cloud | Yes* | - | This server's resource URL (audience) | | `ALLOWED_ISSUERS` | Cloud | Yes* | - | Comma-separated issuer URLs | | `JWKS_CACHE_TTL` | Cloud | No | `3600` | JWKS cache TTL in seconds | | `SCOPES_SUPPORTED` | Cloud | No | - | Advertised scopes (comma-separated) | | `CHECKLIST_DIR` | All | Yes | - | Directory containing checklist files | | `MCP_PORT` | All | No | `8080` | Server port | | `LOG_LEVEL` | All | No | `INFO` | Log level: DEBUG, INFO, WARNING, ERROR | *Required based on AUTH_MODE setting. ## Next Steps - Add more checklist files to your CHECKLIST_DIR - Customize checklists with YAML frontmatter (name, description) - Check logs at `~/.sso-mcp-server/logs/` for debugging - See [Cloud Deployment Guide](../../docs/cloud-deployment.md) for production setup ## Support - GitHub Issues: <repository-issues-url> - Documentation: `docs/architecture.md`