.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.

Update (2026): Industry momentum around MCP has cooled relative to 2024–2025 peaks. For new work we treat SKILLS.md (or the same instructions under another filename) as the default agent contract: it is usually far cheaper in tokens than standing up MCP for every surface, while /.well-known/mcp.json stays available when you need JSON discovery or legacy clients. The current recommendation is to publish both /.well-known/mcp.json and /.well-known/skills.md when you want a machine-readable endpoint list plus a lightweight human/agent instruction layer. See the MCP Discovery specification for the formal split between SKILLS-first guidance and the optional well-known JSON shape.

This write-up was also updated recently so that the current recommendation is obvious without having to infer it from the older 2024 framing.

Timeline (informative): This story was committed roughly a month before Google publicized MCP-related support in the Chrome browser. That ordering is historical context only.

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. Pair that with SKILLS.md so assistants get conventions first, and keep JSON for endpoints that are awkward to spell out in prose. In the updated pattern, publishing both /.well-known/mcp.json and /.well-known/skills.md gives agents a stable place to look whether they prefer structured JSON or lightweight Markdown instructions.

When the API is not at /

RFC 8615 pins well-known metadata to the origin root, but products rarely live only there:

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 or agent checks https://example.com/.well-known/skills.md and https://example.com/.well-known/mcp.json
  2. Capability Detection: Reads conventions from Markdown and identifies integration points and authentication details from JSON
  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              # Machine-readable endpoint metadata
├── skills.md             # Lightweight agent instructions
├── 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";
}

Specification Shape: /.well-known/mcp.json and /.well-known/skills.md

Below is the specification shape used here for paired MCP discovery and lightweight Markdown agent instructions under .well-known.

Abstract

This document defines a pair of well-known resources, /.well-known/mcp.json and /.well-known/skills.md, that allow a website origin to publish Model Context Protocol (MCP) connection metadata alongside lightweight agent instructions for tools/services associated with that origin (or explicitly delegated services). This enables automatic discovery by compatible clients (agents, IDEs, automations) without forcing every client into the full MCP stack.

Status of This Memo

This document defines the implementation guidance used here for paired well-known agent instructions and MCP discovery resources.

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 additional registry actions for the implementation described here.

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.