SSO MCP Server
MCP server providing development tools with Azure Entra ID authentication.
Overview
This server implements the Model Context Protocol (MCP) to expose development tools to AI coding assistants like GitHub Copilot and Claude Code. It provides access to organizational resources such as:
- Development Checklists: Quality standards and verification items for code reviews, architecture, and design
- Process Documentation: Step-by-step procedures for development workflows like deployments, incident response, and code reviews
- More tools coming soon: The server is designed to be extensible with additional development resources
The server supports two authentication modes:
- Local Mode: Browser-based Azure SSO for desktop/developer use
- Cloud Mode: Bearer token validation for server deployments
Features
- Dual-mode authentication (Local SSO / Cloud Bearer tokens)
- OAuth 2.1 compliant Resource Server (Cloud mode)
- Checklist tools:
get_checklist,list_checklists - Process tools:
get_process,list_processes,search_processes - HTTP Streamable transport for MCP communication
- JWKS-based token validation with caching
- Secure local token persistence (Local mode)
- YAML frontmatter-based metadata for all content types
- Keyword search with relevance ranking for processes
Prerequisites
- Python 3.11+
- uv package manager
- Azure App Registration
- VSCode with GitHub Copilot or Claude Code
Installation
# Clone the repository
git clone <repository-url>
cd sso-mcp-server
# Install dependencies
uv sync
# Configure environment
cp .env.example .env
# Edit .env with your configuration
Authentication Modes
Local Mode (Default)
For desktop/developer use with browser-based Azure SSO:
AUTH_MODE=local
AZURE_CLIENT_ID=your-app-registration-client-id
AZURE_TENANT_ID=your-azure-tenant-id
CHECKLIST_DIR=./checklists
Cloud Mode
For server deployments with Bearer token validation:
AUTH_MODE=cloud
RESOURCE_IDENTIFIER=api://your-app-id
ALLOWED_ISSUERS=https://login.microsoftonline.com/your-tenant-id/v2.0
CHECKLIST_DIR=./checklists
Auto Mode
Automatically detects mode from request context:
AUTH_MODE=auto
# Configure both local and cloud settings
Configuration
| Variable | Mode | Required | Default | Description |
|---|---|---|---|---|
AUTH_MODE | All | No | local | local, cloud, or auto |
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 (seconds) |
CHECKLIST_DIR | All | Yes | - | Checklist directory |
PROCESS_DIR | All | No | ./processes | Process documentation directory |
MCP_PORT | All | No | 8080 | Server port |
LOG_LEVEL | All | No | INFO | Log level |
Usage
Start the server:
# Local mode
uv run sso-mcp-server
# Cloud mode
AUTH_MODE=cloud \
RESOURCE_IDENTIFIER=api://my-app \
ALLOWED_ISSUERS=https://login.microsoftonline.com/tenant/v2.0 \
CHECKLIST_DIR=./checklists \
uv run sso-mcp-server
The server uses HTTP Streamable transport. Configure your AI assistant to connect to http://localhost:8080/mcp.
Supported Clients
This MCP server works with:
- Claude Desktop - Add to
claude_desktop_config.json - VSCode with GitHub Copilot - Add to
.vscode/mcp.json - Cline - Configure via Cline's MCP UI
- GitHub Copilot CLI - Add to
~/.copilot/mcp-config.json - Claude Code CLI - Add to
~/.claude/claude_desktop_config.json
Example configuration:
{
"mcpServers": {
"sso-checklist": {
"type": "http",
"url": "http://localhost:8080/mcp"
}
}
}
Available Tools
Checklist Tools
get_checklist
Retrieve a specific checklist by name (case-insensitive).
{
"name": "coding"
}
list_checklists
List all available checklists with metadata (name, description).
Process Tools
get_process
Retrieve a specific process document by name (case-insensitive).
{
"name": "code-review"
}
list_processes
List all available process documents with metadata (name, description).
search_processes
Search for processes by keyword across name, description, and content. Returns up to 50 results ranked by relevance.
{
"keyword": "deployment"
}
Creating Content
Checklists
Add markdown files to your CHECKLIST_DIR with YAML frontmatter:
---
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
Processes
Add markdown files to your PROCESS_DIR with YAML frontmatter:
---
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
## During Review
1. Review for correctness
2. Check for security issues
3. Verify coding standards compliance
Development
# Run tests
uv run pytest
# Run tests with coverage
uv run pytest --cov=sso_mcp_server
# Run linting
uv run ruff check src/ tests/
# Run formatting
uv run ruff format src/ tests/
# Run security scan
uv run bandit -r src/
Documentation
Project Structure
src/sso_mcp_server/
├── auth/ # Authentication (local + cloud modes)
│ └── cloud/ # JWT validation, JWKS client
├── checklists/ # Checklist service (get, list)
├── processes/ # Process service (get, list, search)
├── config/ # Settings and configuration
├── metadata/ # Protected Resource Metadata
├── tools/ # MCP tool implementations
└── server.py # FastMCP server
checklists/ # Default checklist directory
processes/ # Default process directory
tests/
├── unit/ # Unit tests (266+ total)
├── integration/ # Integration tests
└── e2e/ # End-to-end tests (31 scenarios)
Version History
v0.3.0 (2025-12-13)
- Added Process Query feature with 3 new MCP tools:
get_process,list_processes,search_processes - Keyword search with relevance ranking across process documentation
- E2E test suite with 31 scenarios (100% pass rate)
- Updated project description to reflect multi-function server capability
v0.2.0 (2025-12-12)
- Added dual-mode authentication (LOCAL, CLOUD, AUTO)
- Added OAuth 2.1 Resource Server support
- Added JWT token validation with JWKS
- Added Protected Resource Metadata (RFC 9728)
- Added 91 new tests (218 total)
v0.1.0 (2025-12-11)
- Initial release
- Azure Entra ID SSO authentication
- MCP tools for checklist management
- HTTP Streamable transport
License
MIT
