Static Secure MCP - AI-Enhanced Model Context Protocol Gateway

Overview

This repository demonstrates a comprehensive implementation of the Model Context Protocol (MCP) with AI-powered enhancement capabilities and multiple inspection interfaces. It provides a complete solution for generating, enriching, serving, and testing MCP catalogs from OpenAPI specifications using Azure OpenAI services.

The project includes both HTTP and stdio transport implementations, making it compatible with various MCP clients including Claude Desktop and the official MCP Inspector.

Key Features

AI-Enhanced MCP Generation: Automatically enriches MCP tool definitions with business context using Azure OpenAI
Dual Transport Support: Both HTTP and stdio transport implementations for maximum compatibility
MCP Inspector Integration: Built-in support for the official MCP Inspector tool for development and testing
Secure API Gateway Pattern: Zero-trust implementation with policy enforcement and execution controls
OpenAPI Integration: Seamless conversion from Swagger/OpenAPI specifications to MCP format
Enterprise Security: Built for regulated environments with comprehensive security controls
Cross-Platform Support: Scripts available for both PowerShell (Windows) and Bash (Linux/WSL)

Architecture Components

1. McpGen.Cli - AI-Enhanced MCP Generator

The core command-line tool that converts OpenAPI specifications into enriched MCP catalogs.

Recent Enhancements

The Program.cs has been significantly enhanced with AI capabilities:

New Command-Line Options:

--source-path: Path to API source code for AI analysis
--ai-endpoint: Azure OpenAI endpoint URL
--ai-key: API key for Azure OpenAI authentication
--ai-model: Model selection (gpt-4, gpt-3.5-turbo, etc.)
--enrich-ai: Enable AI-powered enrichment

AI Enrichment Features:

Source Code Analysis: Examines API implementation code to understand business logic
Intelligent Prompt Generation: Creates context-aware prompts for AI analysis
Comprehensive Documentation: Generates detailed tool descriptions including:
- Business purpose and use cases
- Expected behavior and side effects
- Error scenarios with specific causes
- Security considerations
- Performance characteristics
- Real-world usage examples

Implementation Details:

EnrichWithAI(): Main orchestration method for AI enhancement process
GenerateEnrichmentPrompt(): Creates intelligent prompts with source code context
CallAIAPI(): HTTP integration with OpenAI/Azure OpenAI endpoints
MergeAIEnrichment(): Combines AI responses into MCP tool definitions
BuildInputSchema(): Converts OpenAPI parameters to JSON Schema with validation

2. SampleApi - Reference Implementation

A demonstration API that serves as both:

Source for MCP generation
Target for secure execution through the gateway pattern

Endpoints:

GET /customers - Retrieve customer list
POST /orders - Create new orders
GET /products - List available products
GET /stats - Business statistics
GET /.well-known/mcp - Serves the AI-enhanced MCP catalog

3. ExecutionGateway - Security Layer

Policy-enforced execution gateway that provides:

Request validation and filtering
Security policy enforcement
Audit logging and compliance
Zero-trust execution model

4. McpStdioWrapper - Transport Adapter

A stdio transport adapter that bridges the MCP Inspector with the HTTP-based ExecutionGateway:

Protocol Translation: Converts JSON-RPC 2.0 stdio messages to HTTP requests
MCP Inspector Compatibility: Enables testing with the official MCP Inspector tool
Debugging Support: Comprehensive logging for troubleshooting
Seamless Integration: Acts as a transparent proxy between Inspector and Gateway

AI Enhancement Scripts

mcp-ai-enrichment.sh

A comprehensive Bash script for AI-powered MCP enhancement with the following capabilities:

Core Features:

Automatic API Detection: Identifies running API instances or starts them as needed
Flexible Configuration: Support for custom endpoints, models, and ports
Error Handling: Robust error management with graceful degradation
Backup Management: Automatic backup of existing MCP configurations
Real-time Feedback: Colored output with progress indicators

Command-Line Interface:

# Basic usage - test mode only
./mcp-ai-enrichment.sh

# Update production MCP catalog
./mcp-ai-enrichment.sh --update-wellknown

# Use different AI model
./mcp-ai-enrichment.sh --model gpt-3.5-turbo

# Custom API port
./mcp-ai-enrichment.sh --api-port 5001

# View all options
./mcp-ai-enrichment.sh --help

Advanced Features:

Process management with PID tracking
Automatic cleanup of background processes
Support for both Windows (WSL) and native Linux environments
JSON validation and tool counting
Integration with existing CI/CD pipelines

Architecture Flow

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│  MCP Inspector  │    │ McpStdioWrapper │    │ExecutionGateway │    │   SampleAPI     │
│   (stdio)       │◄──►│   (adapter)     │◄──►│  (HTTP Gateway) │◄──►│  (backend)      │
└─────────────────┘    └─────────────────┘    └─────────────────┘    └─────────────────┘

The system supports multiple access patterns:

Development/Testing: MCP Inspector → stdio wrapper → HTTP Gateway → API
Production/HTTP: Direct HTTP access to ExecutionGateway
Claude Desktop: Configure stdio wrapper as MCP server

Getting Started

Prerequisites

.NET 8.0 SDK
Node.js ≥22.7.5 (for MCP Inspector)
Azure OpenAI service access (optional, for AI enhancement)
curl and jq (for testing scripts)

Quick Start

Clone the repository

git clone https://github.com/jmfloreszazo/static-secure-mcp.git
cd static-secure-mcp

Install MCP Inspector

npm install -g @modelcontextprotocol/inspector

Run the complete demo (Recommended)
```
# This will start all services and optionally launch MCP Inspector
./demo-test.sh
```
The script will:
- Build all projects
- Start SampleAPI on port 5001
- Start ExecutionGateway on port 5050
- Test the MCP endpoint
- Ask if you want to launch MCP Inspector automatically

Alternative: Manual step-by-step setup

# Start the backend API
dotnet run --project src/SampleApi --urls "http://localhost:5001" &

# Start the ExecutionGateway  
dotnet run --project src/ExecutionGateway --urls "http://localhost:5050" &

# Launch MCP Inspector with stdio wrapper
mcp-inspector dotnet run --project src/McpStdioWrapper

Build-only option

# Just build without starting services
./demo-test.sh --build-only

Quick MCP Inspector launch

# If services are already running, just launch MCP Inspector
./mcp-test.sh

Testing and Development

Interactive Testing with MCP Inspector

The MCP Inspector provides a web-based interface for testing your MCP server:

Access the Inspector: Open the URL provided by the demo script (typically http://localhost:6274)
Available Features:
- Tools List: View all available MCP tools with descriptions and schemas
- Tool Execution: Test individual tools with custom parameters
- Real-time Responses: See immediate results from tool calls
- Schema Validation: Verify input parameters against tool schemas

Testing Workflow:

# Run the complete demo
./demo-test.sh

# Or test against running services
./demo-test.sh --test-only

# Build only (no service startup)
./demo-test.sh --build-only

HTTP Testing

For direct HTTP testing without the Inspector:

# Test MCP catalog discovery
curl http://localhost:5050/.well-known/mcp | jq .

# Test tool execution
curl -X POST http://localhost:5050/execute/ListCustomers \
  -H "Content-Type: application/json" \
  -d '{}'

# Test with parameters
curl -X POST http://localhost:5050/execute/CreateOrder \
  -H "Content-Type: application/json" \
  -d '{"customerId": 1, "product": "Laptop", "quantity": 2}'

Integration with Claude Desktop

To use with Claude Desktop, add this configuration to your claude_desktop_config.json:

{
  "mcpServers": {
    "static-secure-mcp": {
      "command": "dotnet",
      "args": ["run", "--project", "/path/to/src/McpStdioWrapper"],
      "cwd": "/path/to/static-secure-mcp"
    }
  }
}

Configuration

Azure OpenAI Setup

The system supports both Azure OpenAI and standard OpenAI APIs:

Azure OpenAI (Recommended for Enterprise):

Endpoint format: https://{resource}.openai.azure.com/openai/deployments/{model}/chat/completions?api-version=2024-02-15-preview
Models: gpt-4, gpt-4-1106-preview, gpt-3.5-turbo
Authentication: API key or Azure AD

Standard OpenAI:

Endpoint: https://api.openai.com/v1/chat/completions
Models: gpt-4, gpt-3.5-turbo
Authentication: API key

Security Configuration

The system implements enterprise-grade security:

Zero-Trust Architecture: No implicit trust, verify every request
Policy Enforcement: Configurable rules for tool execution
Audit Logging: Comprehensive request and response logging
Identity Integration: Azure AD and other identity providers
Network Security: Private endpoints and network isolation

Cost Optimization

AI enhancement costs are minimal:

GPT-4: $0.03-0.06 per endpoint
GPT-3.5-turbo: $0.002-0.004 per endpoint
ROI: Saves 5-10 minutes of manual documentation per endpoint

Enterprise Integration

CI/CD Pipeline Integration

# Example GitHub Actions workflow
- name: Enhance MCP with AI
  run: |
    ./mcp-ai-enrichment.sh --update-wellknown
    git add src/SampleApi/wwwroot/.well-known/mcp.json
    git commit -m "Update AI-enhanced MCP catalog"

Monitoring and Observability

Application Insights integration
Custom metrics for AI enhancement success rates
Performance monitoring for API response times
Security event logging and alerting

Security Considerations

Data Privacy

Source code analysis is limited to API implementation files
No sensitive data is sent to AI services
Support for private AI endpoints (Azure OpenAI with private access)

Compliance

GDPR compliant (no PII processing)
SOC2 compatible audit trails
HIPAA support with Azure OpenAI BAA
Configurable data retention policies

Contributing

Please read our contribution guidelines and security policy before submitting changes.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For enterprise support and custom implementations, please contact the development team.

Projects Structure

src/
 ├─ SampleApi/        # Reference .NET 8 API with Swagger/OpenAPI and /.well-known/mcp
 ├─ McpGen.Cli/       # CLI tool for AI-enhanced MCP catalog generation
 └─ ExecutionGateway/ # Policy-enforced gateway for secure tool execution

AI-Enhanced MCP Generation

The McpGen.Cli tool provides comprehensive AI-powered documentation enhancement:

Features:

Enhanced descriptions from source code analysis
Business context and use cases generation
Error scenarios and security considerations
Real-world examples and performance notes
Integration with OpenAI GPT-4 and Azure OpenAI

Quick Start:

# Set Azure OpenAI credentials
export AZURE_OPENAI_ENDPOINT="your-endpoint"
export AZURE_OPENAI_KEY="your-key"

# Run AI enhancement
./mcp-ai-enrichment.sh --update-wellknown

Development Tools

Scripts Available

mcp-ai-enrichment.sh - Primary AI enhancement script

Automatic API detection and management
Flexible configuration options
Robust error handling and cleanup
Support for multiple AI models and endpoints

test-mcp-server.sh - MCP endpoint testing utility

Comprehensive endpoint validation
JSON response verification
Performance and availability checks

Usage Examples

# Test mode (no changes)
./mcp-ai-enrichment.sh

# Update production MCP catalog
./mcp-ai-enrichment.sh --update-wellknown

# Use specific AI model
./mcp-ai-enrichment.sh --model gpt-3.5-turbo

# Custom API configuration
./mcp-ai-enrichment.sh --api-port 5001 --endpoint custom-url

Architecture Overview

The system implements a secure, enterprise-ready MCP pattern with the following components:

Discovery Layer:

Static MCP catalogs served via /.well-known/mcp
AI-enhanced tool documentation
Policy-based tool filtering

Security Layer:

Zero-trust execution model
Policy enforcement and validation
Comprehensive audit logging

Integration Layer:

OpenAPI specification compatibility
Azure services integration
Enterprise identity provider support

Testing and Validation

Local Development Testing

# Start the complete stack
./demo-test.sh

# Test individual components
dotnet test

# Validate MCP endpoints
curl http://localhost:5000/.well-known/mcp | jq .

Production Validation

# Health check endpoints
curl http://your-api/health

# MCP catalog validation
curl http://your-api/.well-known/mcp | jq '.tools | length'

# Security policy verification
curl -H "X-Test-Mode: true" http://your-gateway/execute/test-tool

Documentation

Additional Resources

AI-ENRICHMENT-GUIDE.md - Comprehensive AI enhancement documentation
AI-PROMPT-GUIDE.md - Prompt engineering best practices
AI-IMPLEMENTATION-SUMMARY.md - Technical implementation details

Configuration Examples

examples/mcp-ai-enriched-example.json - Sample enhanced MCP output
src/ExecutionGateway/policy.json - Security policy configuration

Security and Compliance

This implementation provides enterprise-grade security suitable for regulated environments:

Security Controls:

Policy-driven tool access control
Request validation and sanitization
Comprehensive audit trails
Identity and access management integration

Compliance Features:

Data privacy protection (no PII processing)
Audit logging for compliance reporting
Configurable retention policies
Support for industry standards (SOC2, HIPAA, GDPR)

Performance and Scalability

AI Enhancement Performance:

Processing time: 30-60 seconds per API
Cost efficiency: $0.03-0.06 per endpoint (GPT-4)
Scalable to hundreds of endpoints
Cacheable results for repeated use

Runtime Performance:

Sub-100ms MCP catalog serving
Concurrent request support
Horizontal scaling capability
CDN-friendly static catalog generation
Constraint enforcement: limits like pageSize, timeouts, schema validation.
Manual approvals: via expiring HMAC tickets (X‑Job‑Ticket).
Scoped credentials: no “god tokens” — each tool has scoped service credentials.
Auditing: who/what/when; payload truncation; PII scrubbing; SIEM export.
Network isolation: Gateway is the only path to the backend.

This pattern is API‑Gateway‑ready: can be implemented in Azure API Management, Kong, or Envoy using policies or filters.

Zero‑Trust MCP Architecture (API Gateway Pattern)

Why this matters

Centralizes RBAC, quotas, and auditing across all MCP backends.
Integrates with Azure Entra ID (OIDC) and Managed Identities.
Enables safe exposure of legacy APIs without code changes.
Aligns with Zero‑Trust principles: no implicit trust, everything verified.

Architecture Diagram

flowchart LR
  subgraph Client[Agent / LLM Client]
    C1["MCP Discovery"]
    C2["Tool Execution"]
  end

  subgraph Edge[Azure Front Door / WAF]
    E1["TLS termination + DDoS + Firewall"]
  end

  subgraph Gateway[API Gateway + Policy Engine]
    G1["Filtered MCP Discovery"]
    G2["POST /execute/:tool"]
    G3["OIDC Auth + RBAC"]
    G4["Rate Limit + Quotas"]
    G5["Schema Validation (OpenAPI)"]
    G6["Manual Approval (HMAC Ticket)"]
    G7["Audit + Correlation IDs"]
  end

  subgraph Security[Azure Identity + Secrets]
    K1["Azure Key Vault"]
    I1["Managed Identity"]
  end

  subgraph Network[Private Network Zone]
    N1["Private Link + vNet"]
    N2["mTLS Gateway↔Backend"]
  end

  subgraph Backend[SampleApi / Legacy APIs]
    B1["/.well-known/mcp"]
    B2["Business Endpoints"]
    B3["Observability: Log Analytics / Sentinel"]
  end

  Client --> E1 --> Gateway
  Gateway -->|fetch| Backend
  Gateway -. logs .-> B3
  Gateway -. secrets .-> K1
  Gateway -. identity .-> I1
  Gateway -. private .-> Network

Hardening Recommendations (Azure)

Identity & Access

Azure Entra ID (OIDC) for agent auth, with Conditional Access (MFA, CAE).
Managed Identity for Gateway → Backend and Key Vault access.
Key Vault for secrets and certificate rotation.
Use RBAC scopes per tool (tool:Orders.Read, tool:Orders.Write).

Networking

Private subnet with Private Link to backends.
mTLS for Gateway ↔ Backend communication.
Fronted by Azure Front Door or Application Gateway (WAF).
Disable public endpoints — deny by default.

Policies & Observability

Enforce OpenAPI schema validation in gateway.
Rate limiting + concurrency control.
Forward X‑Correlation‑ID and log to Azure Monitor / Sentinel.
Scrub PII, truncate large payloads, sign audit logs.
Anomaly detection: detect repeated rejections or misuse patterns.

Compliance & Supply Chain

Generate MCP in CI/CD, sign artifacts, and verify signatures at deploy.
Enable SCA + SAST scanning in pipeline.
Use Infrastructure‑as‑Code (IaC) for reproducibility.

Where Tokens Are Useful

| Token Type | Purpose | Example | |-------------|----------|----------| | JWT / OIDC | Identify the agent or LLM runtime | Azure Entra ID access token | | HMAC Ticket | One‑time approval for sensitive tool | Header X‑Job‑Ticket | | Service Token | Scoped backend access | Managed identity / PAT | | Correlation ID | End‑to‑end traceability | X‑Correlation‑Id | | Replay Protection | Nonce + expiry | Prevents reuse attacks |

Security Hardening Checklist

[x] Dynamic MCP filtering (no static exposure)
[x] Deny‑by‑default policy model
[x] JSON Schema validation per tool
[x] Manual HMAC approval for sensitive ops
[x] Managed Identity + Key Vault integration
[x] Private networking + mTLS
[x] Azure Sentinel logging + PII scrubbing
[x] Rotation of keys and secrets
[x] CI/CD‑signed MCP catalogs
[x] Fuzzing + penetration testing in staging

Adopting the Pattern in an API Gateway

You can embed this ExecutionGateway logic inside an existing API Gateway (Azure APIM, Kong, Tyk, NGINX, Envoy):

As a custom policy/plugin that filters discovery and validates execution.
As a sidecar to enforce schema validation, tickets, and quotas.
As a central catalog gateway merging multiple backends into one MCP view.

Advantages:

Unified RBAC, WAF, telemetry, and secrets management.
Easier onboarding for legacy APIs.
Full audit traceability for regulated industries (finance, insurance, health).

Think of it as ExecutionGateway‑as‑Infrastructure — policy, identity, and compliance baked into the fabric.

What's Inside

SampleApi → Generates or serves MCP catalog (/.well-known/mcp)
McpGen.Cli → Builds static MCPs from Swagger (CI/CD ready)
ExecutionGateway → Enforces policies, executes tools securely

Interactive Demo

./demo-test.sh

This demo:

Builds the full solution
Starts all services automatically
Generates Static MCP from Swagger
Demonstrates filtered discovery & secure execution
Shows blocked tools and manual approvals
Displays logs, tokens, and policy enforcement

Stop services:

./stop-services.sh

Available Scripts

| Script | Purpose | Usage | |--------|---------|-------| | demo-test.sh | Complete demo with all services | ./demo-test.sh | | demo-test.sh --build-only | Build projects only | ./demo-test.sh --build-only | | mcp-test.sh | Quick MCP Inspector launch | ./mcp-test.sh | | stop-services.sh | Stop all running services | ./stop-services.sh |

Quick Commands:

# Complete setup and demo
./demo-test.sh

# Just test MCP Inspector (services must be running)  
./mcp-test.sh

# Manual MCP Inspector launch
mcp-inspector dotnet run --project src/McpStdioWrapper

© 2025 José M. Flores Zazo — MIT License
Built for demonstrating enterprise-grade MCP security & governance.