.well-known/mcp directory
#1147
Replies: 28 comments 30 replies
-
|
Possibly related: #69 |
Beta Was this translation helpful? Give feedback.
-
|
One additional use case for |
Beta Was this translation helpful? Give feedback.
-
|
Just a note: this would also be useful for prompt MCP's related to a site (not just tools provided by API), e.g. for a research paper site that allows comments and has a prompt MCP that serves something like: |
Beta Was this translation helpful? Give feedback.
-
|
I'll throw in another use case that might be enabled by this effort: signaling to clients what it "costs" to use the server's data or capabilities. For example, some options could be:
In the current web, Google Search rewards services and publishers with traffic, and then the "cost" layer comes after (payment walls, display ads, affiliate links). As fewer humans and more LLM workflows/agents are the ones doing the "web browsing" and interfacing with MCP servers instead of websites, the payment walls & ads-supported models break if everything has to be simply "free" (see: the ongoing web scraping battles / data-for-cash deals between large publishers and the big LLM providers). So figuring out how to signal "cost" enables a whole class of non-free (higher quality) service/data/info providers to be discovered in the MCP ecosystem. |
Beta Was this translation helpful? Give feedback.
-
|
FYI, someone else has come up with a proposal for "/llms.txt" (not in .well-known) at https://llmstxt.org/ |
Beta Was this translation helpful? Give feedback.
-
|
That one may eventually switch to |
Beta Was this translation helpful? Give feedback.
-
|
Some thoughts on pushing this discussion forward -- Do we need a whole .well-known directory, or is a single file enough?The starting proposal is:
The .well-known spec itself does allow for directories, but most of the registered URI's in .well-known are just single files rather than directories. I'm not against using a directory if we can foresee a need for it. But I would bias towards keeping this integration with .well-known as simple (and optional) as possible, while putting more fine-grained complexity in some place like the InitializeResult that a client would have access to on initiating the connection with the server. Who is the intended "user" of this file/directory?The obvious answer here might be "MCP Clients," but an alternative idea would be: "MCP server directory web crawlers". Drawing from the sitemap.xml analogy: search engines like Google collect and process sitemaps from websites completely separately from the experience of actually surfacing search results to users. They use sitemap.xml (when available -- it's optional) as a kind of guidebook for their crawlers. And after discovering the website's pages, they apply their own proprietary logic as to whether to crawl them, and ultimately whether to index and rank them in search results. Details like "page title", "page description", contents of a page are not in sitemap.xml -- the crawler needs to go and make a GET request to the URL as part of its crawling process to get that information. If we peg "MCP Clients" as the users of this .well-known file, then we have to rely on them to properly make discovery and comparison/ranking decisions on the fly. It would be the equivalent of Google trying to do its whole discover/crawl/index/rank process the moment somebody enters a query into google.com. And it would have other problems, e.g. the fact that relying on self-owned domains to facilitate the best MCP servers likely won't be practical for some time -- most MCP servers today are by third-party devs that would never get discovered by an MCP Client running a search for "find me MCP servers available on github.com" because all the GitHub MCP servers are made by third parties. If we peg "MCP server directory web crawlers" as the users instead, I could see it playing out like this:
If the idea of building .well-known for third party directories instead of MCP clients directly appeals, the first step could look like this (just iterating on the original proposal) -- Establish a file, /.well-known/mcp.json: {
"version": "1.0",
"servers": [
{
"name": "primary",
"description": "Main API server for example.com",
"endpoint": "https://mcp.example.com/v1",
}
]
}I'm omitting I think that alone could be enough for an initial version. It would accomplish:
|
Beta Was this translation helpful? Give feedback.
-
|
I like the idea of decentralized discovery of MCP services. Just with regard to this question:
I think both of the users (clients and server directories) you mentioned are totally valid. One argument in favor of using a directory here is that different files could actually cater to different audiences. However, that could also just be some big JSON file that contains everything needed for either. Not sure yet. |
Beta Was this translation helpful? Give feedback.
-
|
Catering to different audiences seems like something that should exist outside of this proposal entirely, i.e. this file should just give the client or crawler all the information and then let it decide how to use it. In other words, the single json doesn't appear to prescribe any specific value or usefulness to a given user, it just shares all the facts in a neutral way. |
Beta Was this translation helpful? Give feedback.
-
|
For the information above, definitely agreed. Not sure if there would be more audience-specific information we'd want to add in the future, though. Anyway, it seems like a small enough risk that a single file probably makes sense! |
Beta Was this translation helpful? Give feedback.
-
|
Has the team considered using something like OAuth device flow? I think that, along with a standard token auth option, would be pretty flexible. OAuth Device Authorization Grant (RFC 8628) Standard Token Based Auth [
{
"domains": ["*.airtable.com","airtable.com"],
"token": "my-secret-key"
},{
"domains": ["*.github.com","github.com"],
"token": "another-secret-key"
}
] |
Beta Was this translation helpful? Give feedback.
-
|
Have we thought of aligning with W3C discovery RFC? {
"@context":[
"https://www.w3.org/ns/did/v1",
"https://www.w3.org/2022/wot/discovery-did"
],
...
"service": [{
"id": "did:example:wotdiscoveryexample#td",
"type": "WotThing",
"serviceEndpoint":
"https://wot.example.com/.well-known/wot"
}]
...
} |
Beta Was this translation helpful? Give feedback.
-
|
From the MCP workshop at the AI Engineer conf in NYC. Oauth2 support (and an official registry) was also confirmed. 
|
Beta Was this translation helpful? Give feedback.
-
|
I have a question regarding "local" servers, such as the GitHub MCP server. Would it be possible to discover such MCP servers through a .well-known registration? While dynamic discovery of these servers could be useful, it raises security concerns about executing unknown code locally. However, the .well-known mechanism could serve as an approved list of MCP servers, whether they are remote or local. What are your thoughts on this? |
Beta Was this translation helpful? Give feedback.
-
|
Hey everyone! 👋 We've been following these discussions closely and have been thinking a lot about how we, as an agent framework (Mastra), would want to interact with MCP servers. We've also had some great conversations with folks in the community about this over the past week. We built a POC that explores what all this might look like from our perspective. The question we asked ourselves was: "As an agent framework, how could we build an abstraction that would simplify interacting with MCP servers for our users?" You can check out our exploration here: mastra/explorations/mcp-registry-client A few things we've learned:
Here's a quick example of what we have in the link above: const registry = new RegistryClient({
url: "https://example-tools.com/.well-known/mcp.json",
})
const directory = await registry.connect()
const allServers = await registry.listServers()
const stripeServer = await registry.getServerDefinition({ id: "stripe" })
// The server definition includes schemas that can be used to build UIs
const userInput = await userlandexample.buildServerUI(stripeServer.schemas)
const validConfig = stripeServer.parseConfig(userInput)We have some examples showing how this could be used in practice, including a TUI for discovering and configuring servers interactively. We wanted to share our perspective as a downstream MCP consumer and show how we're thinking about integrating once this all comes out. We're excited about these discussions and where MCP is heading! |
Beta Was this translation helpful? Give feedback.
-
|
@TylerBarnes I was also working on a very similar proposition based on the registry proposition in this discussion. There it is my proposition: MCP Discovery ProcessThis RFC defines how MCP Clients discover and connect to MCP Servers, inspired by the Web of Things (WoT) discovery standard. Core Entities
Discovery Flow
User Experience: mcpClient = McpClient(
discovery_channels = [
"my-server-url.com",
"my-registry-url.com"
]
)
print(mcpClient.list_tools()) # list tools for all server discovered in registry + tools in “my-server-url.com”** I am not sure if individual servers should go in there or we should do something like this mcpClient = McpClient(
discovery_channels = [
"my-registry-url.com"
]
servers: ["my-server-url.com", LocalServer()]
)
Security ConsiderationsAuthentication Reuse
Registry Filtering
Security Bootstrapping
sequenceDiagram
actor Host
participant Client as MCP Client
participant Registry as MCP Registry
participant PkgRegistry as Package Registry<br/>(npm/pypi)
participant LocalServer as Local MCP Server
participant RemoteServer as Remote MCP Server
%% Initial setup of discovery channels
Host->>Client: Configure discovery channels<br/>(Registry + Direct Server)
rect rgb(204, 255, 204)
Note right of Client: MCP Registry Discovery Channel Flow
Client->>Registry: GET .well-known/mcp.json
Registry-->>Client: Auth mechanism details
Client->>Host: Request auth input (OAuth/Bearer)
Host-->>Client: Provide credentials
Client->>Registry: Authenticate
Registry-->>Client: Auth success + token
Client->>Registry: List available MCP servers
Registry-->>Client: List of MCP servers
end
loop For each MCP server (direct or from registry)
alt Local MCP Server
rect rgb(204, 255, 204)
Note right of Client: Installation Bootstrapping
Client->>PkgRegistry: Download MCP server package
PkgRegistry-->>Client: Package contents
end
alt Installation successful
Client->>LocalServer: List resources
LocalServer-->>Client: Available resources
Client->>LocalServer: List prompts
LocalServer-->>Client: Available prompts
Client->>LocalServer: List tools
LocalServer-->>Client: Available tools
Note over Client: Store server capabilities
end
else Remote MCP Server
rect rgb(204, 255, 204)
Note right of Client: Security Bootstrapping
Client->>RemoteServer: GET .well-known/mcp.json
RemoteServer-->>Client: Auth mechanism details
Client->>Host: Request auth input (OAuth/Bearer)
Host-->>Client: Provide credentials
Client->>RemoteServer: Authenticate
RemoteServer-->>Client: Auth success + token
end
alt Authentication successful
Client->>RemoteServer: List resources
RemoteServer-->>Client: Available resources
Client->>RemoteServer: List prompts
RemoteServer-->>Client: Available prompts
Client->>RemoteServer: List tools
RemoteServer-->>Client: Available tools
Note over Client: Store server capabilities
end
end
end
|
Beta Was this translation helpful? Give feedback.
-
|
I like this idea, as it takes into account both enterprise and consumer scenarios. |
Beta Was this translation helpful? Give feedback.
-
|
https://github.com/orgs/modelcontextprotocol/discussions/159#discussioncomment-12624829 |
Beta Was this translation helpful? Give feedback.
-
|
I've been working on the MCP service discovery issue too since I learned about the protocol and created a POC for a DNS TXT pointer based system that checks for _mcp.domain.com for the tool server address. Here's my POC DNS record: And here where I'm writing up my ideas https://mcpintegrate.com with code here https://github.com/McSpidey/mcpi |
Beta Was this translation helpful? Give feedback.
-
|
This is what killed ChatGPT Plugins - be careful! |
Beta Was this translation helpful? Give feedback.
-
|
I am curious about this point. |
Beta Was this translation helpful? Give feedback.
-
|
Yes. Please elaborate. |
Beta Was this translation helpful? Give feedback.
-
|
One of the things about having complex hosted infrastructure is that it adds more steps and often requires auth / rate limiting at a certain scale. It may make sense to make more plugins / MCPs run as local processes on the users' computer than requiring external hosting. Would prefer having a mechanism that allows discovering services from public GitHub repos as well as hosted services. |
Beta Was this translation helpful? Give feedback.
-
|
The usecases for mcp sourcecode registry / search and mcp deployed instance announcement / search are very different: mcp sourcecode registry / search:
mcp deployed instance announcement / search:
So, as you see, you are just looking for a very different usecase. Please refer to the other thread. |
Beta Was this translation helpful? Give feedback.
-
I also believe that asking for adding the same mechanism on Git repos does not negatively impact the suggested discovery mechanism. This exact mechanism can work on a GitHub repo, by allowing people to look at: What needs to be expanded in the spec is how people can connect to locally runnable services/tools, which is orthogonal to the discovery mechanism itself. I also think that this thread is focussed on one of the solutions for the problem well discussed in /modelcontextprotocol/discussions/159. I definitely see value in the generic approach of that thread. |
Beta Was this translation helpful? Give feedback.
-
|
bro, look at my design |
Beta Was this translation helpful? Give feedback.
-
|
FYI：Agent2Agent Protocol (A2A) https://google.github.io/A2A/#/documentation?id=agent-card |
Beta Was this translation helpful? Give feedback.
-
|
FYI: Some of the .well-known discussion here has been intertwined with the discussion on the concept of a centralized registry, which is now under development here. FWIW: I think this notion of a decentralized .well-known mechanism for server discovery should still exist, and may become a more prominent server discovery entrypoint than the centralized registry in the long term, especially as remote servers grow in popularity. |
Beta Was this translation helpful? Give feedback.
-
|
This should exist. As a concrete example, at Shopify we've just shipped |
Beta Was this translation helpful? Give feedback.
-
|
Indeed it should exist, and good for shopify to take some lead here. |
Beta Was this translation helpful? Give feedback.
-
|
@igrigorik can we start a draft with some fields? or start a conversation in discord |
Beta Was this translation helpful? Give feedback.
-
|
I also brought a similar discussion to OpenAI on their community platform. I suggested using Happy to be included if a group around this topic forms :) |
Beta Was this translation helpful? Give feedback.
-
|
@igrigorik @dendik @arivero @johannespn I have consolidated some ideas in this document let me know if that makes sense and if you need edit permissions, feel free to share with others as well. |
Beta Was this translation helpful? Give feedback.
-
|
@electrocucaracha Thanks for starting this document! I added some comments. Their work might be interesting for MCP trust problems too. Maybe we should integrate their Verifiable Credential in the well known file, once it's vetted by this community & production ready |
Beta Was this translation helpful? Give feedback.
-
|
I want to bring this up #138 to the .well-known discussion. At Smithery, many of our servers have required GET parameters for users to configure the behavior of a server upon connection. Having a standard way to be able to be able to discover these GET paramaeters would be useful. We're already using an internal Happy to contribute this to the main specification. That way, there's a standard way of defining what GET parameters are possible. |
Beta Was this translation helpful? Give feedback.
-
|
Hi everyone, I've created a community working group channel for this topic on the MCP CWG Discord server. This will help us gather implementation experiences and validate proposals with the wider community, complementing the great discussion happening here. For anyone who isn't already acquainted with the CWG, here's the link to the README which explains more about the working groups and has a link to join the Discord server: https://github.com/modelcontextprotocol-community/working-groups |
Beta Was this translation helpful? Give feedback.
-
My UI looks something like this. It would be great if I could avoid the auth and type field, maybe even the name? Is there any way I could automatically figure these out? |
Beta Was this translation helpful? Give feedback.
-
|
This thread is really insightful!
I'm wondering if MCP Servers could be used as follows, in the future: For example, let's say you prompt ChatGPT something like:
and it'd do it's normal thing (surfaces information from the underlying LLM + a web search to pull promotions from local restaurants, etc.) but in addition to that, it also notices that the Dominos Pizza website references an MCP server in it's metadata (meta tag, .well-known, etc.) so it auto discovers it's functionality and notices that it exposes actions that actually place orders, leading to a response like this from ChatGPT:
Then ChatGPT continues the conversation with the user, helping them place an order (that is ultimately facilitated through the MCP Server abstraction.) Is this where things are going? If not, is there another direction that would provide this type of functionality? |
Beta Was this translation helpful? Give feedback.
-
|
That is exactly where things are going. You will be able to engage with a service 100% through your LLM (minus maybe the oauth flow to get logged in). |
Beta Was this translation helpful? Give feedback.
-
|
Really appreciate all the work here. Especially the example from Shopify, which helps show how this could scale in practice. To keep things moving, I’m curious what’s holding back adoption from the client side particularly from platforms like OpenAI or Claude. Are there technical constraints, policy questions, or just uncertainty around what to implement? Whatever structure we land on (single file, directory, auth details, cost metadata), having a minimal, shared version of .well-known/mcp.json that clients can start supporting would be a strong step forward. Happy to help draft or test a baseline format if that would be useful. |
Beta Was this translation helpful? Give feedback.
-
|
I'd like to bring up what I think is potentially a serious issue here - it depends on how exactly this is implemented, but if .well-known becomes a critical part of the MCP initialization process, this is a tight coupling to http as a transport. The current model of all important interactions being messages means that MCP could be adapted to literally any transport, any flavor of http, udp, satellite comms, literally anything. I'm not sure if this is meant as purely discovery and initialization still is message based, but I'd be careful to use this for anything other than establishing the MCP connect url. |
Beta Was this translation helpful? Give feedback.
-
|
But realistically, this would really only be useful for HTTP-based remote MCP servers, same as we do with auth and the PRM document at |
Beta Was this translation helpful? Give feedback.
-
|
Great discussion! I'd like to propose a complementary approach inspired by Apple's Smart App Banners. When Safari sees We could do similar for MCP: <meta name="mcp" content="server=https://blog.com/mcp/sse, transport=sse, capabilities=search;read;summarize">Key advantage: LLMs already fetch and parse HTML. When they scrape a page, they'd discover MCP servers with zero additional requests. The client could then prompt: "This site offers enhanced MCP integration - connect for real-time features?" Why both approaches make sense:
The philosophical distinction matters. Meta tags avoid this entirely - they're only parsed if present, no 404s, no extra requests. ChatGPT and Claude's web tools could be tweaked to identify and surface these tags immediately. Combined with Thoughts? |
Beta Was this translation helpful? Give feedback.
-
|
+1 for an open web+search based discovery. The current POC I'm working on is using a link rel alternative.
This allows the search tool from the LLM to discover the MCP endpoint given that the resource (web page which allows the manual way of doing it) matches the intend of the user - and can then offer to complete the action without having to go visit the website. The link rel as the benefit that it could potentially have multiple on the same page - located in the HTML where the action is for humans when they visit the site. Screenshot from POC for the chat experience: |
Beta Was this translation helpful? Give feedback.
-
|
@keepthebyte when you say POC, is this actually working for you or have u had to build our ur own chat experience to prove this out? I'm think Atlas (and other AI browsers) should immediately add this or the |
Beta Was this translation helpful? Give feedback.
-
Not OP but me and a colleague had a very similar idea two weeks ago and just recently stumbled upon this issue. We have a sample implementation of a LangChain agent that, through a mocked search tool, discovers and then utilizes the remote MCP server. The way the discovery process has been implemented is through a specific HTTP header which, if present, exposed the MCP server url. It works like the meta tag I guess. Indeed the approach can be refined but I strongly believe that discovering MCP servers opportunistically and without relying on a centralized registry can empower web-crawling LLM agents via new contextual-capabilities |
Beta Was this translation helpful? Give feedback.
-
|
FYI, there is an open SEP related to this idea. |
Beta Was this translation helpful? Give feedback.
-
@nicky-parsons the MCP is real - but needed to write own chat experience and tool calling sequence. Looks like right now - OpenAI choose to follow the 'AppStore' model with approved apps - and not an open web discovery. Not sure what Google is going to do. But I think there is a difference between an approved app from a brand - and a low friction action without having to 'configure' an app. |
Beta Was this translation helpful? Give feedback.
-
|
Folks, this discussion needs to reach somewhere because MCP server discovery is a well-needed feature for publicly hosted MCP servers protected by OAuth 2.1. MCP was designed to allow resource and tool discovery by LLMs i.e. the tools/list call would directly return the payload that I can include in the system prompt. With OAuth 2.1, I can't make this call myself at the time of agent initialization/configuration because OAuth 2.1 is meant to allow authorization on behalf of the invoker of my agent, which might not necessarily be me (I may be an agent developer for my org for others to use it). This means that my agent won't even know what functionality it can invoke at the time of initialization. I can't fill the system prompt. Having a .well-known URI solves this problem, if the returned document contains (and it should contain) the resource and tool definitions of the MCP server, I can just include that in my agent's system prompt without the need to initiate the OAuth2.1 flow. |
Beta Was this translation helpful? Give feedback.
-
I think having a Oauth2.1 and .well-known serves different purpose. It should be implemented in both perspective than just saying that now we know what MCP server could do so that I'm aware and now I dont need any kind of OAuth mechanism for this. |
Beta Was this translation helpful? Give feedback.
-
|
Reiterating on this point: #1147 (comment) Could these .well-known configuration files be utilized by enterprises to discover local MCP servers or servers hosted in remote clouds? I’m relatively new to this topic and might be missing some details. If anyone has experience with a similar use case, I’d really appreciate it if you could share your insights! |
Beta Was this translation helpful? Give feedback.
-
|
A small summary of the possibilities mentioned in this thread:
It looks like |
Beta Was this translation helpful? Give feedback.
and others
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
-
As we think more about supporting remote MCP servers, there's been some discussion around using a Well-known URI (RFC 8615) for server discovery. This could enable automatic discovery and verification of MCP servers, similar to how
sitemap.xmlworks for search engines.The idea would be to establish a directory,
/.well-known/mcp/, allowing for future extensibility. We could then include aservers.jsonfile that might look something like:{ "version": "1.0", "servers": [ { "name": "primary", "description": "Main API server for example.com", "endpoint": "https://mcp.example.com/v1", "capabilities": ["resources", "tools"] } ] }This is just a strawman to get the discussion started—there are likely many other approaches worth considering.
Potential Benefits
Areas for Discussion
Directory Structure
Security
Implementation
Open to all feedback what this could look like and whether it would be valuable for the MCP ecosystem!
Scope
Beta Was this translation helpful? Give feedback.
All reactions