Enterprise MCP Auth
No description available
Ask AI about Enterprise MCP Auth
Powered by Claude Β· Grounded in docs
I know everything about Enterprise MCP Auth. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
Enterprise MCP Auth
Enterprise MCP Auth with Azure AI Search MCP server/client and ingestion app.
Overview
This project implements a Model Context Protocol (MCP) server and client for Azure AI Search with OAuth authentication and document-level permission filtering. It includes:
- MCP Server: FastMCP server with Azure (Entra ID) OAuth via
AzureProviderand On-Behalf-Of (OBO) flow for Azure AI Search - MCP Client: CLI client using FastMCP's built-in OAuth flow (browser-based)
- LangGraph ReAct Agent: Multi-agent client using LangGraph for intelligent document search and retrieval
- Ingestion Tool: Creates Azure AI Search index with permission filtering and uploads sample documents
Features
- β
Azure AD (Entra ID) OAuth authentication via FastMCP
AzureProvider - β On-Behalf-Of (OBO) token flow for Azure AI Search
- β
Document-level access control via
x_ms_query_source_authorization - β
Four MCP tools:
search_documents,get_document,suggest,get_user_info - β
Permission filtering with USER_IDS (
oidfield) and GROUP_IDS (groupfield) - β Search suggester support
- β LangGraph ReAct agent for intelligent query processing
- β Supervisor graph with identity validation and MCP client management
Installation
- Clone the repository:
git clone https://github.com/denniszielke/enterprise-mcp-auth.git
cd enterprise-mcp-auth
- Install dependencies:
pip install -r requirements.txt
# Or install the package in development mode
pip install -e .
-
Set up Azure AD applications:
Option A: Automated (Recommended)
# Create MCP Server app ./scripts/create-server-app.sh # Create MCP Client app ./scripts/create-client-app.shSee scripts/README.md for detailed instructions.
Option B: Manual
- Follow the manual configuration steps in scripts/README.md
-
Configure environment variables:
cp .env.example .env
# Edit .env with values from the app registration scripts
Configuration
Edit .env file with your Azure credentials:
# Azure Search Configuration
AZURE_SEARCH_ENDPOINT=https://your-search-service.search.windows.net
AZURE_SEARCH_INDEX=documents
AZURE_SEARCH_ADMIN_KEY=your-admin-key
# Azure AD Configuration (server app registration)
AZURE_CLIENT_ID=your-server-app-client-id
AZURE_CLIENT_SECRET=your-server-app-client-secret
AZURE_TENANT_ID=your-tenant-id
# MCP Client Configuration
MCP_SERVER_URL=http://localhost:8000/mcp
# LangGraph CLI Agent (optional)
# MCP_BASE_URL=http://localhost:8000
# MCP_SCOPE=api://your-server-client-id/.default
# OPENAI_API_KEY=your-openai-api-key
Usage
1. Create Index and Ingest Documents
First, create the Azure AI Search index with permission filtering and upload sample documents:
python -m ai_search_ingestion.create_index_and_documents
This will:
- Create an index named
documentswith permission filtering fields - Add a suggester named
sg - Upload 8 sample documents
- Inject the current Azure CLI user ID,
AI_SEARCH_QUERY_USER_ID, andAI_SEARCH_QUERY_GROUP_IDinto every document'soid/groupfields
2. Start the MCP Server
Start the MCP server with AzureProvider OAuth authentication:
python -m enterprise_mcp_auth.server.ai_search_mcp_server
The server will:
- Listen on port 8000 (default)
- Use FastMCP
AzureProviderfor Azure AD OAuth (handles authorization code flow via browser) - Use OBO flow to acquire Azure AI Search tokens
- Apply document-level permission filtering
3. Use the MCP Client
Interact with the MCP server using the CLI client:
# List available tools
python -m enterprise_mcp_auth.client.ai_search_mcp_client list-tools
# Search documents
python -m enterprise_mcp_auth.client.ai_search_mcp_client search --query "security" --top 5
# Get a specific document
python -m enterprise_mcp_auth.client.ai_search_mcp_client get --id "doc1"
# Get suggestions
python -m enterprise_mcp_auth.client.ai_search_mcp_client suggest --query "sec" --top 5
The client will:
- Use FastMCP's built-in OAuth flow (
auth="oauth") which opens your browser for Azure AD authentication - Automatically handle token acquisition, caching, and refresh
- Execute the requested tool via the MCP server
4. Use the LangGraph ReAct Agent
For intelligent query processing with natural language, use the LangGraph ReAct agent:
# After installing with pip install -e .
mcp-agent "What documents mention security policies?"
# Or run directly with Python
python -m enterprise_mcp_auth.cli "What documents mention security policies?"
# Use verbose mode to see reasoning steps
mcp-agent "Find documents about authentication" --verbose
# Specify a different OpenAI model
mcp-agent "Search for compliance documents" --model gpt-4
The LangGraph agent will:
- Authenticate using device code flow (or client credentials if
AZURE_CLIENT_SECRETis set) - Create a ReAct agent with access to MCP tools
- Process your natural language query
- Automatically call appropriate tools (search, get, suggest)
- Return a comprehensive answer based on retrieved documents
Example interaction:
$ mcp-agent "What are the security policies mentioned in the documents?"
π€ LangGraph ReAct Agent for Azure AI Search
============================================================
π Acquiring access token...
Tenant: your-tenant-id
Client: your-client-id
Scope: api://your-server-client-id/.default
To sign in, use a web browser to open the page https://microsoft.com/devicelogin and enter the code XXXXXXXXX to authenticate.
β Token acquired for user: user@example.com
π Query: What are the security policies mentioned in the documents?
π MCP Server: http://localhost:8000
π€ Model: gpt-4o-mini
============================================================
π Response:
Based on the search results, here are the security policies mentioned in the documents:
1. **Document Security Policy (doc1)**: This document outlines general security guidelines...
2. **Access Control Policy (doc3)**: Details the access control mechanisms...
These documents provide comprehensive security guidelines for the organization.
============================================================
β Query completed successfully
Architecture
Permission Filtering
The system enforces document-level access control through:
-
Index Fields:
oid: Collection of user IDs (USER_IDS permission filter)group: Collection of group IDs (GROUP_IDS permission filter)
-
OAuth + OBO Token Flow:
- Client authenticates via browser-based Azure AD OAuth (managed by FastMCP
AzureProvider) - MCP server receives the upstream Azure AD token
- Server uses OBO to exchange it for an Azure AI Search token
- Token contains user/group claims
- Client authenticates via browser-based Azure AD OAuth (managed by FastMCP
-
Query-Time Filtering:
- Server passes OBO token via
x_ms_query_source_authorizationparameter - Azure AI Search filters results based on token claims
- Only documents matching user's
oidorgroupare returned
- Server passes OBO token via
MCP Tools
-
search_documents(query: str, top: int = 5)
- Full-text search across the index
- Returns top N matching documents
- Applies permission filtering
-
get_document(id: str)
- Retrieves a specific document by ID
- Applies permission filtering
- Returns document or error if not found/accessible
-
suggest(query: str, top: int = 5)
- Auto-complete suggestions using the
sgsuggester - Returns top N suggestions
- Applies permission filtering
- Auto-complete suggestions using the
-
get_user_info()
- Returns information about the authenticated Azure user
- Extracts claims from the access token (sub, email, name, etc.)
Security
- Azure AD OAuth 2.0 via FastMCP
AzureProviderfor all operations - AzureProvider handles token issuance and verification internally
- On-Behalf-Of flow ensures user context is preserved
- Document-level access control enforced by Azure AI Search
- No direct admin key exposure to clients
Agent Framework Integration
The repository now includes support for Agent Framework with Agent Identity authentication. This allows agents to authenticate directly to Azure services using agent identities instead of user credentials.
Agent Framework Features
- β Agent identity creation and management using Agent Identity Python SDK
- β Agent blueprint definition using Agent Framework Core
- β Direct Azure AI Search authentication (bypassing MCP server)
- β Token-based authentication for Azure services
- β Comprehensive error handling and logging
Agent Framework Components
The agent framework is organized in the src/enterprise_mcp_auth/agent_framework/ directory:
- agent_identity.py: Manages agent identity creation and token acquisition
- agent_blueprint.py: Defines agent blueprints with capabilities
- agent.py: Main agent implementation with Azure AI Search integration
Agent Framework Configuration
Add the following environment variables to your .env file:
# Agent Framework Configuration
AGENT_IDENTITY_CLIENT_ID=your-agent-identity-client-id
AGENT_IDENTITY_TENANT_ID=your-agent-identity-tenant-id
AGENT_IDENTITY_AUDIENCE=https://search.azure.com/.default
AGENT_BLUEPRINT_NAME=enterprise-blueprint
AGENT_NAME=enterprise-agent
Agent Framework Usage
1. Setup Agent Identity
Create an agent identity for authentication:
python scripts/agent/setup_agent_identity.py
This script:
- Initializes the agent identity manager
- Validates identity configuration
- Creates an agent identity with the specified name
- Associates it with a blueprint
2. Setup Agent Blueprint
Define an agent blueprint with capabilities:
python scripts/agent/setup_agent_blueprint.py
This script:
- Creates an agent blueprint
- Defines capabilities (search_documents, retrieve_document, authenticate_to_azure)
- Validates the blueprint configuration
3. Run Agent
Execute the agent with authentication:
# Run with default search query
python scripts/agent/run_agent.py
# Run with custom search query
python scripts/agent/run_agent.py "security policies"
The agent will:
- Authenticate using agent identity
- Connect to Azure AI Search
- Execute the search query
- Display results with document details
4. Test Direct Azure AI Search Access
Test direct authentication to Azure AI Search without using the MCP server:
# Test with default query
python scripts/agent/test_ai_search_direct.py
# Test with custom query
python scripts/agent/test_ai_search_direct.py "compliance"
This script demonstrates:
- Direct Azure AI Search authentication using agent identity
- Token acquisition for Azure AI Search
- Document search and retrieval
- Bypassing the MCP server for direct API access
Example output:
$ python scripts/agent/test_ai_search_direct.py "security"
============================================================
Direct Azure AI Search Test with Agent Identity
============================================================
Endpoint: https://your-search-service.search.windows.net
Index: documents
Search Query: security
Initializing Agent Identity Manager...
β Tenant ID: your-tenant-id
β Client ID: your-client-id
Acquiring access token for Azure AI Search...
β Token acquired (length: 1234)
Creating Azure Search client for index: documents...
β Search client created
Searching for: 'security'...
β Found 3 documents
Search Results:
------------------------------------------------------------
1. Document ID: doc1
Title: Document Security Policy
Content: This document outlines security guidelines...
Score: 2.4567
2. Document ID: doc3
Title: Access Control Policy
Content: Details about access control mechanisms...
Score: 1.8901
============================================================
Test completed successfully!
============================================================
Agent Framework Architecture
Agent Identity
β
Agent Blueprint
β
Enterprise Agent
β
Azure AI Search Client (Direct Auth)
β
Search / Retrieve Documents
Key Components:
- AgentIdentityManager: Manages agent identity and token acquisition
- AgentBlueprintManager: Defines agent capabilities and configuration
- EnterpriseAgent: Main agent implementation with Azure AI Search integration
- TokenCredential: Simple credential adapter for Azure SDK
Agent Identity vs User Identity
Agent Identity (New):
- Uses service principal or managed identity
- Suitable for automated agents and services
- Direct authentication to Azure services
- No user interaction required
- Ideal for background tasks and automation
User Identity (Existing):
- Uses browser-based OAuth flow via FastMCP
AzureProvider - Requires user authentication
- Uses On-Behalf-Of (OBO) flow through MCP server
- Document-level access control based on user claims
- Ideal for interactive applications
Agent Framework References
Development
Project Structure
enterprise_mcp_auth/
βββ __init__.py
βββ cli.py # LangGraph ReAct agent CLI
βββ server/
β βββ __init__.py
β βββ __main__.py
β βββ ai_search_mcp_server.py
βββ client/
β βββ __init__.py
β βββ __main__.py
β βββ ai_search_mcp_client.py # MCP client (uses FastMCP built-in OAuth)
β βββ auth.py # MSAL authentication helpers (used by LangGraph agent)
β βββ mcp_client.py # Authenticated MCP client wrapper (used by LangGraph agent)
βββ agents/
β βββ __init__.py
β βββ state.py # Graph state definitions
β βββ tools.py # LangChain tool wrappers
β βββ react_agent.py # ReAct agent implementation
β βββ supervisor.py # Supervisor graph
βββ agent_framework/
βββ __init__.py
βββ agent_identity.py # Agent identity management
βββ agent_blueprint.py # Agent blueprint definition
βββ agent.py # Main agent implementation
ai_search_ingestion/
βββ __init__.py
βββ __main__.py
βββ create_index_and_documents.py # Index creation & document ingestion
Requirements
- Python 3.8+
- fastmcp==2.14.5
- msal>=1.31.0
- azure-search-documents>=11.6.0
- azure-core>=1.32.0
- python-dotenv>=1.0.0
- langgraph>=0.2.0
- langchain-openai>=0.2.0
- langchain-core>=0.3.0
- click>=8.1.0
- requests>=2.31.0
- agent-framework-core==1.0.0b260116
- azure-identity==1.25.1
- agent-identity-python-sdk>=0.1.2
LangGraph Architecture
The LangGraph ReAct agent implementation follows this architecture:
User Query
β
Supervisor Graph
β
1. Identity Validation
- Check identity context exists
- Validate access token
β
2. ReAct Agent Node
- Create authenticated MCP client
- Initialize ReAct agent with MCP tools
- Process query using reasoning + action loop
β
3. Tool Execution
- search_documents: Search index
- get_document: Retrieve by ID
- suggest: Get suggestions
- get_user_info: Get authenticated user info
β
Response
Key Components:
- IdentityContext: Carries user identity and access token through the graph
- AgentState: Complete state including messages, identity, query, and MCP URL
- MCPTools: LangChain tool wrappers for MCP server tools
- ReAct Agent: Uses LangGraph's
create_react_agentwith OpenAI LLM - Supervisor: Orchestrates identity validation and agent execution
License
MIT
