Discovery XML Specification - Complete Reference Guide

Overview

The discovery.xml file is a standardized format for describing MCP (Model Context Protocol) servers. Similar to how sitemap.xml helps search engines discover web pages,discovery.xml helps AI agents and discovery platforms find and understand your MCP server.

Place this file at /.well-known/discovery.xml on your server to enable automatic discovery.

File Location

Your discovery.xml file must be accessible at:

URL Path

https://your-server.com/.well-known/discovery.xml

Basic Structure

Here's a minimal discovery.xml file:

discovery.xml

<?xml version="1.0" encoding="UTF-8"?>
<discovery version="1.0">
  <server>
    <name>My MCP Server</name>
    <url>https://my-server.com</url>
  </server>
  
  <design>
    <logo>https://my-server.com/logo.png</logo>
  </design>
  
  <seo>
    <shortDescription>A powerful MCP server for...</shortDescription>
    <categories>
      <category>Developer Tools</category>
    </categories>
    <keywords>
      <keyword>mcp</keyword>
      <keyword>ai</keyword>
    </keywords>
  </seo>
  
  <engines>
    <allowAll>false</allowAll>
    <allowed>
      <engine>
        <id>melven.ai</id>
        <permissions>
          <displayImages>true</displayImages>
          <displayDesign>true</displayDesign>
          <cacheData>true</cacheData>
          <showInSearch>true</showInSearch>
        </permissions>
      </engine>
    </allowed>
  </engines>
  
  <legal>
    <noIllegalContent>true</noIllegalContent>
    <noMaliciousActivity>true</noMaliciousActivity>
    <accurateInformation>true</accurateInformation>
    <ownershipConfirmed>true</ownershipConfirmed>
    <termsAccepted>true</termsAccepted>
    <confirmedAt>2024-01-01T00:00:00.000Z</confirmedAt>
  </legal>
</discovery>

Server Section

The <server> section contains basic information about your MCP server:

Element	Required	Description
`name`	Required	The display name of your server
`url`	Required	The base URL of your server
`author`	Optional	Author information (name, url, email)
`version`	Optional	Server version (e.g., "1.0.0")
`license`	Optional	License type (e.g., "MIT")
`repository`	Optional	Source code repository URL
`documentation`	Optional	Documentation URL
`support`	Optional	Support URL or contact

Full Server Example

<server>
  <name>Weather MCP Server</name>
  <url>https://weather-mcp.example.com</url>
  <author>
    <name>John Doe</name>
    <url>https://johndoe.dev</url>
    <email>john@example.com</email>
  </author>
  <version>2.1.0</version>
  <license>MIT</license>
  <repository>https://github.com/johndoe/weather-mcp</repository>
  <documentation>https://docs.weather-mcp.example.com</documentation>
  <support>https://github.com/johndoe/weather-mcp/issues</support>
</server>

Design Section

The <design> section lets you customize how your server appears on discovery platforms:

Element	Description
`logo`	URL to your server's logo (square, min 256x256px)
`cover`	URL to a cover/banner image (16:9 ratio recommended)
`primaryColor`	Primary brand color in hex (e.g., #3B82F6)
`secondaryColor`	Secondary brand color in hex
`backgroundColor`	Background color in hex
`font`	Preferred font family
`theme`	"light", "dark", or "auto"

SEO Section

The <seo> section helps AI agents and search engines understand your server:

Element	Required	Description
`shortDescription`	Required	Brief description (10-200 chars)
`longDescription`	Optional	Detailed description (up to 2000 chars)
`categories`	Required	List of categories (1-5)
`keywords`	Required	List of relevant keywords
`primaryCategory`	Optional	Main category for the server
`targetAudience`	Optional	Who the server is for
`useCases`	Optional	Example use cases

Tools Section

Document your MCP tools with rich metadata and custom design:

Tools Example

<tools>
  <tool>
    <name>get_weather</name>
    <displayName>Get Weather</displayName>
    <description>Fetch current weather data for any location</description>
    <category>Weather</category>
    <keywords>
      <keyword>weather</keyword>
      <keyword>forecast</keyword>
      <keyword>temperature</keyword>
    </keywords>
    <useCases>
      <useCase>Get current weather conditions</useCase>
      <useCase>Check temperature before travel</useCase>
    </useCases>
    <design>
      <icon>https://example.com/weather-icon.png</icon>
      <primaryColor>#0EA5E9</primaryColor>
    </design>
  </tool>
</tools>

Engines Section

Control which discovery engines can index your server:

Engines Example

<engines>
  <!-- Allow all engines -->
  <allowAll>true</allowAll>
  
  <!-- OR specify allowed engines -->
  <allowAll>false</allowAll>
  <allowed>
    <engine>
      <id>melven.ai</id>
      <permissions>
        <displayImages>true</displayImages>
        <displayDesign>true</displayDesign>
        <cacheData>true</cacheData>
        <showInSearch>true</showInSearch>
      </permissions>
    </engine>
  </allowed>
  
  <!-- Optionally deny specific engines -->
  <denied>
    <engine>some-engine.com</engine>
  </denied>
</engines>

Legal Section

Required legal confirmations for indexing:

Element	Description
`noIllegalContent`	Server does not host illegal content
`noMaliciousActivity`	Server does not engage in malicious activities
`accurateInformation`	All information provided is accurate
`ownershipConfirmed`	Submitter has authority to submit
`termsAccepted`	Terms of service accepted
`confirmedAt`	ISO timestamp of confirmation

All legal confirmations must be set to true for your server to be indexed.

Ready to Create Your Discovery File?

Use our interactive builder to generate a valid discovery.xml file for your MCP server.

Open Discovery Builder