Skip to content

Add mcp.json discovery protocol #1054

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Draft
wants to merge 4 commits into
base: main
Choose a base branch
from
Draft

Add mcp.json discovery protocol #1054

wants to merge 4 commits into from
+297 −5

Conversation

ksinder
Copy link

@ksinder ksinder commented Jul 24, 2025

Introduces server discovery mechanism for MCP via /.well-known/mcp.json, enabling automatic detection of MCP servers on domains.

Motivation and Context

The MCP ecosystem needs a standardized way for remote MCP servers to advertise their presence and capabilities. This PR introduces a discovery mechanism that enables:

  • Automatic server detection: Clients can discover MCP servers by checking /.well-known/mcp.json on any domain
  • Seamless user experience: When users provide URLs (e.g., notion.so/doc/123), clients can automatically detect and suggest connecting to the appropriate MCP server
  • Standardized metadata: Servers advertise their name, logo, supported transports, and capabilities in a consistent format

Example discovery file (GET https://www.notion.so/.well-known/mcp.json):

{
  "name": "Notion",
  "description": "Connect your Notion workspace to search, update, and trigger workflows across tools.",
  "icon": "https://www.notion.so/images/notion-logo-block-main.svg",
  "endpoint": "https://mcp.notion.com/mcp"
}

Implementation Details

  • Added ServerDiscoveryMetadata interface to TypeScript schema
  • Created comprehensive specification at /specification/draft/server/discovery
  • Added user-facing documentation at /docs/concepts/discovery
  • Includes security requirements (HTTPS-only, CORS policies)
  • Specifies that endpoint field is required when web transports are available
  • Documents preference for streamable HTTP over SSE when both are available

How Has This Been Tested?

Breaking Changes

None - this is an additive feature that doesn't affect existing functionality.

Types of changes

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to change)
  • Documentation update

Checklist

  • I have read the MCP Documentation
  • My code follows the repository's style guidelines
  • New and existing tests pass locally
  • I have added appropriate error handling
  • I have added or updated documentation as needed

Additional context

This feature is based on discussions with teams at Cursor and Anthropic about improving MCP server discoverability. The well-known URI pattern follows RFC 8615 standards.

@nickcoai
Copy link
Contributor

Very interested in this, is there a corresponding SEP Issue for it to facilitate discussion?

@connor4312
Copy link
Contributor

connor4312 commented Jul 24, 2025 •
edited
Loading

Some previous discussion: https://github.com/orgs/modelcontextprotocol/discussions/84

I strongly suggest adopting/embedding the server.json spec we're working on in the registry repo, as it provides mechanisms for command and input customization and runtime specifications which are not covered here https://github.com/modelcontextprotocol/registry/tree/main/docs/server-json In fact usage of that sever.json spec on well-known is an explicit goal :)

@ksinder
Copy link
Author

ksinder commented Jul 24, 2025

Very interested in this, is there a corresponding SEP Issue for it to facilitate discussion?

Not yet, sorry mind catching me up on what SEP means? Would it just be something like this? https://github.com/orgs/modelcontextprotocol/discussions/84

strongly suggest adopting/embedding the server.json spec we're working on in the registry repo

Ooh, thanks for letting me know! Will take a look, definitely happy to unify the proposals if it makes sense 👍

@nickcoai
Copy link
Contributor

Very interested in this, is there a corresponding SEP Issue for it to facilitate discussion?

Not yet, sorry mind catching me up on what SEP means? Would it just be something like this? https://github.com/orgs/modelcontextprotocol/discussions/84

strongly suggest adopting/embedding the server.json spec we're working on in the registry repo

Ooh, thanks for letting me know! Will take a look, definitely happy to unify the proposals if it makes sense 👍

Yep! full details here: https://modelcontextprotocol.io/community/sep-guidelines

But we've gained a way to decide on these things :)

@tadasant
Copy link
Member

tadasant commented Jul 25, 2025 •
edited
Loading

Some previous discussion: https://github.com/orgs/modelcontextprotocol/discussions/84

I strongly suggest adopting/embedding the server.json spec we're working on in the registry repo, as it provides mechanisms for command and input customization and runtime specifications which are not covered here https://github.com/modelcontextprotocol/registry/tree/main/docs/server-json In fact usage of that sever.json spec on well-known is an explicit goal :)

+1 on this!

You should feel free to evolve that shape to include the features important to the .well-known use case. We'd all benefit from aligning on this static representation of servers we can unify across all the relevant use cases.

I think the only thing missing from the current iteration of server.json for you is icon. I haven't proposed adding it there yet as that shape is under discussion here - probably worth aligning that SEP with this + the server.json.

Couple small thoughts from earlier conversations on .well-known:

  1. mcp.json is a term that most people associate with configuring MCP servers on a local machine. I would highly suggest using server.json for this purpose instead; no ongoing collisions there and alignment with how the Registry is thinking about it
  2. I think there'd be a lot of merit to considering declaring a .well-known directory instead of a single file, i.e. /.well-known/mcp/server.json. For one, it keeps the naming of the file consistent and simple, while still providing the mcp context in the directory name (anyone looking at that URL will know what it means in any context). Further, I expect there may be other non-server uses to expand into (MCP clients? auth-related needed? security-related notices? Although we could squeeze it all in one mcp.json-esque file in theory, it's probably cleaner to separate out those concerns and just reserve a directory)
  3. One point to address is how a domain can declare several MCP servers. e.g. do we need this to be /.well-known/mcp/servers.json, where servers.json is an array of server.json object? Maybe both servers.json and server.json are valid?
  4. Small detail, but I think we should require that the MCP endpoint be aligned with the domain where the .well-known file is hosted. This way we don't have the possibility of many different domains all trying to provide the reference data for a single server.

Thank you for taking this on! Very much needed.

Edit: As a follow-on to point 2, the registry working group is about to propose another .well-known endpoint for the purpose of storing HTTP-based domain verification. Something like /.well-known/mcp/domain-verify. More reason to use the subdirectory approach. cc @toby

@tadasant tadasant mentioned this pull request Jul 29, 2025
Open
@dsp-ant
Copy link
Member

dsp-ant commented Aug 4, 2025

Please change the label from SEP-requested to SEP once a SEP is available.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers
No reviews
Assignees
No one assigned
Labels
SEP-requested
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
5 participants
@ksinder @nickcoai @connor4312 @tadasant @dsp-ant