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