SSO MCP Server

# Quickstart Guide This guide walks you through setting up and using the SSO MCP Server. ## Prerequisites - Python 3.11 or later - [uv](https://github.com/astral-sh/uv) for Python package management - For **Local Mode**: An Azure Entra ID (formerly Azure AD) application registration - For **Cloud Mode**: An OAuth 2.0 identity provider (e.g., Azure Entra ID) with JWKS support ## Installation 1. Clone the repository: ```bash git clone <repository-url> cd sso-mcp-server ``` 2. Install dependencies: ```bash uv sync ``` 3. Create your environment file: ```bash cp .env.example .env ``` 4. Configure your environment variables (see [Configuration](#configuration)) ## Authentication Modes The server supports two authentication modes: | Mode | Use Case | Auth Method | |------|----------|-------------| | **LOCAL** (default) | Desktop/developer use | Browser-based Azure SSO | | **CLOUD** | Server/containerized deployment | Bearer token validation | ## Configuration ### Local Mode (Default) For local development and single-user desktop use. Opens browser for Azure SSO. Edit `.env` with your Azure and content settings: ```bash # Authentication mode AUTH_MODE=local # Azure Entra ID credentials AZURE_CLIENT_ID=your-azure-client-id AZURE_TENANT_ID=your-azure-tenant-id # Content directories (absolute or relative paths) CHECKLIST_DIR=./checklists PROCESS_DIR=./processes # Server port (default: 8080) MCP_PORT=8080 # Logging level (DEBUG, INFO, WARNING, ERROR) LOG_LEVEL=INFO ``` #### Azure App Registration (Local Mode) 1. Go to [Azure Portal](https://portal.azure.com) > Azure Active Directory > App registrations 2. Create a new registration with: - **Name**: SSO MCP Server - **Supported account types**: Accounts in this organizational directory only - **Redirect URI**: Select "Public client/native (mobile & desktop)" and add `http://localhost` 3. Copy the **Application (client) ID** → `AZURE_CLIENT_ID` 4. Copy the **Directory (tenant) ID** → `AZURE_TENANT_ID` 5. Under **Authentication**: - Enable "Allow public client flows" → Yes - Add platform "Mobile and desktop applications" - Select `http://localhost` as redirect URI ### Cloud Mode For server deployments where clients provide Bearer tokens. No browser interaction required. Edit `.env` with your cloud settings: ```bash # Authentication mode AUTH_MODE=cloud # Resource identifier (must match 'aud' claim in tokens) RESOURCE_IDENTIFIER=api://your-mcp-server # Allowed token issuers (comma-separated) ALLOWED_ISSUERS=https://login.microsoftonline.com/your-tenant-id/v2.0 # Content directories CHECKLIST_DIR=./checklists PROCESS_DIR=./processes # Optional: JWKS cache TTL in seconds (default: 3600) JWKS_CACHE_TTL=3600 # Optional: Advertised scopes SCOPES_SUPPORTED=checklist.read,process.read # Server port (default: 8080) MCP_PORT=8080 # Logging level LOG_LEVEL=INFO ``` #### Azure App Registration (Cloud Mode) 1. Go to [Azure Portal](https://portal.azure.com) > Azure Active Directory > App registrations 2. Create a new registration with: - **Name**: SSO MCP Server API - **Supported account types**: Choose based on your needs 3. Go to **Expose an API**: - Set the Application ID URI (e.g., `api://sso-mcp-server`) - Add scopes as needed (e.g., `checklist.read`, `process.read`) 4. Go to **Manifest** and set `"accessTokenAcceptedVersion": 2` 5. Note your: - **Application ID URI** → `RESOURCE_IDENTIFIER` - **Issuer URL**: `https://login.microsoftonline.com/{tenant-id}/v2.0` → `ALLOWED_ISSUERS` For detailed cloud deployment instructions, see [Cloud Deployment Guide](./cloud-deployment.md). ## Running the Server ### Local Mode ```bash uv run sso-mcp-server ``` On first run, a browser window will open for Azure SSO authentication. ### Cloud Mode ```bash AUTH_MODE=cloud \ RESOURCE_IDENTIFIER=api://your-mcp-server \ ALLOWED_ISSUERS=https://login.microsoftonline.com/tenant-id/v2.0 \ CHECKLIST_DIR=./checklists \ PROCESS_DIR=./processes \ uv run sso-mcp-server ``` In cloud mode: - No browser login required - Clients must provide `Authorization: Bearer <token>` header - Tokens are validated against the configured issuer(s) The server uses **HTTP Streamable transport** and listens on `http://localhost:8080/mcp`. ## Integrating with AI Assistants ### Claude Desktop Add to your Claude Desktop configuration file: **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` ```json { "mcpServers": { "sso-mcp-server": { "type": "http", "url": "http://localhost:8080/mcp" } } } ``` > **Note**: Start the server first with `uv run sso-mcp-server` before connecting from Claude Desktop. ### VSCode with GitHub Copilot Create or edit `.vscode/mcp.json` in your workspace: ```json { "servers": { "sso-mcp-server": { "type": "http", "url": "http://localhost:8080/mcp" } } } ``` > **Note**: Start the server first with `uv run sso-mcp-server` before connecting from VSCode. ### Cline (VSCode Extension) Cline has a built-in MCP configuration UI: 1. Click the **MCP Servers** icon at the top of the Cline pane 2. Select the **Configure** tab 3. Click **Configure MCP Servers** 4. Add your server: - **Name**: `sso-mcp-server` - **Type**: `http` - **URL**: `http://localhost:8080/mcp` > **Note**: Start the server first with `uv run sso-mcp-server` before connecting from Cline. ### Claude Code CLI Add to `~/.claude/claude_desktop_config.json`: ```json { "mcpServers": { "sso-mcp-server": { "type": "http", "url": "http://localhost:8080/mcp" } } } ``` Or use the CLI command: ```bash claude mcp add --transport http sso-mcp-server http://localhost:8080/mcp ``` ## Available Tools Once authenticated, your AI assistant can use these tools: ### Checklist Tools #### get_checklist Retrieves a specific checklist by name (case-insensitive). **Example prompts**: - "Get the coding checklist" - "Show me the architecture review checklist" #### list_checklists Lists all available checklists with their descriptions. **Example prompts**: - "List available checklists" - "What checklists do I have?" ### Process Tools #### get_process Retrieves a specific process document by name (case-insensitive). **Example prompts**: - "Get the code review process" - "Show me the deployment process" #### list_processes Lists all available process documents with their descriptions. **Example prompts**: - "List available processes" - "What development processes are defined?" #### search_processes Searches for processes by keyword across name, description, and content. Returns up to 50 results ranked by relevance. **Example prompts**: - "Search for processes about deployment" - "Find processes related to testing" ## Creating Content ### Checklists Create markdown files in your `CHECKLIST_DIR` with YAML frontmatter: ```markdown --- name: Coding Standards description: Checklist for code quality and best practices --- # Coding Standards Checklist ## Naming Conventions - [ ] Variables use descriptive names - [ ] Functions follow verb_noun pattern - [ ] Classes use PascalCase ## Testing - [ ] Unit tests cover main functionality - [ ] Edge cases are tested ``` ### Processes Create markdown files in your `PROCESS_DIR` with YAML frontmatter: ```markdown --- name: Code Review Process description: Step-by-step guide for conducting code reviews --- # Code Review Process ## Before Review 1. Ensure all tests pass 2. Check code coverage meets threshold ## During Review 1. Review for correctness and logic 2. Check for security vulnerabilities 3. Verify coding standards compliance ## After Review 1. Document feedback 2. Track resolution of issues ``` ## Troubleshooting ### Authentication Issues (Local Mode) **Problem**: Browser doesn't open for authentication - Ensure `http://localhost` is configured as a redirect URI in Azure - Check that "Allow public client flows" is enabled **Problem**: Authentication succeeds but server disconnects - This is expected behavior - authentication happens once on startup - Subsequent tool calls use the cached token ### Authentication Issues (Cloud Mode) **Problem**: "Invalid audience" error - Check the `aud` claim in your token (decode at jwt.io) - Ensure it matches `RESOURCE_IDENTIFIER` exactly **Problem**: "Invalid issuer" error - Check the `iss` claim in your token - Ensure it's in `ALLOWED_ISSUERS` (watch for trailing slashes) - Azure v2.0 tokens have issuer: `https://login.microsoftonline.com/{tenant}/v2.0` **Problem**: "Invalid signature" error - Ensure token is from the expected issuer - Check JWKS endpoint is accessible from the server ### Server Issues **Problem**: Server won't start - Check that all required environment variables are set - Verify `CHECKLIST_DIR` exists and contains markdown files **Problem**: Tools not available - Ensure the server started successfully (check logs) - Verify your AI assistant configuration points to the correct URL ### Content Issues **Problem**: Checklist/process not found - Check the exact name matches the `name` field in frontmatter - Names are case-insensitive - Verify the file has `.md` extension ## Token Persistence (Local Mode) Tokens are stored securely at `~/.sso-mcp-server/token_cache.bin`. On server restart: 1. Attempts silent re-authentication using cached tokens 2. If refresh fails, prompts for browser login To clear cached tokens and force re-authentication: ```bash rm ~/.sso-mcp-server/token_cache.bin ``` ## Environment Variables Reference | Variable | Mode | Required | Default | Description | |----------|------|----------|---------|-------------| | `AUTH_MODE` | All | No | `local` | `local` or `cloud` | | `AZURE_CLIENT_ID` | Local | Yes | - | Azure app client ID | | `AZURE_TENANT_ID` | Local | Yes | - | Azure tenant ID | | `RESOURCE_IDENTIFIER` | Cloud | Yes | - | API 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 | | `CHECKLIST_DIR` | All | Yes | - | Checklist directory | | `PROCESS_DIR` | All | No | `./processes` | Process directory | | `MCP_PORT` | All | No | `8080` | Server port | | `LOG_LEVEL` | All | No | `INFO` | Log level | ## Next Steps - Add more checklist and process files to your content directories - See [Cloud Deployment Guide](./cloud-deployment.md) for production deployment - Check [Architecture Overview](./architecture.md) for system design details