MCP Server Discovery: Complete 2026 Guide to Implementing .well-known/mcp.json for AI Agent Connectivity

Last updated: February 7, 2026

According to Anthropic's January 2026 announcement, the Model Context Protocol ecosystem has reached 97 million monthly SDK downloads and over 10,000+ active public MCP servers. With that explosive growth comes a fundamental infrastructure problem: how does an AI client discover what your MCP server offers before connecting to it? The answer is server discovery via .well-known/mcp.json endpoints, a standardized mechanism that lets AI assistants like Claude, ChatGPT, and Cursor automatically detect, inspect, and connect to your server without manual configuration. This guide walks you through the specification, implementation, and production deployment of MCP server discovery endpoints.

What You'll Learn

• What MCP server discovery is and why it matters for the 10,000+ server ecosystem
• The two competing discovery proposals: SEP-1649 (server cards) and SEP-1960 (manifest endpoint)
• How AI clients like Claude, ChatGPT, and VS Code use discovery to auto-configure connections
• Step-by-step implementation with working code for Express.js, Next.js, and FastAPI
• A real production example from Ekamoira's GSC MCP server
• Testing and debugging techniques using MCP Inspector and curl
• Common pitfalls around CORS, HTTPS, and JSON schema validation
• A production readiness checklist for shipping your discovery endpoint

Why Does MCP Server Discovery Matter in 2026?

Model Context Protocol (MCP) has become the universal standard for connecting AI agents to enterprise tools. As Anthropic stated when donating MCP to the Agentic AI Foundation in January 2026, the protocol is now adopted by Anthropic, OpenAI, Google, Microsoft, and AWS. With that level of adoption, the discovery problem has become critical: MCP connects AI to machines differently than traditional APIs, and without a standardized discovery mechanism, each of those 10,000+ servers requires manual configuration.

The discovery problem is well-documented. As Harald Kirschner described in a WorkOS MCP Night recap from October 2025, finding and installing MCP servers has been described as a "Byzantine process" requiring users to manually locate endpoints, configure authentication, and verify compatibility. AI agents themselves are unable to dynamically discover or adapt to available servers without structured metadata.

Metric	Value	Source
Monthly SDK downloads	97 million	Anthropic, Jan 2026
Active public MCP servers	10,000+	Anthropic, Jan 2026
Major platform adopters	Anthropic, OpenAI, Google, Microsoft, AWS	Anthropic, Jan 2026
MCP spec version	November 2025 (JSON Schema 2020-12)	MCP Changelog
MCP Apps Extension	January 2026	MCP Blog

Server discovery solves this by letting servers advertise structured metadata at a well-known URL path. An AI client can issue a single HTTP GET request to learn what tools, resources, and prompts a server provides, what transport protocols it supports, and how to authenticate, all before establishing a full MCP session. This is the same pattern used by OAuth 2.0 (/.well-known/oauth-authorization-server) and OpenID Connect (/.well-known/openid-configuration), applied to the MCP ecosystem.

Key Finding: The MCP specification describes discovery as answering "where to connect and what is available, while initialization handles how to communicate" -- SEP-1649

For teams building or maintaining MCP servers, implementing a discovery endpoint is rapidly becoming table stakes. If you are choosing the right MCP server for your workflow, understanding how discovery works is essential for production readiness.

What Are the Two Discovery Specification Proposals?

The MCP community has developed two complementary specification enhancement proposals (SEPs) for server discovery. Understanding both is important because they address different aspects of the discovery problem and may eventually be merged or adopted in parallel.

SEP-1649: MCP Server Cards via .well-known/mcp/server-card.json

SEP-1649 proposes that MCP servers expose a structured metadata document called a "server card" at the path /.well-known/mcp/server-card.json. According to the proposal, "MCP Server Cards are structured metadata documents that servers expose through standardized mechanisms," with "the primary mechanism being a .well-known/mcp.json endpoint."

The server card JSON schema (v1.0) uses protocol version 2025-06-18 and requires the following fields:

{
  "$schema": "https://modelcontextprotocol.io/schemas/server-card/v1.0",
  "version": "1.0",
  "protocolVersion": "2025-06-18",
  "serverInfo": {
    "name": "My MCP Server",
    "version": "1.2.0",
    "description": "Description of what this server does",
    "homepage": "https://example.com"
  },
  "transport": {
    "type": "streamable-http",
    "url": "https://example.com/mcp"
  },
  "capabilities": {
    "tools": true,
    "resources": true,
    "prompts": false
  }
}

The key insight from SEP-1649 is that "discovery answers where to connect and what is available, while initialization handles how to communicate." Server cards enable IDE extensions and AI clients to auto-configure when pointed at a domain, eliminating the manual configuration step entirely.

SEP-1960: .well-known/mcp Manifest Endpoint

SEP-1960 takes a slightly different approach, proposing a discovery endpoint at /.well-known/mcp (note: not /.well-known/mcp/manifest.json as some early drafts suggested). This proposal follows RFC 8615 conventions used by OAuth 2.0 and OpenID Connect.

SEP-1960's required fields include mcp_version and an endpoints array, and it specifies mandatory security headers:

{
  "mcp_version": "2025-11-25",
  "endpoints": [
    {
      "url": "https://example.com/mcp",
      "transport": "streamable-http",
      "capabilities": ["tools", "resources"],
      "auth": {
        "type": "oauth2",
        "authorization_server": "https://example.com/.well-known/oauth-authorization-server"
      }
    }
  ]
}

The response must include security headers: Content-Type: application/json, X-Content-Type-Options: nosniff, Cache-Control with an appropriate TTL, and Access-Control-Allow-Origin for CORS. SEP-1960 also notes that servers operating in high-security environments should cryptographically sign responses.

Pro Tip: Both SEP-1649 and SEP-1960 are active proposals, not finalized specifications. Implementing both endpoints is a safe strategy since they serve complementary purposes: SEP-1649 provides rich server metadata while SEP-1960 focuses on endpoint enumeration and authentication discovery.

Comparison: SEP-1649 vs SEP-1960

Feature	SEP-1649 (Server Cards)	SEP-1960 (Manifest)
Path	/.well-known/mcp/server-card.json	/.well-known/mcp
Focus	Server metadata and capabilities	Endpoint enumeration and auth
Required fields	$schema, version, protocolVersion, serverInfo, transport, capabilities	mcp_version, endpoints
Auth discovery	Optional auth field	Built-in auth object per endpoint
RFC basis	Custom	RFC 8615
Multiple endpoints	Single transport definition	Array of endpoints
Security headers	Not specified	Required (CORS, CSP, Cache-Control)

How Do AI Clients Use Discovery Endpoints?

Understanding client-side discovery behavior is critical for implementing endpoints that work correctly. Different AI clients approach MCP server discovery in slightly different ways, but the general pattern is consistent.

The Discovery Flow

When a user adds an MCP server URL (for example, https://gsc.ekamoira.com) to their AI client, the following sequence typically occurs:

1. Well-known probe: The client sends a GET request to https://gsc.ekamoira.com/.well-known/mcp/server-card.json (and/or /.well-known/mcp)
2. Metadata parsing: If the endpoint returns valid JSON, the client extracts transport type, endpoint URL, capabilities, and authentication requirements
3. Auth negotiation: If an OAuth endpoint is specified, the client initiates the OAuth 2.1 flow (for details, see our guide on securing your MCP server with OAuth 2.1)
4. Session initialization: The client connects to the MCP endpoint using the discovered transport and begins the JSON-RPC handshake
5. Capability confirmation: During initialize, the client confirms capabilities match what was advertised in the server card

Client-Specific Behaviors

Claude Desktop and Claude Code initiated the MCP ecosystem and support server discovery natively. When you configure a server URL, Claude probes the well-known endpoint to determine transport type and capabilities before connecting.

ChatGPT adopted MCP in March 2025. In January 2026, Anthropic and OpenAI partnered to release the MCP Apps Extension, bringing standardized interactive UI capabilities to MCP clients including ChatGPT, Claude, Goose, and Visual Studio Code.

VS Code provides MCP support with dynamic context across all models. The development tools use discovery endpoints to populate server listings and allow developers to browse available tools before connecting.

Watch Out: If your discovery endpoint returns incorrect or incomplete metadata, clients may fail silently. The Stainless error handling guide documents that most MCP issues fall into four categories: configuration errors, JSON-RPC format problems, protocol version mismatches, and connection failures. A malformed discovery response creates the first category of issue.

How Do You Implement .well-known/mcp.json Step by Step?

This section provides working code examples for three popular frameworks. Each implementation serves both SEP-1649 and SEP-1960 endpoints, with proper security headers, CORS configuration, and error handling.

Express.js Implementation

import express from 'express';
import cors from 'cors';

const app = express();

// CORS configuration for browser-based MCP clients
app.use(cors({
  origin: '*',
  methods: ['GET', 'OPTIONS'],
  allowedHeaders: ['Content-Type', 'Authorization', 'Mcp-Session-Id'],
}));

// SEP-1649: Server Card
app.get('/.well-known/mcp/server-card.json', (_req, res) => {
  res.set({
    'Content-Type': 'application/json',
    'X-Content-Type-Options': 'nosniff',
    'Cache-Control': 'public, max-age=3600',
    'Access-Control-Allow-Origin': '*',
  });

  res.json({
    "$schema": "https://modelcontextprotocol.io/schemas/server-card/v1.0",
    "version": "1.0",
    "protocolVersion": "2025-06-18",
    "serverInfo": {
      "name": "My Analytics MCP Server",
      "version": "2.1.0",
      "description": "Provides search analytics and keyword data",
      "homepage": "https://example.com"
    },
    "transport": {
      "type": "streamable-http",
      "url": "https://example.com/mcp"
    },
    "capabilities": {
      "tools": true,
      "resources": true,
      "prompts": false
    }
  });
});

// SEP-1960: Discovery Manifest
app.get('/.well-known/mcp', (_req, res) => {
  res.set({
    'Content-Type': 'application/json',
    'X-Content-Type-Options': 'nosniff',
    'Cache-Control': 'public, max-age=3600',
    'Access-Control-Allow-Origin': '*',
  });

  res.json({
    "mcp_version": "2025-11-25",
    "endpoints": [
      {
        "url": "https://example.com/mcp",
        "transport": "streamable-http",
        "capabilities": ["tools", "resources"],
        "auth": {
          "type": "oauth2",
          "authorization_server":
            "https://example.com/.well-known/oauth-authorization-server"
        }
      }
    ]
  });
});

app.listen(3000, '127.0.0.1', () => {
  console.log('MCP server with discovery running on port 3000');
});

Next.js API Route Implementation

// app/.well-known/mcp/server-card.json/route.ts
import { NextResponse } from 'next/server';

export async function GET() {
  return NextResponse.json(
    {
      "$schema": "https://modelcontextprotocol.io/schemas/server-card/v1.0",
      "version": "1.0",
      "protocolVersion": "2025-06-18",
      "serverInfo": {
        "name": "My Analytics MCP Server",
        "version": "2.1.0",
        "description": "Search analytics and keyword tracking tools",
        "homepage": "https://example.com"
      },
      "transport": {
        "type": "streamable-http",
        "url": "https://example.com/mcp"
      },
      "capabilities": {
        "tools": true,
        "resources": true,
        "prompts": false
      }
    },
    {
      headers: {
        'Content-Type': 'application/json',
        'X-Content-Type-Options': 'nosniff',
        'Cache-Control': 'public, max-age=3600',
        'Access-Control-Allow-Origin': '*',
      },
    }
  );
}

FastAPI Implementation

from fastapi import FastAPI
from fastapi.responses import JSONResponse
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI()

app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],
    allow_methods=["GET", "OPTIONS"],
    allow_headers=["Content-Type", "Authorization", "Mcp-Session-Id"],
)

@app.get("/.well-known/mcp/server-card.json")
async def server_card():
    return JSONResponse(
        content={
            "$schema": "https://modelcontextprotocol.io/schemas/server-card/v1.0",
            "version": "1.0",
            "protocolVersion": "2025-06-18",
            "serverInfo": {
                "name": "My Analytics MCP Server",
                "version": "2.1.0",
                "description": "Search analytics and keyword data",
                "homepage": "https://example.com",
            },
            "transport": {
                "type": "streamable-http",
                "url": "https://example.com/mcp",
            },
            "capabilities": {
                "tools": True,
                "resources": True,
                "prompts": False,
            },
        },
        headers={
            "X-Content-Type-Options": "nosniff",
            "Cache-Control": "public, max-age=3600",
            "Access-Control-Allow-Origin": "*",
        },
    )

@app.get("/.well-known/mcp")
async def mcp_manifest():
    return JSONResponse(
        content={
            "mcp_version": "2025-11-25",
            "endpoints": [
                {
                    "url": "https://example.com/mcp",
                    "transport": "streamable-http",
                    "capabilities": ["tools", "resources"],
                    "auth": {
                        "type": "oauth2",
                        "authorization_server":
                            "https://example.com/.well-known/oauth-authorization-server",
                    },
                }
            ],
        },
        headers={
            "X-Content-Type-Options": "nosniff",
            "Cache-Control": "public, max-age=3600",
            "Access-Control-Allow-Origin": "*",
        },
    )

Pro Tip: The official TypeScript SDK is published as two separate packages: @modelcontextprotocol/server and @modelcontextprotocol/client. Install the one matching your use case. The server package includes auth helpers and high-level server libraries for building MCP servers with discovery support.

What Does a Production Discovery Endpoint Look Like?

Ekamoira's GSC MCP server provides a real-world example of how server discovery works in production. The server exposes Google Search Console data -- keyword rankings, page performance, click-through rates -- to AI assistants through the Model Context Protocol. Here is what the production server card looks like.

Ekamoira GSC MCP Server Card

{
  "$schema": "https://modelcontextprotocol.io/schemas/server-card/v1.0",
  "version": "1.0",
  "protocolVersion": "2025-06-18",
  "serverInfo": {
    "name": "Ekamoira GSC MCP Server",
    "version": "1.4.0",
    "description": "Google Search Console data access for AI assistants. Provides keyword rankings, page performance metrics, click-through rates, and search analytics.",
    "homepage": "https://www.ekamoira.com"
  },
  "transport": {
    "type": "streamable-http",
    "url": "https://gsc.ekamoira.com/mcp"
  },
  "capabilities": {
    "tools": true,
    "resources": true,
    "prompts": false
  },
  "tools": [
    {
      "name": "get_top_pages",
      "description": "Get top-performing pages by impressions, clicks, or CTR"
    },
    {
      "name": "get_top_keywords",
      "description": "Get top keywords with search volume and position data"
    },
    {
      "name": "get_keyword_for_page",
      "description": "Get all keywords ranking for a specific page URL"
    },
    {
      "name": "get_search_analytics",
      "description": "Full search analytics with dimension and filter support"
    }
  ]
}

This server card tells any AI client exactly what it needs to know: the server provides four tools for Google Search Console data, uses streamable HTTP transport at https://gsc.ekamoira.com/mcp, and supports tools and resources but not prompts. A client can parse this and present the user with a clear list of available capabilities before initiating a connection.

For a comprehensive comparison of Google Search Console MCP servers and how they differ in tool availability, authentication, and deployment complexity, see our GSC MCP server comparison guide.

Production Architecture Notes

The Ekamoira GSC MCP server runs behind an HTTPS reverse proxy with TLS termination. According to the MCP Transports specification, the server must provide a single HTTP endpoint supporting both POST and GET methods, and servers must validate the Origin header on all incoming connections to prevent DNS rebinding attacks. For local development, the specification recommends binding to localhost (127.0.0.1).

The production deployment uses the following security configuration:

// Validate Origin header per MCP Transports spec
function validateOrigin(req: Request): boolean {
  const origin = req.headers.get('origin');
  const allowedOrigins = [
    'https://claude.ai',
    'https://chatgpt.com',
    'https://www.ekamoira.com',
  ];
  return !origin || allowedOrigins.includes(origin);
}

For more on production deployment patterns including cloud hosting on Vercel, Cloudflare Workers, and AWS, see our guide on deploying your MCP server to production.

Key Finding: The MCP Transports specification requires that "servers MUST validate the Origin header on all incoming connections to prevent DNS rebinding attacks" -- MCP Specification, March 2025

How Do You Test and Debug Your Discovery Endpoint?

Testing your discovery endpoint before deploying to production prevents silent failures in AI clients. The MCP ecosystem provides several debugging tools, and standard HTTP tools like curl work well for basic validation.

curl Validation Commands

Start with basic endpoint reachability:

# Test SEP-1649 server card
curl -s https://your-server.com/.well-known/mcp/server-card.json | jq .

# Test SEP-1960 manifest
curl -s https://your-server.com/.well-known/mcp | jq .

# Verify security headers
curl -I https://your-server.com/.well-known/mcp/server-card.json
# Expected headers:
#   Content-Type: application/json
#   X-Content-Type-Options: nosniff
#   Cache-Control: public, max-age=3600
#   Access-Control-Allow-Origin: *

# Test CORS preflight
curl -X OPTIONS \
  -H "Origin: https://claude.ai" \
  -H "Access-Control-Request-Method: GET" \
  -I https://your-server.com/.well-known/mcp/server-card.json

MCP Inspector

The MCP Inspector is the official visual testing tool for MCP servers. It consists of two components: a React-based web UI (MCPI) and a Node.js proxy server (MCPP). The Inspector supports real-time message inspection, tool testing, and resource browsing, and binds to localhost only by default for security.

# Install and run MCP Inspector
npx @modelcontextprotocol/inspector

# The Inspector will open a web UI where you can:
# 1. Enter your server URL
# 2. View the discovery response
# 3. Test individual tools
# 4. Inspect JSON-RPC message flow

JSON Schema Validation

Validate your server card against the schema to catch structural issues:

# Save your server card locally
curl -s https://your-server.com/.well-known/mcp/server-card.json > server-card.json

# Validate required fields exist
jq 'has("$schema", "version", "protocolVersion", "serverInfo", "transport", "capabilities")' server-card.json
# Expected output: true

# Validate transport URL is HTTPS
jq '.transport.url | startswith("https://")' server-card.json
# Expected output: true

Pro Tip: The November 2025 MCP specification established JSON Schema 2020-12 as the default dialect. Make sure your $schema field references are compatible with this version.

Automated Health Check Script

For continuous monitoring in production, implement a health check that validates both endpoints:

#!/bin/bash
# mcp-discovery-healthcheck.sh

SERVER_URL="${1:-https://your-server.com}"

echo "Testing MCP discovery endpoints for $SERVER_URL"

# Test server card
SC_STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
  "$SERVER_URL/.well-known/mcp/server-card.json")

if [ "$SC_STATUS" = "200" ]; then
  echo "  server-card.json: OK ($SC_STATUS)"
else
  echo "  server-card.json: FAIL ($SC_STATUS)"
  exit 1
fi

# Test manifest
MF_STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
  "$SERVER_URL/.well-known/mcp")

if [ "$MF_STATUS" = "200" ]; then
  echo "  manifest: OK ($MF_STATUS)"
else
  echo "  manifest: FAIL ($MF_STATUS)"
  exit 1
fi

# Validate JSON structure
SC_VALID=$(curl -s "$SERVER_URL/.well-known/mcp/server-card.json" | \
  jq 'has("serverInfo", "transport", "capabilities")')

if [ "$SC_VALID" = "true" ]; then
  echo "  Schema validation: PASSED"
else
  echo "  Schema validation: FAILED - missing required fields"
  exit 1
fi

echo "All discovery endpoints healthy."

If you run into issues during testing, our MCP server troubleshooting guide covers the most common connection failures and their solutions.

What Are the Most Common Discovery Endpoint Pitfalls?

Based on real-world implementation experience and documented issues across the MCP ecosystem, these are the most frequent problems developers encounter when implementing discovery endpoints.

Pitfall 1: Missing or Incorrect CORS Headers

Browser-based MCP clients fail with CORS errors when calling servers from different origins. The discovery endpoint must return proper Access-Control-Allow-Origin headers, and the preflight (OPTIONS) request must be handled correctly.

Fix: Ensure your CORS configuration includes the required headers for MCP:

// Required CORS headers for MCP discovery
const corsHeaders = {
  'Access-Control-Allow-Origin': '*',
  'Access-Control-Allow-Methods': 'GET, OPTIONS',
  'Access-Control-Allow-Headers':
    'Content-Type, Authorization, Mcp-Session-Id',
};

Pitfall 2: Non-HTTPS Transport URLs

The MCP Transports specification requires HTTPS for all HTTP-based communication in production. Servers advertising http:// transport URLs in their server cards will be rejected by security-conscious clients.

Fix: Always use HTTPS URLs in your transport configuration. For local development, http://localhost is acceptable, but production endpoints must use valid TLS certificates.

Pitfall 3: stdout Pollution in JSON-RPC

The Stainless debugging guide documents that "the MCP protocol relies strictly on stdout for all JSON-RPC messages, and any non-protocol output sent to stdout will corrupt the protocol stream." This applies to servers using stdio transport, but developers who test discovery endpoints alongside their main MCP server sometimes introduce logging statements that pollute stdout.

Fix: Redirect all logging and debug output to stderr. Never use console.log for diagnostics in MCP server code -- use console.error or a dedicated logging library configured for stderr output.

Pitfall 4: Protocol Version Mismatches

Your server card's protocolVersion must match what your server actually implements during the initialize handshake. If your discovery endpoint advertises 2025-06-18 but your server negotiates 2025-03-26, clients may exhibit unexpected behavior.

Fix: Keep protocolVersion in sync between your discovery endpoint and your server's initialize response. Update both when upgrading your MCP SDK version.

Pitfall 5: Missing Cache-Control Headers

Discovery endpoints without proper Cache-Control headers cause excessive polling. AI clients may re-fetch the server card on every interaction, creating unnecessary load.

Fix: Set Cache-Control: public, max-age=3600 (1 hour) for stable server cards. For servers that change capabilities frequently, use a shorter TTL with must-revalidate.

Watch Out: Many MCP clients fail silently when discovery endpoints return errors. According to the WorkOS MCP security guide (August 2025), authentication was one of the most challenging aspects of implementing MCP servers, and clients often do not surface discovery failures to users. Always test with multiple clients to verify behavior.

Common Error Reference Table

Error	Symptom	Cause	Fix
404 on well-known path	Client shows "server not found"	Framework routing does not handle dot-prefixed paths	Add explicit route for /.well-known/mcp/*
CORS preflight failure	Browser console shows blocked request	Missing OPTIONS handler or incorrect headers	Add CORS middleware with Mcp-Session-Id in allowed headers
Invalid JSON	Client silently drops server	Trailing commas, unquoted keys, BOM character	Validate output with jq before deploying
Protocol version mismatch	Connection established but tools not visible	Server card advertises different version than server	Synchronize protocolVersion fields
Mixed content error	HTTPS page blocks HTTP MCP call	Transport URL uses http:// instead of https://	Use HTTPS with valid TLS certificate

What Should Your Production Readiness Checklist Include?

Before shipping your MCP server with discovery endpoints, verify every item on this checklist. Each item addresses a real failure mode documented across the MCP ecosystem.

Discovery Endpoint Checklist

• /.well-known/mcp/server-card.json returns valid JSON with all required fields ($schema, version, protocolVersion, serverInfo, transport, capabilities)
• /.well-known/mcp returns valid manifest with mcp_version and endpoints array
• HTTPS enforced on all transport URLs (per MCP Transports specification)
• Security headers present: Content-Type, X-Content-Type-Options: nosniff, Cache-Control, Access-Control-Allow-Origin
• CORS preflight handled for browser-based clients (OPTIONS method returns correct headers)
• Origin validation implemented on the main MCP endpoint to prevent DNS rebinding attacks
• protocolVersion synchronized between server card and server's initialize response
• JSON validated with jq or equivalent (no trailing commas, no BOM, proper encoding)
• OAuth discovery configured if authentication is required (.well-known/oauth-authorization-server)
• Rate limiting applied to discovery endpoints (prevent abuse while allowing client polling)
• Health check script running in CI/CD pipeline
• Tested with MCP Inspector for end-to-end tool visibility
• Tested with at least two AI clients (Claude Desktop + one other)
• Monitoring and alerting configured for 5xx errors on well-known paths

TL;DR

• Implement both /.well-known/mcp/server-card.json (SEP-1649) and /.well-known/mcp (SEP-1960)
• Always use HTTPS with valid TLS certificates for production transport URLs
• Include CORS headers, X-Content-Type-Options: nosniff, and Cache-Control
• Validate Origin headers on your main MCP endpoint
• Synchronize protocolVersion between discovery and server initialization
• Test with MCP Inspector and multiple AI clients before deploying

Frequently Asked Questions

What is .well-known/mcp.json and why do I need it?

The .well-known/mcp.json path (or more precisely, /.well-known/mcp/server-card.json per SEP-1649) is a standardized HTTP endpoint that your MCP server exposes to advertise its capabilities, transport configuration, and available tools to AI clients. Without it, every user must manually configure their AI assistant with your server's URL, transport type, and authentication details. Implementing discovery eliminates this friction and enables auto-configuration.

Is .well-known/mcp.json part of the official MCP specification?

As of February 2026, server discovery via well-known endpoints is defined in two active specification enhancement proposals: SEP-1649 (server cards at /.well-known/mcp/server-card.json) and SEP-1960 (manifest at /.well-known/mcp). These proposals have broad community support and are being actively implemented by major MCP clients, but they are not yet merged into the core specification.

Do I need to implement both SEP-1649 and SEP-1960?

Implementing both is recommended but not strictly required. SEP-1649 provides richer server metadata (description, homepage, tool listings), while SEP-1960 focuses on endpoint enumeration and authentication discovery. Major AI clients are converging on supporting both, so implementing both endpoints future-proofs your server.

What happens if a client does not support discovery?

If an AI client does not support well-known discovery, it will simply skip the probe and require manual configuration. Your MCP server continues to function normally through direct connection. Discovery is additive -- it improves the setup experience without breaking anything.

Can I use .well-known discovery with stdio transport?

Server discovery via well-known endpoints is designed for HTTP-based MCP servers (streamable HTTP transport). Stdio-based servers run as local processes and do not expose HTTP endpoints, so well-known discovery does not apply to them. Stdio servers are discovered through configuration files (like claude_desktop_config.json) instead.

How often do AI clients poll the discovery endpoint?

Polling frequency varies by client, but respecting the Cache-Control header is standard behavior. Setting Cache-Control: public, max-age=3600 tells clients to cache the response for one hour. Most clients will fetch the server card once during initial setup and then periodically refresh based on the cache TTL.

What security risks does the discovery endpoint introduce?

The discovery endpoint itself is read-only and exposes only metadata, so the direct risk is low. However, exposing your server's internal URL structure and capabilities provides information to potential attackers. Mitigate this by requiring HTTPS, setting X-Content-Type-Options: nosniff, implementing rate limiting, and avoiding exposure of internal implementation details in tool descriptions.

How do I handle versioning when my server capabilities change?

Update your server card's version field and tool listings when capabilities change. If you add or remove tools, increment the version number so clients know to refresh their cached state. For breaking changes to the transport or protocol version, update the protocolVersion field and test with all supported clients before deploying.

Can I serve the discovery endpoint from a CDN?

Yes. Since discovery endpoints return static JSON, they are excellent candidates for CDN caching. Serve them from your CDN with appropriate Cache-Control headers. Make sure the CDN passes through the required security headers (X-Content-Type-Options, Access-Control-Allow-Origin) and does not strip them.

How do I test discovery with Claude Desktop specifically?

Add your server URL to Claude Desktop's MCP server configuration. Claude will probe the well-known endpoint automatically. Check Claude Desktop's developer console or logs for discovery-related messages. If Claude cannot parse your server card, it will fall back to requiring manual transport configuration.

Sources

1. GitHub modelcontextprotocol (2025). "SEP-1649: MCP Server Cards - HTTP Server Discovery via .well-known." https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1649
2. GitHub modelcontextprotocol (2025). "SEP-1960: .well-known/mcp Discovery Endpoint for Server Metadata." https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1960
3. Model Context Protocol (2025). "Transports - Model Context Protocol Specification." https://modelcontextprotocol.io/specification/2025-03-26/basic/transports
4. Anthropic (2026). "Donating the Model Context Protocol and Establishing the Agentic AI Foundation." https://www.anthropic.com/news/donating-the-model-context-protocol-and-establishing-of-the-agentic-ai-foundation
5. Model Context Protocol Blog (2026). "MCP Apps - Bringing UI Capabilities To MCP Clients." https://blog.modelcontextprotocol.io/posts/2026-01-26-mcp-apps/
6. Model Context Protocol (2025). "MCP November 2025 Specification Release - Changelog." https://modelcontextprotocol.io/specification/2025-11-25/changelog
7. WorkOS (2025). "From Pain Points to Solutions: How VSCode Solved MCP's Biggest Developer Challenges." https://workos.com/blog/mcp-night-2-0-demo-recap-vscode-harald-kirschner
8. WorkOS (2025). "The Complete Guide to MCP Security: How to Secure MCP Servers and Clients." https://workos.com/blog/mcp-security-risks-best-practices
9. AI Native Dev (2025). "Teaching MCP Servers New Tricks: Challenges in Tool Discovery." https://ainativedev.io/news/teaching-mcp-servers-new-tricks
10. MCPcat (2025). "CORS Policies for Web-Based MCP Servers - Security Guide." https://mcpcat.io/guides/implementing-cors-policies-web-based-mcp-servers/
11. Stainless (2025). "Error Handling And Debugging MCP Servers." https://www.stainless.com/mcp/error-handling-and-debugging-mcp-servers
12. GitHub modelcontextprotocol (2025). "MCP Inspector - Visual Testing Tool for MCP Servers." https://github.com/modelcontextprotocol/inspector
13. GitHub modelcontextprotocol (2025). "Official TypeScript SDK for Model Context Protocol." https://github.com/modelcontextprotocol/typescript-sdk

---

Ready to Track Your AI Visibility?

Ekamoira helps you monitor how AI assistants like ChatGPT, Claude, and Perplexity cite your brand. Track your presence across AI search results, optimize for AI visibility, and connect your data through MCP. Start Free