Model Context Protocol
.well-known/mcp directory
#84
Replies: 11 comments 5 replies
-
|
Possibly related: modelcontextprotocol/specification#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.
-
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