Metadata Discovery

Modern applications need a way for clients to discover how to authenticate and interact with servers securely. In the Model Context Protocol (MCP), this is achieved through standardized metadata endpoints that describe both the resource server (your MCP server) and its associated authorization server.
Without this discovery mechanism, clients would have to guess or hardcode authentication details, leading to brittle integrations and poor user experience.

Why does this matter?

  • Seamless integration: Clients (like VS Code, web apps, or other tools) can automatically discover how to authenticate and what endpoints to use.
  • Security: By following standards, you reduce the risk of misconfiguration and security vulnerabilities.
  • Interoperability: Any MCP-compliant client can connect to any MCP server, regardless of who built it.

The relationship: Auth Server vs. Resource Server

  • Resource Server: Your MCP server, which hosts protected resources and APIs.
  • Authorization Server: Issues access tokens and handles user authentication. It may be a separate service or co-located with the resource server.
Clients first discover the resource server’s metadata, which points them to the authorization server’s metadata. This chain of discovery is what enables secure, standards-based authentication.
πŸ“œ See the MCP Authorization Spec for details on discovery and metadata.

Example: Metadata Discovery Flow

Authorization ServerMCP ServerClientAuthorization ServerMCP ServerClientGET /.well-known/oauth-protected-resourceResource metadata (includes authorization_servers)GET /.well-known/oauth-authorization-serverAuthorization server metadataPOST /oauth/register (dynamic client registration)Client credentials (client_id, client_secret)Redirect to /oauth/authorize (with client_id)Authorization codePOST /oauth/token (exchange code for token)Access tokenAuthenticated request with tokenProtected resource

Realistic Example

// Discover resource server metadata
const resourceMeta = await fetch(
	'https://our-mcp-server.example.com/.well-known/oauth-protected-resource',
).then((r) => r.json())

// Find the authorization server URL
const authServerUrl = resourceMeta.authorization_servers[0]

// Discover authorization server metadata
const authMeta = await fetch(authServerUrl).then((r) => r.json())

// Now the client knows how to authenticate!
By implementing these endpoints, you make your MCP server discoverable and easy to integrate with any standards-compliant client.
  • Always implement both resource and authorization server metadata endpoints.
  • Use CORS headers to allow cross-origin discovery.
  • Validate and document your endpoints for client developers.
Edit on GitHubStart Learning