.well-known MCP Configuration for External Service Integration

Timeframe: 2024

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:

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:

  1. Discovery Phase: The external service checks https://example.com/.well-known/mcp.json
  2. Capability Detection: Identifies available integration points and required authentication
  3. Configuration: Automatically configures webhooks and API endpoints
  4. 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

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";
}

Proposed RFC (Draft): /.well-known/mcp.json

There isn’t (yet) an official IETF RFC defining an MCP discovery document under /.well-known/. Below is a proposed RFC-style shape for what that standard could look like for MCP service discovery.

This section is intentionally written in “Internet-Draft” style so it can be reused as a future spec if needed.

Abstract

This document defines a well-known URI, /.well-known/mcp.json, that allows a website origin to publish Model Context Protocol (MCP) connection metadata for tools/services associated with that origin (or explicitly delegated services). This enables automatic discovery by compatible clients (agents, IDEs, automations).

Status of This Memo

This is a non-standard draft intended for documentation and implementation guidance. Implementations may vary until a formal standard exists.

Conventions and Terminology

The key words MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY are to be interpreted as described in BCP 14.

1. Well-Known Resource

2. Document Format (JSON)

The response body MUST be a JSON object containing an mcp object:

{
  "mcp": {
    "spec_version": "2026-01-21",
    "status": "draft",
    "servers": [],
    "tools": []
  }
}

2.1 mcp.spec_version

2.2 mcp.status

2.3 mcp.servers[]

An optional array of MCP servers. Each entry SHOULD include:

2.4 mcp.tools[]

An optional array of tools/services that are not necessarily MCP servers themselves but are discoverable integration targets. Each entry SHOULD include:

3. Delegation and External Services

If a tool/service is hosted on a different origin (e.g., https://tracker.motherboardrepair.ca/), the discovery document MAY list it explicitly, but clients SHOULD treat it as external and apply stricter trust rules:

4. Security Considerations

5. IANA Considerations

This document does not require IANA actions unless standardized as an official well-known URI.

Results & Impact

This approach enables:

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

Live Examples: My MCP-Enabled Services

I've implemented MCP configuration on several of my own services:

Hastebin Service

haste.nixc.us provides a simple paste service with MCP integration:

Markdown Rendering Service

md.colinknapp.com provides markdown rendering with MCP support:

These endpoints allow AI assistants like Claude, ChatGPT, and automation tools to interact with these services programmatically—enabling seamless integration into developer workflows.

Future Applications

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

Observations

  1. Standards Matter: Following web standards like .well-known ensures broad compatibility
  2. Security First: Always implement proper authentication and rate limiting
  3. Versioning: Include version information in configurations for future compatibility
  4. Documentation: Clear documentation of configuration schemas is essential
  5. 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.