MCP Server Discovery at Scale: Registry and Server Cards Explained

There are now over 10,000 active public MCP servers. The Python and TypeScript SDKs together pull in 97 million downloads every month. And according to Stacklok's 2026 State of MCP report, 41% of software organizations are already running MCP in some form of production.

Here's the uncomfortable question nobody asks out loud: how does an AI agent actually find the right server out of thousands - without a human hardcoding every single connection?

That's exactly what MCP Server Discovery solves. And if you're building anything serious on top of the Model Context Protocol, you need to understand how it works.

---

What Is MCP Server Discovery?

MCP Server Discovery refers to the automated mechanisms that let AI clients find, identify, and connect to MCP servers - without a human manually configuring every connection. (If MCP itself is new to you, start with what MCP is.)

Think of it as DNS for AI tools. Instead of you hardcoding server-A, server-B, and server-C into every agent config, discovery lets the client figure out what's available and how to connect - at runtime.

Static vs. Dynamic Discovery

There are two modes:

• Static (hardcoded config): You list every server URL explicitly in a config file. Simple, predictable, doesn't scale past a handful of servers.
• Dynamic (runtime discovery): The client probes well-known endpoints, queries a registry, and filters results semantically. Works at 10,000+ servers.

Dynamic discovery is where things get interesting - and where most teams are headed.

The Unbounded Discovery Problem

Here's the catch. MCP has no mandatory pre-registration. Any client can connect to any server, instantly. That's powerful, but it creates two real problems:

1. Visibility gaps - servers exist that no one knows about (sometimes called "Shadow MCP")
2. Security risks - unauthenticated servers are reachable by anyone

We'll dig into both later. First, let's walk through how discovery actually works end to end.

---

How Does MCP Server Discovery Work?

The short answer: a client probes a well-known URI, reads a structured JSON file (the Server Card), optionally queries a central registry, filters results with semantic search, then connects.

Here's the full step-by-step flow:

1. Well-Known URI Probe

The client sends a GET request to /.well-known/mcp/server-card.json on the target domain. This convention is borrowed directly from OAuth 2.0 / OpenID Connect (RFC 8615) - if you've worked with those protocols, the pattern will feel familiar. (For the implementation details, see our companion guide on Server Cards and .well-known discovery.)

2. Server Card Parsing

The client reads the returned JSON - the Server Card - to extract transport type, endpoint URL, supported protocol versions, auth requirements, and more. No guessing, no scraping docs. It's all machine-readable.

3. Registry Lookup (Optional)

If the client doesn't already know which server to target, it can query a registry API - for example, registry.modelcontextprotocol.io - to search for servers by capability, name, or category. This is how ecosystem-wide Model Context Protocol discovery works.

4. RAG-Based Filtering

With thousands of servers potentially matching a query, you can't dump all their descriptions into an LLM prompt. That causes context overflow and hallucinations. Instead, clients use Retrieval-Augmented Generation (RAG) - semantic vector search - to retrieve only the top-N most relevant servers for the user's current intent.

5. Runtime Connection

The client initiates an MCP session using the transport and auth details discovered in steps 1–4. No manual config needed.

6. Capability Confirmation

The server's initialize response confirms that its advertised capabilities actually match what was in the Server Card. This is the final handshake - and a useful sanity check.

---

What Is the MCP Registry?

The MCP Registry (registry.modelcontextprotocol.io) is the official, centralized metadata repository for publicly accessible MCP servers. Think of it as npm for MCP - but it stores metadata only. The actual artifacts (packages, binaries, Docker images) stay on npm, PyPI, Docker Hub, wherever they live.

It launched in preview on September 8, 2025, and as of mid-2026 it's still in preview status - meaning breaking changes are possible before general availability.

Who Runs It?

Governance matters here. The registry was donated to the Linux Foundation's Agentic AI Foundation (AAIF) - announced December 2025. The AAIF is co-founded by Anthropic, Block, and OpenAI, with Platinum members including Google, Microsoft, AWS, and Cloudflare.

That's a meaningful shift from single-vendor control to a neutral, community-owned model. The Registry Working Group includes contributors from PulseMCP, Stacklok, TeamSpark, and Ravenmail.

Community registries like mcp.so and Smithery also exist - they're independently run directories that complement the official registry. (Our guide to finding MCP servers walks through how to search and evaluate them.)

Scale

• ~9,652 latest server records
• ~28,959 total server/version records
• 7,000+ GitHub stars on the registry repo (as of June 2026)

Namespace Format

Servers use reverse DNS naming - e.g., io.github.username/server-name. This isn't arbitrary. The registry validates namespace ownership at publish time:

• To publish io.github.acme/my-server, you must authenticate as the acme GitHub org
• To publish io.acme.com/my-server, you must prove ownership of acme.com via DNS or HTTP challenge

This prevents namespace squatting and impersonation.

Key API Endpoints

# List servers
GET /v0/servers

# Get a specific server
GET /v0/servers/{id}

# Search by keyword
GET /v0/servers?search=filesystem

# Publish a server (requires auth)
POST /v0/publish

You can try it right now:

curl "https://registry.modelcontextprotocol.io/v0/servers?limit=10"

⚠️ Important Caveat

Registry admission requires only GitHub or domain ownership verification - there are no code reviews, no security audits, no vulnerability scans. Being listed in the registry does not mean a server is safe to use. We'll come back to this.

---

What Is an MCP Server Card?

An MCP Server Card is a structured JSON file that gives any MCP client everything it needs to connect to and use your server - transport type, endpoint URL, auth requirements, supported protocol versions, and more.

It lives at /.well-known/mcp/server-card.json on your server's domain. Think of it as a machine-readable business card for your MCP server. Always available, always up to date, no docs-reading required.

The format is defined by an active Specification Enhancement Proposal (SEP-2127, released April 2026) and is expected to be formalized in the upcoming MCP spec release candidate.

Required Fields

Field	Type	Description
$schema	string	Schema URI - must match the v1 schema URL
name	string	Reverse-DNS format, e.g. org.example/my-server
version	string	Semantic version, e.g. 1.2.0
description	string	Human-readable summary (1–100 chars)

Optional But Important Fields

Field	Type	Description
title	string	Display name for UIs
icons	array	Icon objects (src, mimeType, sizes, theme)
websiteUrl	string	Homepage or docs URL
repository	object	Source code metadata (source, url)
remotes	array	HTTP transport details (type, url, auth, headers)
_meta	object	Vendor-specific extensions (reverse-DNS namespaced)

The remotes Array - Where Transport Lives

The remotes array is where the real connection details live. Each entry specifies:

• type: sse or streamable-http
• url: endpoint URL (supports {variable} templates)
• supportedProtocolVersions: e.g. ["2025-06-18"]
• headers: auth headers, with isSecret: true for tokens and passwords

Mark every secret properly. If isSecret isn't set on an API key field, clients may log or expose it. Don't skip this.

Real Example: A Minimal MCP Server Card

Here's what a complete, working server-card.json looks like for a weather API server:

{
  "$schema": "https://static.modelcontextprotocol.io/schemas/v1/server-card.schema.json",
  "name": "io.github.acme/weather-server",
  "version": "1.0.0",
  "description": "Provides real-time weather data and forecasts via MCP.",
  "title": "ACME Weather Server",
  "websiteUrl": "https://weather.acme.io/docs",
  "remotes": [
    {
      "type": "streamable-http",
      "url": "https://weather.acme.io/mcp",
      "supportedProtocolVersions": ["2025-06-18"],
      "headers": [
        {
          "name": "Authorization",
          "value": "Bearer {api_key}",
          "isRequired": true,
          "isSecret": true,
          "description": "Your ACME API key",
          "placeholder": "acme_sk_..."
        }
      ],
      "variables": {
        "api_key": {
          "isRequired": true,
          "isSecret": true,
          "format": "string",
          "description": "API key from your ACME dashboard"
        }
      }
    }
  ]
}

A few things worth noting in this example:

• The name uses reverse-DNS format (io.github.acme/weather-server)
• streamable-http is the modern transport type (preferred over sse for new servers)
• The api_key variable is marked isSecret: true in both the header and the variables block
• supportedProtocolVersions pins to 2025-06-18 - the current stable MCP protocol version

(For a full breakdown of transports, see our MCP transport comparison.)

---

Server Card vs. Registry Entry - What's the Difference?

Both are part of MCP at scale discovery - but they serve different purposes and live in different places. Here's the breakdown:

	Server Card	Registry Entry
Location	Hosted on the server's own domain	Hosted on registry.modelcontextprotocol.io
Format	JSON file at /.well-known/mcp/server-card.json	API record in the registry database
Who controls it	The server owner	The registry (with owner's published data)
Discovery method	Well-known URI probe (direct)	Registry API query (centralized)
Auth verification	Self-declared	GitHub/DNS ownership verified
Best for	Direct client-to-server discovery	Ecosystem-wide search and indexing

The key insight: they're complementary, not competing. A well-run MCP server should have both.

The Server Card handles direct discovery - when a client already knows your domain and just needs connection details. The Registry Entry handles finding your server in the first place - when a client is searching across the whole ecosystem.

Skip the Server Card and direct discovery breaks. Skip the Registry and nobody outside your immediate circle will find you.

---

Challenges of MCP Discovery at Scale

Discovery at 10,000+ servers isn't just a technical problem - it's a security and governance problem too. Here are the real challenges we're seeing in 2026.

Context Overflow

You cannot dump 10,000 server descriptions into an LLM prompt. The context window fills up, costs spike, and the model starts hallucinating tool names and capabilities. RAG-based semantic filtering is the only practical solution - retrieve the top-N most relevant servers for the current intent, not all of them.

Shadow MCP Servers

Research in 2026 found over 1,467 MCP servers exposed to the public internet without proper security oversight - and many lack authentication entirely. Only 8.5% of MCP servers use OAuth; 53% rely on long-lived static secrets. These "shadow" servers are the MCP equivalent of shadow IT: deployed without central registration, running with default credentials, invisible to security teams. The OWASP MCP Top 10 (2025) lists Shadow MCP Servers as a critical risk category.

No Mandatory Pre-Registration

The unbounded discovery problem is structural: the protocol doesn't require servers to register anywhere before accepting connections. That's by design (it enables flexibility), but it means visibility gaps are baked in.

False Security of Registry Listings

This one trips up a lot of teams. Being listed in the MCP Registry does not mean a server is safe. There are no code audits at registration - only GitHub or DNS ownership verification. A malicious actor with a GitHub account can publish a server. Treat registry listings as a starting point for discovery, not as a security endorsement. (Our MCP server security checklist covers how to vet one properly.)

Authentication Complexity

Discovering servers that require OAuth 2.1 without standardized verification flows is still messy. The spec is evolving (the upcoming 2026 release candidate is expected to formalize OAuth 2.1 support), but for now, auth discovery is inconsistent across servers.

Fragmented Ecosystem

Multiple competing registries - the official one, mcp.so, Smithery - with no single source of truth yet. The official registry is working toward becoming that source, but the ecosystem is still consolidating.

---

Best Practices for MCP Server Discovery

Here's what we recommend for teams building or operating MCP servers in 2026.

1. Always publish a Server Card

Host /.well-known/mcp/server-card.json on your server's domain. It's the foundation of auto-discovery. Without it, clients that probe the well-known URI will fail silently.

2. Register in the official registry

Submit your server to registry.modelcontextprotocol.io for ecosystem-wide visibility. It's free, it's open source, and it's where clients will look first.

3. Use semantic versioning

The version field in your Server Card isn't decorative. Clients use it to detect breaking changes. Follow semver - bump the major version when you change transport types or remove capabilities.

4. Mark secrets properly

Set isSecret: true on every auth header, API key, and password in your remotes config. This tells clients to handle those values securely - not log them, not display them in plaintext UIs.

5. Use RAG-based filtering on the client side

If your agent works with more than a handful of servers, implement semantic search over server descriptions before building your tool list. Tools like LlamaIndex and LangChain have built-in vector store integrations that make this straightforward. (If you're curating that list by hand, our best MCP servers list is a useful starting set.)

6. Don't treat registry listing as a security guarantee

Always verify server identity independently. Check the repository URL, review the source code if it's open source, and audit the capabilities the server claims. The registry tells you a server exists - it doesn't tell you it's safe.

7. Keep your Server Card updated

Stale cards break auto-discovery. If you change your endpoint URL, transport type, or auth scheme, update the card immediately. Set up a CI check that validates your server-card.json against the schema on every deploy.

---

Key Takeaways

📌 Quick summary for busy readers

• MCP Server Discovery solves the "how does an AI find the right tool?" problem at scale - automatically, without human-hardcoded configs
• Two complementary mechanisms: Server Cards (self-hosted JSON at /.well-known/mcp/server-card.json) + Registry (centralized metadata at registry.modelcontextprotocol.io)
• The official MCP Registry has ~9,652 servers, is governed by the Linux Foundation's AAIF, and is still in preview as of mid-2026
• Server Cards follow a strict JSON schema with required fields: $schema, name, version, description
• RAG-based filtering is essential to prevent context overflow when working with thousands of servers
• Registry listing ≠ security - there are no code audits at registration; always verify independently
• Shadow MCP servers are a real and growing risk - over 1,467 exposed servers found in 2026 research

---

FAQ

What is MCP Server Discovery?

MCP Server Discovery is the set of automated mechanisms that allow AI clients to find, identify, and connect to MCP (Model Context Protocol) servers without manual configuration. It works through two main approaches: probing a well-known URI (/.well-known/mcp/server-card.json) directly on a server's domain, and querying a centralized registry like registry.modelcontextprotocol.io to search across the ecosystem. Dynamic discovery is essential at scale because there are now over 10,000 public MCP servers - far too many to hardcode manually.

What is an MCP Server Card and where is it hosted?

An MCP Server Card (mcp-server-card.json) is a structured JSON file that describes everything an MCP client needs to connect to a server: transport type, endpoint URL, supported protocol versions, authentication requirements, and more. It's hosted at /.well-known/mcp/server-card.json on the server's own domain - inspired by the same well-known URI convention used by OAuth 2.0 and OpenID Connect (RFC 8615). The format follows a strict JSON schema with required fields including $schema, name, version, and description.

What is the official MCP Registry and who runs it?

The official MCP Registry lives at registry.modelcontextprotocol.io and launched in preview on September 8, 2025. It's a centralized metadata repository - a "metaregistry" - for publicly accessible MCP servers. It stores metadata only; actual artifacts stay on npm, PyPI, Docker Hub, etc. Governance was transferred to the Linux Foundation's Agentic AI Foundation (AAIF) in December 2025, with co-founders including Anthropic, Block, and OpenAI, and Platinum members including Google, Microsoft, and AWS. As of mid-2026, the registry holds ~9,652 latest server records and is still in preview status.

What's the difference between a Server Card and a Registry entry?

A Server Card is self-hosted on your server's own domain and is discovered via a direct well-known URI probe. A Registry entry is hosted on registry.modelcontextprotocol.io and is discovered via a centralized API query. The Server Card is controlled entirely by the server owner; the registry entry is published by the owner but stored in the registry database. They're complementary: the Server Card handles direct client-to-server discovery, while the Registry handles ecosystem-wide search and indexing. A well-run MCP server should have both.

How do AI agents avoid context overflow when there are thousands of MCP servers?

The solution is RAG-based (Retrieval-Augmented Generation) semantic filtering. Instead of dumping all server descriptions into an LLM prompt - which would overflow the context window and cause hallucinations - the client uses vector embeddings and semantic search to retrieve only the top-N most relevant servers for the user's current intent. Tools like LlamaIndex and LangChain support this pattern natively. This is one of the most important architectural decisions for any MCP client working at scale.

Is a server listed in the MCP Registry automatically safe to use?

No. Registry admission requires only GitHub or domain ownership verification - there are no code reviews, security audits, or vulnerability scans. Being listed in the registry confirms that someone with a valid GitHub account or domain published the entry; it says nothing about the server's security posture or trustworthiness. Always verify server identity independently, review the source code if it's available, and audit the capabilities the server claims before connecting in production. The OWASP MCP Top 10 explicitly flags this as a risk.

---

Useful Sources

• MCP Registry Preview Launch - Official Blog Post
• MCP Registry GitHub Repository
• Linux Foundation - Agentic AI Foundation Announcement
• Stacklok - State of MCP in Software 2026 (PDF)
• MCP Server Card Working Group
• MCP Development Roadmap
• Trend Micro - Exposed MCP Servers Security Research