Sitecore MCP External Authentication Examples

This repository demonstrates how to integrate with Sitecore's Model Context Protocol (MCP) server using OAuth 2.1 authentication with PKCE, showcasing both Python and .NET implementations.

Overview

These examples show how to build AI agents that can interact with Sitecore content management through MCP tools, using the Microsoft Agent Framework with Azure OpenAI.

📁 Project Structure

SCMP_AI_Foundry_App/
├── python_example/          # Python implementation (fully automated)
│   ├── agent_with_mcp.py   # Main chat app with MCP tools
│   ├── mcp_compliant_auth.py # OAuth 2.1 + PKCE authentication
│   ├── instructions.md      # Agent behavior configuration
│   ├── mcp.json            # MCP server configuration
│   └── README.md           # Python-specific documentation
│
├── dotnet_example/          # .NET implementation (using MCP SDK)
│   └── SitecoreMcpChat/
│       ├── Program.cs      # Main chat application
│       ├── McpOAuthClient.cs    # OAuth 2.1 + PKCE
│       ├── instructions.md      # Agent behavior configuration
│       ├── mcp.json            # MCP server configuration
│       └── README.md           # .NET-specific documentation
│
└── README.md               # This file

🚀 Quick Start

Python (Recommended)

cd python_example
pip install -r requirements.txt
cp .env.example .env        # Configure Azure OpenAI credentials
python agent_with_mcp.py

Features:

• ✅ Streaming responses (word-by-word output)
• ✅ Automatic MCP tool integration
• ✅ 39+ Sitecore tools automatically available
• ✅ Tool call indicators (🔧 emoji)
• ✅ OAuth 2.1 with PKCE and token caching

.NET

cd dotnet_example/SitecoreMcpChat
cp appsettings.example.json appsettings.json  # Configure Azure OpenAI
dotnet run

Features:

• ✅ Official ModelContextProtocol C# SDK (v0.4.0-preview.3)
• ✅ HttpClientTransport for HTTP/SSE connections
• ✅ OAuth 2.1 with PKCE and token caching
• ✅ MCP tool discovery via SDK (39+ tools)
• ✅ Native MCP tool integration via Agent Framework
• ✅ Automatic function calling - agent calls tools as needed
• ✅ Tool call visibility - shows which tools are being called
• ⚠️ No streaming (preview limitation)

🔐 Authentication

Both implementations use OAuth 2.1 with PKCE for secure authentication:

1. Metadata Discovery: Reads OAuth endpoints from .well-known/oauth-authorization-server
2. Dynamic Client Registration: Registers OAuth client with the MCP server
3. PKCE Flow: Uses code challenge/verifier for enhanced security
4. Browser Authentication: Opens browser for user login
5. Local Callback: Runs HTTP server on localhost:3000 to receive auth code
6. Token Exchange: Exchanges authorization code for access token
7. Token Caching: Caches tokens for 24 hours (development only)

⚠️ Security Warning - Token Caching

Current Implementation (Development Only):

• Tokens cached in .mcp_token_cache.json
• 24-hour expiry with 5-minute safety buffer
• Plain text storage
• NO encryption
• NO audit logging

Production Requirements:

• ✅ Use Azure Key Vault or similar secure credential storage
• ✅ Implement managed identities where possible
• ✅ Enable token rotation and refresh mechanisms
• ✅ Set shorter token lifetimes (1 hour maximum)
• ✅ Enable comprehensive audit logging
• ✅ Use encrypted storage for cached credentials
• ❌ NEVER commit token cache files to source control
• ❌ NEVER use plain text file storage in production

🛠️ Available MCP Tools

Both implementations provide access to 39+ Sitecore MCP tools:

Site Management

• List sites, get site information, manage site configuration

Content Management

• Create/update/delete pages and content items
• Search content, get page details, manage page templates

Component Management

• List components, add/remove components from pages
• Manage component datasources, set personalization

Language & Localization

• Get available languages, add language versions to pages

Asset Management

• Search assets, upload files, update asset metadata

Marketing Operations

• Create personalization versions, manage targeting rules

📝 Configuration

Agent Instructions

Both implementations use external instructions.md files for agent behavior:

Python: python_example/instructions.md

• Simple guidelines for when to use MCP tools
• Python Agent Framework handles tool integration automatically

dotnet: dotnet_example/SitecoreMcpChat/instructions.md

• Simple guidelines for when to use MCP tools
• .NET Agent Framework handles tool integration automatically
• Same automatic approach as Python

MCP Server Configuration

Both use mcp.json for MCP server settings:

{
  "mcpServers": {
    "marketer": {
      "url": "https://edge-platform.sitecorecloud.io/mcp/marketer-mcp-prod",
      "auth": {
        "type": "external"
      }
    }
  }
}

Azure OpenAI Configuration

Python: .env file

AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com
AZURE_OPENAI_DEPLOYMENT=gpt-5.1-chat
AZURE_OPENAI_API_KEY=your-api-key
AZURE_OPENAI_API_VERSION=2025-01-01-preview

.NET: appsettings.json file

{
  "AZURE_OPENAI_ENDPOINT": "https://your-resource.openai.azure.com",
  "AZURE_OPENAI_DEPLOYMENT": "gpt-5.1-chat",
  "AZURE_OPENAI_API_KEY": "your-api-key"
}

🔄 Implementation Comparison

Feature	Python	.NET
OAuth 2.1 + PKCE	✅	✅
Token Caching	✅ (24 hours)	✅ (24 hours)
MCP SDK Usage	✅ (MCPStreamableHTTPTool)	✅ (HttpClientTransport)
Tool Discovery	✅ (automatic)	✅ (automatic via SDK)
Tool Execution	✅ (automatic)	✅ (automatic via framework)
Tool Orchestration	✅ (automatic)	✅ (automatic)
Streaming Responses	✅ (word-level)	❌ (preview limitation)
Tool Call Visibility	✅	✅
Conversation History	✅	✅
Instructions File	✅ (instructions.md)	✅ (instructions.md)

Both implementations use native MCP integration:

• Python: Uses MCPStreamableHTTPTool for automatic tool orchestration
• .NET: Passes tools to agent via tools: [.. mcpTools.Cast<AITool>()] for automatic orchestration
• Both follow official Microsoft Agent Framework documentation patterns
• Both are production-ready with automatic function calling

Choose based on your stack: Both implementations provide the same automatic tool calling capabilities.

🎯 Use Cases

• Content Management: Create, update, and manage Sitecore content items
• Site Administration: Manage sites, pages, and templates
• Marketing Operations: Set up personalization and targeting
• Asset Management: Upload and organize media files
• Multi-language Support: Manage content across multiple languages
• Component Management: Configure page layouts and components

📚 Documentation

• Python Example: See python_example/README.md
• dotnet Example: See dotnet_example/README.md
• Microsoft Agent Framework: https://learn.microsoft.com/agent-framework/
• Model Context Protocol: https://modelcontextprotocol.io/
• Sitecore MCP Documentation: https://doc.sitecore.com/mp/en/developers/sdk/0/sitecore-marketplace-sdk/developer-guides.html

🔧 Prerequisites

Python

• Python 3.13+
• Azure OpenAI resource
• Sitecore MCP server access

.NET

• .NET 9.0 SDK+
• Azure OpenAI resource
• Sitecore MCP server access

🤝 Contributing

This is example code for learning purposes. Feel free to adapt and extend for your own use cases.

⚠️ Important Notes

1. Token Caching: Current implementation is for DEVELOPMENT ONLY. Use secure credential storage for production.
2. Error Handling: Examples include basic error handling. Production code should be more robust.
3. Agent Framework Versions: Python uses agent-framework package, .NET uses Microsoft.Agents.AI preview packages.
4. MCP SDK Integration:
   • Python: Native integration via MCPStreamableHTTPTool - fully automatic orchestration
   • .NET: Native integration via Agent Framework - passes tools directly to agent for automatic orchestration
   • Both use official SDKs with automatic function calling
5. Production Use: Both Python and .NET are production-ready with automatic tool calling. Choose based on your preferred tech stack.

📄 License

This is example code for educational purposes.