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

• Quickstart Guide
• Cloud Deployment Guide
• Architecture Overview
• Coding Standards

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