.well-known MCP Configuration for External Service Integration

Timeframe: 2024-Present

Role: Technical Architect

Technologies: Web Standards, JSON, REST APIs, MCP Protocol

Example: MotherboardRepair.ca Tracker

How the .well-known directory enables seamless integration between websites and external services through Model Context Protocol (MCP) configuration.

The Challenge

Modern web applications increasingly need to integrate with external services - from repair tracking systems like MotherboardRepair.ca to analytics platforms, content management systems, and specialized business tools. However, these integrations often require manual configuration, API key exchanges, and hardcoded endpoints.

The .well-known directory, a web standard established by RFC 8615, provides a standardized location for websites to publish configuration metadata. This creates an opportunity to use Model Context Protocol (MCP) configurations to enable external services to automatically discover integration capabilities and configuration details.

The Approach

The solution involves creating MCP configuration files in the .well-known directory that external services can discover and consume. This approach provides several benefits:

Service Discovery

External services can automatically detect integration capabilities by checking standard endpoints like:

/.well-known/mcp.json - Primary MCP configuration
/.well-known/services.json - Available service integrations
/.well-known/webhooks.json - Webhook configuration endpoints

Configuration Sharing

Instead of manual API key exchanges, services can publish their integration requirements and capabilities in a standardized format:

{
  "mcp": {
    "version": "1.0",
    "services": [
      {
        "name": "repair-tracker",
        "type": "external-integration",
        "endpoint": "https://tracker.motherboardrepair.ca/",
        "capabilities": ["ticket-lookup", "status-updates"],
        "auth": {
          "type": "api-key",
          "discovery": "/.well-known/mcp-auth.json"
        }
      }
    ]
  }
}

Real-World Example: MotherboardRepair.ca Integration

The MotherboardRepair.ca repair tracking system demonstrates this pattern in action. When a website integrates with their repair service:

Discovery Phase: The external service checks https://example.com/.well-known/mcp.json
Capability Detection: Identifies available integration points and required authentication
Configuration: Automatically configures webhooks and API endpoints
Integration: Seamlessly connects repair ticket systems with customer websites

Configuration Example

{
  "mcp": {
    "version": "1.0",
    "integrations": {
      "repair-tracking": {
        "provider": "MotherboardRepair.ca",
        "base_url": "https://tracker.motherboardrepair.ca/",
        "endpoints": {
          "ticket_lookup": "/api/tickets/{ticket_id}",
          "status_webhook": "/webhooks/repair-status"
        },
        "authentication": {
          "method": "bearer-token",
          "token_endpoint": "/oauth/token"
        },
        "webhook_config": {
          "events": ["status_changed", "repair_completed"],
          "secret_header": "X-Webhook-Secret"
        }
      }
    }
  }
}

Technical Implementation

Directory Structure

.well-known/
├── mcp.json              # Main MCP configuration
├── services.json         # Available services
├── webhooks.json         # Webhook endpoints
└── auth/
    ├── oauth.json        # OAuth configuration
    └── api-keys.json     # API key specifications

Security Considerations

All .well-known endpoints should use HTTPS
Sensitive configuration data should be protected
Webhook secrets should be rotated regularly
Rate limiting should be implemented on discovery endpoints

CORS and Access Control

External services need appropriate CORS headers to access .well-known resources:

location /.well-known/ {
    add_header Access-Control-Allow-Origin *;
    add_header Access-Control-Allow-Methods "GET, OPTIONS";
    add_header Access-Control-Allow-Headers "Authorization, Content-Type";
}

Results & Impact

This approach enables:

Automatic Integration: External services can self-configure without manual setup
Standardized Discovery: Consistent patterns across different service types
Improved Security: Reduced need for hardcoded credentials and endpoints
Scalability: Easy addition of new integration points
Developer Experience: Simplified integration workflows

Future Applications

The .well-known MCP configuration pattern could extend to:

Analytics Platforms: Automatic Google Analytics or Matomo integration
Content Management: WordPress or headless CMS connections
E-commerce: Payment processor and shipping service integration
Communication Tools: Slack, Discord, or email service webhooks
Monitoring Systems: Error tracking and performance monitoring setup

Lessons Learned

Standards Matter: Following web standards like .well-known ensures broad compatibility
Security First: Always implement proper authentication and rate limiting
Versioning: Include version information in configurations for future compatibility
Documentation: Clear documentation of configuration schemas is essential
Testing: Comprehensive testing of discovery and integration workflows

This pattern represents a significant improvement in how web services can integrate with external platforms, moving from manual configuration to automatic discovery and seamless integration.

← Motherboard Repair Nuclear DNS →