> 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.
I have also been finding the MCP auth story to be really lacking was excited to see OAuth 2 support until I tried to get it to work at work and realized our idp implementation didn't support 2.1, and went into the spec and started wondering if anyone had a good experience yet. Luckily most of our environment can settle on a OAuth token env var standard until that's all in order.
A lot of how well it works or won't work depends on your clients, as not all clients have support for things like RFC 9728 (Protected Resource Metadata). Assuming your client has good support for most of the OAuth 2.0 standards that MCP uses (you don't need DCR as you can statically register clients, assuming that is viable for your environment), then it is possible now with most IDPs to get an OAuth 2.0 auth code flow working just fine. You would then do a token exchange to the upstream to ensure to get the appropriate new audience and rescope/downscope as necessary. Gateways can also help here a lot as instead of baking in all of the auth concerns into your MCP Servers and upstreams, you delegate that to the MCP Gateway. Again, gateway here means different things to different vendors, but Kong, for example, has the ability to act as an MCP proxy (gateway), expose tools based on consumer role or group, apply OAuth 2.0 to it and do an upstream token exchange, while also acting as a regular API gateway that can protect an endpoint with OAuth 2.0/OIDC.
First time I access this website, as far as I know (via a corporate VPN, and the first time I see this kind of blocking from Cloudflare while using that VPN):
"Sorry, you have been blocked
You are unable to access hybridlogic.co.uk
Why have I been blocked?
This website is using a security service to protect itself from online attacks. The action you just performed triggered the security solution. There are several actions that could trigger this block including submitting a certain word or phrase, a SQL command or malformed data."
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 have learned that if the request accepts html, just give them that, however, some agents will ask for text/markdown, so just give them that.
you can even take OPs ideas further: text/html? serve html help page; text/markdown? serve the same but pure text, maybe nudge the agent on how to install the mcp; application/json? pass through to the mcp app.
> 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.
A redirect actually does make sense but then there will be some percentage of users that end up copying the redirect URL and try to use that as the MCP URL
Bearer tokens using mcp-remote are the pragmatic way forward out of the authentication mess.
Spec-based implementations of OAuth 2.0/2.1, including dynamic client registration and token exchanges, are absolutely necessary on a large scale but are an enormous barrier for adoption during early deployments. Cookie tricks ignore the spec and produce special cases when client credentials need to be rotated.
Solution in the real world: configure the server to provide the WWW-Authenticate header with value "Bearer" on unauthorized requests, issue limited-scoped tokens, leave the rest up to mcp-remote. The client authenticates once, uses bearer token in its requests, server verifies against scopes. No dynamic client registration required.
The authentication solution becomes clearer if you distinguish between "what the spec allows" and "what you need in your deployment." Not many servers really require OAuth on day 1.
I love this. The best documentation is that which is presented at the exact place and time that it is needed, and users self support really well if you do that.
I once worked for $COMPANY and we had a network scanning application. Always generated a lot of tickets from angry people wanting to scream about bots.
So we put a web page page on each worker that would inherit some details from whatever job was running, and say “I’m a $TYPE_OF_SCANNER FROM $COMPANY doing $THING_THAT_BENEFITS_YOU.
This behavior is covered by our terms of service page at $LINK.
If you believe that we should not be doing this, please contact $SUPPORT and provide this code:
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.
rest api with swagger docs requires one extra hop to pull the details necessary to interact with the api, and it pollutes context in a similar way as mcp.
ideally what you would have is skills + scripts that the agent can load progressively to interact with the api
or even better: a single cli tool the agent is aware of, and which combines `--help` output with `tldr` tips, when the command is incomplete, and prints out helpful error messages when the incantation is wrong
In fact, this is how Kubernetes APIs work. Even the CLI asks YAML or JSON content type when `-o yaml` or `-o json` is specified.
Also, some other sites (albeit sometimes looking at the User-Agent header, hence more hacky) also doing the same. For example `ipinfo.io` returns HTML page when opened in a browser but a JSON (prettified) when requested via cURL.
Yes, we do use user agents to separate requests to our websites and API service. However, we request users to switch to api.ipinfo.io (dedicated API infrastructure) and use ipinfo.io/json for an explicit request for the API endpoint.
There are indeed some limitations to this implementation. The primary one being IPv6 support. The implementation prioritizes convenience over internet limitations, requiring us to roll out IPv6 dual stacking on the web request level as opposed to the DNS level. On an API level, this results in users with IPv6 addresses making API requests to v6.ipinfo.io.
So, last year we rolled out dedicated API infrastructure for api.ipinfo.io
I have spent ~3 months working on various aspects of an MCP server builder at my day job and I hadn’t considered this solution to the nightmare of getting non technical end users connected. I shall be borrowing it next week!
I ran into the exact same 406 confusion last week when wiring up an MCP server. The Accept header trick is elegant, but I'm wondering — how do you handle clients that send `Accept: /`? Some older HTTP libraries do this by default and it'd match both html and json conditions.
> Despite the fact that MCP is an utterly terrible attempt at a "specification",
Can I just say that anybody involved with MCP's launch should be ashamed of what they put out there. I understand tool calling. I understand specs. I read MCP's "spec" and I used useless word salad that alternates between baby's first wire format and pie-in-the-sky marketing speak. Several of the navigation links I encountered were broken.
Poorly thought out, poorly communicated, but it's the only thing out there that 1) meets the need, and 2) published by people with a huge amount of reach. Right place, right time, shit effort. So it gets adoption. Like the history of PCs, of the internet, or everything, I guess. Worse truly is better.
I thought the concensus was slowly converging to using clear CLIs + skills (i.e. progressive disclosure) instead of MCPs to avoid the context pollution.
what about web apps that requires oauth login - for normal users?
For example, is a typical Google Drive user expected to install an official google drive CLI and a skill md file just to interact with Google Drive in the chatgpt app? That seems absurd, IMO. Clicking “install” via an MCP / Plugin marketplace and then logging in via Oauth is less confusing.
MCP is also way more convenient (as a user) if i’m interacting with an API that supports oauth anyway. I don’t need to generate an api key, install a binary, create an md file, etc. CLIs and skills are great too! But not always the best choice.
folks have caught on to it, but from a service provider perspective it's not as easy to deliver the solution
mcp is basically `claude mcp add <service name> <service url>`
skills require multi step marketplace registration, refresh, then picking the right skill out of *checks notes* 116 skills on the official marketplace + however many skill come with the new marketplace
cli tools may be a bit better, maybe they're there already because you need them to interact with deployment, or they might be a simple `brew add <service cli>`
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 call this "dev think". Blames user for not thinking ahead when they themselves haven't thought ahead about how users use things. It's everywhere these days, as an end user of things myself, it's maddening.
> 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.
> 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.”
I thought the same thing, just discovered content negotiation!
Indeed! Far from a hack it is the entire purpose to the accept header!
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.
Hey thanks for the note about the discord!
I have also been finding the MCP auth story to be really lacking was excited to see OAuth 2 support until I tried to get it to work at work and realized our idp implementation didn't support 2.1, and went into the spec and started wondering if anyone had a good experience yet. Luckily most of our environment can settle on a OAuth token env var standard until that's all in order.
A lot of how well it works or won't work depends on your clients, as not all clients have support for things like RFC 9728 (Protected Resource Metadata). Assuming your client has good support for most of the OAuth 2.0 standards that MCP uses (you don't need DCR as you can statically register clients, assuming that is viable for your environment), then it is possible now with most IDPs to get an OAuth 2.0 auth code flow working just fine. You would then do a token exchange to the upstream to ensure to get the appropriate new audience and rescope/downscope as necessary. Gateways can also help here a lot as instead of baking in all of the auth concerns into your MCP Servers and upstreams, you delegate that to the MCP Gateway. Again, gateway here means different things to different vendors, but Kong, for example, has the ability to act as an MCP proxy (gateway), expose tools based on consumer role or group, apply OAuth 2.0 to it and do an upstream token exchange, while also acting as a regular API gateway that can protect an endpoint with OAuth 2.0/OIDC.
We build a gateway (MintMCP) and I’d love to connect and exchange notes.
We’re excited about XAA, it will simplify many flows
First time I access this website, as far as I know (via a corporate VPN, and the first time I see this kind of blocking from Cloudflare while using that VPN):
"Sorry, you have been blocked
You are unable to access hybridlogic.co.uk
Why have I been blocked?
This website is using a security service to protect itself from online attacks. The action you just performed triggered the security solution. There are several actions that could trigger this block including submitting a certain word or phrase, a SQL command or malformed data."
Same, I don't use any VPNs though.
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 have experimented with this idea a bit
i have learned that if the request accepts html, just give them that, however, some agents will ask for text/markdown, so just give them that.
you can even take OPs ideas further: text/html? serve html help page; text/markdown? serve the same but pure text, maybe nudge the agent on how to install the mcp; application/json? pass through to the mcp app.
the whole llms.txt thing could have been that
> 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
A redirect actually does make sense but then there will be some percentage of users that end up copying the redirect URL and try to use that as the MCP URL
Technically not really, it's supposed to be alternative versions of the same content.
Bearer tokens using mcp-remote are the pragmatic way forward out of the authentication mess.
Spec-based implementations of OAuth 2.0/2.1, including dynamic client registration and token exchanges, are absolutely necessary on a large scale but are an enormous barrier for adoption during early deployments. Cookie tricks ignore the spec and produce special cases when client credentials need to be rotated.
Solution in the real world: configure the server to provide the WWW-Authenticate header with value "Bearer" on unauthorized requests, issue limited-scoped tokens, leave the rest up to mcp-remote. The client authenticates once, uses bearer token in its requests, server verifies against scopes. No dynamic client registration required.
The authentication solution becomes clearer if you distinguish between "what the spec allows" and "what you need in your deployment." Not many servers really require OAuth on day 1.
I love this. The best documentation is that which is presented at the exact place and time that it is needed, and users self support really well if you do that.
I once worked for $COMPANY and we had a network scanning application. Always generated a lot of tickets from angry people wanting to scream about bots.
So we put a web page page on each worker that would inherit some details from whatever job was running, and say “I’m a $TYPE_OF_SCANNER FROM $COMPANY doing $THING_THAT_BENEFITS_YOU.
This behavior is covered by our terms of service page at $LINK.
If you believe that we should not be doing this, please contact $SUPPORT and provide this code:
$SCAN_JOB_IDENTIFIER”
Call volume and unhappy customers went way down.
this reminds: webcrawlers are supposed to include an info url with their user agent header
ex: Googlebot/2.1 (+http://www.google.com/bot.html)
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.
MCP is fine for exposing tools that don't have APIs, but wrapping an API is an MCP is fine if you like consistency.
Personally, for just tools, I wire up tool calls with context captured via system prompt.
rest api with swagger docs requires one extra hop to pull the details necessary to interact with the api, and it pollutes context in a similar way as mcp.
ideally what you would have is skills + scripts that the agent can load progressively to interact with the api
or even better: a single cli tool the agent is aware of, and which combines `--help` output with `tldr` tips, when the command is incomplete, and prints out helpful error messages when the incantation is wrong
MCP = Model Context Protocol, an interface for LLMs to retrieve information and perform actions
Not a hack at all.
In fact, this is how Kubernetes APIs work. Even the CLI asks YAML or JSON content type when `-o yaml` or `-o json` is specified.
Also, some other sites (albeit sometimes looking at the User-Agent header, hence more hacky) also doing the same. For example `ipinfo.io` returns HTML page when opened in a browser but a JSON (prettified) when requested via cURL.
Yes, we do use user agents to separate requests to our websites and API service. However, we request users to switch to api.ipinfo.io (dedicated API infrastructure) and use ipinfo.io/json for an explicit request for the API endpoint.
There are indeed some limitations to this implementation. The primary one being IPv6 support. The implementation prioritizes convenience over internet limitations, requiring us to roll out IPv6 dual stacking on the web request level as opposed to the DNS level. On an API level, this results in users with IPv6 addresses making API requests to v6.ipinfo.io.
So, last year we rolled out dedicated API infrastructure for api.ipinfo.io
I have spent ~3 months working on various aspects of an MCP server builder at my day job and I hadn’t considered this solution to the nightmare of getting non technical end users connected. I shall be borrowing it next week!
consider also solutions like llms.txt, or variations of it using the same trick mentioned in OP
GET / accept: text/html -> passthrough to existing content
GET / accept: text/markdown -> respond with llms.txt or a stripped down version without html tags or other noisy bits
I ran into the exact same 406 confusion last week when wiring up an MCP server. The Accept header trick is elegant, but I'm wondering — how do you handle clients that send `Accept: /`? Some older HTTP libraries do this by default and it'd match both html and json conditions.
> Despite the fact that MCP is an utterly terrible attempt at a "specification",
Can I just say that anybody involved with MCP's launch should be ashamed of what they put out there. I understand tool calling. I understand specs. I read MCP's "spec" and I used useless word salad that alternates between baby's first wire format and pie-in-the-sky marketing speak. Several of the navigation links I encountered were broken.
Poorly thought out, poorly communicated, but it's the only thing out there that 1) meets the need, and 2) published by people with a huge amount of reach. Right place, right time, shit effort. So it gets adoption. Like the history of PCs, of the internet, or everything, I guess. Worse truly is better.
At least there is this:
https://github.com/modelcontextprotocol/modelcontextprotocol...
Sadly, site is blocked for me.
I thought the concensus was slowly converging to using clear CLIs + skills (i.e. progressive disclosure) instead of MCPs to avoid the context pollution.
CLIs need installs. What if your customer uses Web-based Agent? What if your customer has IT that does not easily allow install/updates of your CLI?
CLIs are working better with current harnesses in my experience, but no idea how I would ship them.
i've used pypi, which enables: `uvx <package name>` or `uv tool install <package name>` for a more permanent setup
some folks go to the trouble of publishing with `brew`
then there's the old `curl -LsSf https://example.com/install.sh | sh`
what about web apps that requires oauth login - for normal users?
For example, is a typical Google Drive user expected to install an official google drive CLI and a skill md file just to interact with Google Drive in the chatgpt app? That seems absurd, IMO. Clicking “install” via an MCP / Plugin marketplace and then logging in via Oauth is less confusing.
MCP is also way more convenient (as a user) if i’m interacting with an API that supports oauth anyway. I don’t need to generate an api key, install a binary, create an md file, etc. CLIs and skills are great too! But not always the best choice.
parent is right, but so are you
note: cli tools do auth too — gh and claude code itself have some of the nicest auth flows i've experienced
Sorry, you have been blocked. Webmaster, maybe check your firewall? :/
Haven’t people caught on lately that MCP is a dead end and that we’re better off feeding shell scripts to agents with some brief documentation?
folks have caught on to it, but from a service provider perspective it's not as easy to deliver the solution
mcp is basically `claude mcp add <service name> <service url>`
skills require multi step marketplace registration, refresh, then picking the right skill out of *checks notes* 116 skills on the official marketplace + however many skill come with the new marketplace
cli tools may be a bit better, maybe they're there already because you need them to interact with deployment, or they might be a simple `brew add <service cli>`
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.
I call this "dev think". Blames user for not thinking ahead when they themselves haven't thought ahead about how users use things. It's everywhere these days, as an end user of things myself, it's maddening.
Yep, unfortunately, not many developers think about good UX.
> 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.
"The (annoying) solution is to package our server up into a connector/plugin and release it for each and every LLM client out there."
Isn't this literally against the entire point of MCP
no.
you only deploy + maintain one mcp server, all mcp capable harnesses will know how to use it.
you need to publish to each marketplace for discovery, but you can also just put the the incantation on the product page and be done with it.