I never quite understand why /mcp endpoint is needed.
You can still keep using Rest API with swagger docs and tell the AI to read the swagger docs. It's the same thing. The entire Rest API specification is a lot more flexible than the JSON RPC format /mcp uses.
> Instead, I did something a little bit hacky: if the request is for GET /mcp and the Accept header includes text/html and NOT application/json or text/event-stream, I return a HTML page explaining to the user they're trying to view an mcp server and they need to add it to their client.
This feels like less of a hack and more of discovering what some of the HTTP headers are for. You’re choosing rather reasonably how to present the resource found at /mcp when a client is asking for the resource to be presented in HTML format. It’s perfectly fine to offer an HTML response that says “hey this is not really presentable in HTML. Do this instead.”
Doing a workshop this week on MCP for an enterprise client and explaining the 406 returned by GET against /mcp w/o text/event-stream is exactly one of the things that I have to bring up when I do these.
The specification still leaves a lot to be desired, especially as it relates to auth. There are lots of bad ways to do auth with MCP and only a couple of good ways. It also puts a lot of pressure on the various IdP vendors and relies on lesser used areas of OAuth 2.0/2.1 (like DCR, token exchange, etc.). It started out in a place where the assumption was you were running an MCP Server on a laptop or you were a SaaS provider serving lots of individual users -- somehow DCR in the initial spec iteration seemed like a good idea (spoiler: it wasn't) and fortunately, the latest revision has somewhat addressed that. XAA/ID-JAG & CIMD should continue to round-out some client management and auth solutions for the enterprise.
Gateways are another area that needs to be addressed in the spec. There isn't a formal definition of one in the spec, and yet, there are lots of "gateways" out there. What a gateway is and what it should do is an open question and it means different things to different people depending on who you ask. For example, who does token exchange: the MCP server or the MCP gateway? Both are valid answers right now depending on the implementation or your opinion of which is best.
More spec iterations should be coming this year. I'm still pretty optimistic about MCP as a whole, as it remains a good way to standardize tool calls across agents and some of the other entities that it provides like resources and prompts are genuinely useful to add more determinism to an agent. Interceptors and skills will be good, too.
If you're interested in helping to evolve the spec further, the MCP Contributors Discord is active. There are lots of IGs/WGs that solicit feedback and you can participate in meetings with your feedback.
Excellent. Tiny affordances like this should be more commonplace, IMO.
I think this probably also helps when truly clueless users drop the link into an agent directly, because then the agent will relay the message to the user.
> I did something a little bit hacky: if the request is for GET /mcp and the Accept header includes text/html and NOT application/json or text/event-stream, I return a HTML page
I think so, but if you wanted to be pedantic you could make the argument that the same resource is not being served with the different Accept header. A welcome page is not the same thing as the JSON returned from the MCP spec.
> I wish the spec had some capability to mitigate for this
I like their solution. It feels like because remote MCP servers are built on HTTP that they are actually using the spec as intended. Serving html when asked for it.
But why would you show the MCP server URL as a clickable link in the first place, if it's not meant to be clicked? Put it in a monospaced box with a "copy to clipboard" button, it's not the fault of the user for not "thinking ahead" when they click a clickable link that wasn't actually meant to be clicked.
I never quite understand why /mcp endpoint is needed.
You can still keep using Rest API with swagger docs and tell the AI to read the swagger docs. It's the same thing. The entire Rest API specification is a lot more flexible than the JSON RPC format /mcp uses.
> Instead, I did something a little bit hacky: if the request is for GET /mcp and the Accept header includes text/html and NOT application/json or text/event-stream, I return a HTML page explaining to the user they're trying to view an mcp server and they need to add it to their client.
This feels like less of a hack and more of discovering what some of the HTTP headers are for. You’re choosing rather reasonably how to present the resource found at /mcp when a client is asking for the resource to be presented in HTML format. It’s perfectly fine to offer an HTML response that says “hey this is not really presentable in HTML. Do this instead.”
Doing a workshop this week on MCP for an enterprise client and explaining the 406 returned by GET against /mcp w/o text/event-stream is exactly one of the things that I have to bring up when I do these.
The specification still leaves a lot to be desired, especially as it relates to auth. There are lots of bad ways to do auth with MCP and only a couple of good ways. It also puts a lot of pressure on the various IdP vendors and relies on lesser used areas of OAuth 2.0/2.1 (like DCR, token exchange, etc.). It started out in a place where the assumption was you were running an MCP Server on a laptop or you were a SaaS provider serving lots of individual users -- somehow DCR in the initial spec iteration seemed like a good idea (spoiler: it wasn't) and fortunately, the latest revision has somewhat addressed that. XAA/ID-JAG & CIMD should continue to round-out some client management and auth solutions for the enterprise.
Gateways are another area that needs to be addressed in the spec. There isn't a formal definition of one in the spec, and yet, there are lots of "gateways" out there. What a gateway is and what it should do is an open question and it means different things to different people depending on who you ask. For example, who does token exchange: the MCP server or the MCP gateway? Both are valid answers right now depending on the implementation or your opinion of which is best.
More spec iterations should be coming this year. I'm still pretty optimistic about MCP as a whole, as it remains a good way to standardize tool calls across agents and some of the other entities that it provides like resources and prompts are genuinely useful to add more determinism to an agent. Interceptors and skills will be good, too.
If you're interested in helping to evolve the spec further, the MCP Contributors Discord is active. There are lots of IGs/WGs that solicit feedback and you can participate in meetings with your feedback.
Excellent. Tiny affordances like this should be more commonplace, IMO.
I think this probably also helps when truly clueless users drop the link into an agent directly, because then the agent will relay the message to the user.
> I did something a little bit hacky: if the request is for GET /mcp and the Accept header includes text/html and NOT application/json or text/event-stream, I return a HTML page
Is this not the intended use of request headers?
I think so, but if you wanted to be pedantic you could make the argument that the same resource is not being served with the different Accept header. A welcome page is not the same thing as the JSON returned from the MCP spec.
Maybe it should return a 303 See Other response
Technically not really, it's supposed to be alternative versions of the same content.
> I wish the spec had some capability to mitigate for this
I like their solution. It feels like because remote MCP servers are built on HTTP that they are actually using the spec as intended. Serving html when asked for it.
I hate the MCP rules so much. That I made cookie based auth work by just passing stuff through mimicking the oauth flow.
But why would you show the MCP server URL as a clickable link in the first place, if it's not meant to be clicked? Put it in a monospaced box with a "copy to clipboard" button, it's not the fault of the user for not "thinking ahead" when they click a clickable link that wasn't actually meant to be clicked.
All kinds of tools make it really difficult to not make a URL clickable and even if it wasn't clickable they might still put it in address bar...
Well, they might also just not read the page the OP made, but a change doesn't have to be perfect to be an improvement.