[{"data":1,"prerenderedAt":627},["ShallowReactive",2],{"page-en-\u002Fgarden\u002Fmcp-server-authorization":3,"backlinks-en-\u002Fgarden\u002Fmcp-server-authorization":277},{"doc":4,"isFallback":264},{"id":5,"title":6,"body":7,"description":263,"draft":264,"extension":265,"meta":266,"navigation":267,"notice":268,"path":269,"seo":270,"stage":271,"stem":13,"tags":272,"topic":275,"__hash__":276},"garden_en\u002Fmcp-server-authorization.md","MCP Server Authorization",{"type":8,"value":9,"toc":253},"minimark",[10,14,18,26,31,34,40,43,50,54,63,71,78,82,85,90,99,115,120,127,134,139,148,157,160,173,177,180,192,198,208,212,215,237,240,244,250],[11,12,6],"h1",{"id":13},"mcp-server-authorization",[15,16,17],"p",{},"The common reading is \"MCP servers need OAuth\", followed by bolting OAuth onto every server someone writes. The specification says something considerably more specific, and the specific version is easier to implement.",[15,19,20,21,25],{},"Everything below is from the Model Context Protocol specification, ",[22,23,24],"strong",{},"revision 2026-07-28",". Quotes are verbatim, and the RFC 2119 keywords are the spec's own — the difference between MUST and SHOULD is doing real work here.",[27,28,30],"h2",{"id":29},"authorization-is-optional","Authorization is optional",[15,32,33],{},"Straight from the spec:",[35,36,37],"blockquote",{},[15,38,39],{},"\"Authorization is OPTIONAL for MCP implementations.\"",[15,41,42],{},"A server behind a reverse proxy that already authenticates, or one bound to localhost and reachable only by processes on that machine, is entitled to implement none of this. That's not a loophole; it's the design.",[15,44,45,46,49],{},"The question to ask isn't \"do I need auth?\" but \"",[22,47,48],{},"what's my transport, and what's my trust boundary?","\"",[27,51,53],{"id":52},"over-stdio-dont","Over stdio, don't",[35,55,56],{},[15,57,58,59,62],{},"\"Implementations using an STDIO transport ",[22,60,61],{},"SHOULD NOT"," follow this specification, and instead retrieve credentials from the environment.\"",[15,64,65,66,70],{},"Worth reading twice, because it's stronger than permission to skip the work — it's a recommendation ",[67,68,69],"em",{},"against"," doing it.",[15,72,73,74,77],{},"The logic is that over stdio the trust boundary is the ",[22,75,76],{},"process boundary",". The client launched the server as a subprocess. It already controls the server's environment, its lifetime, and its file descriptors. Layering a token exchange on top of that relationship doesn't add a boundary; it adds ceremony across a boundary that was never crossed. Credentials come from the environment, because whoever set the environment is already the trusted party.",[27,79,81],{"id":80},"over-http-youre-an-oauth-21-resource-server","Over HTTP, you're an OAuth 2.1 resource server",[15,83,84],{},"This is where the obligations become concrete. An HTTP-transport MCP server is a resource server, and it owes four things.",[15,86,87],{},[22,88,89],{},"Publish protected resource metadata.",[35,91,92],{},[15,93,94,95,98],{},"\"MCP servers ",[22,96,97],{},"MUST"," implement OAuth 2.0 Protected Resource Metadata (RFC 9728)\"",[15,100,101,102,106,107,110,111,114],{},"In practice: serve ",[103,104,105],"code",{},"\u002F.well-known\u002Foauth-protected-resource",", and include a ",[103,108,109],{},"resource_metadata"," pointer in the ",[103,112,113],{},"WWW-Authenticate"," header on a 401. That's how a client discovers which authorization server to go to without being told out of band.",[15,116,117],{},[22,118,119],{},"Validate the audience.",[35,121,122],{},[15,123,94,124,126],{},[22,125,97],{}," validate that access tokens were issued specifically for them as the intended audience\"",[15,128,129,130,133],{},"A token that is merely ",[67,131,132],{},"valid"," is not sufficient. It has to have been minted for this server. A server that accepts any well-signed token from a familiar issuer becomes a confused deputy for every other resource that issuer serves.",[15,135,136],{},[22,137,138],{},"Never pass the token through.",[35,140,141],{},[15,142,143,144,147],{},"\"The MCP server ",[22,145,146],{},"MUST NOT"," pass through the token it received from the MCP client\"",[15,149,150,151,156],{},"Forwarding the caller's token to a downstream API is prohibited, not discouraged. If the server needs to call something on the user's behalf, it needs its own credential — which is the entire subject of ",[152,153,155],"a",{"href":154},"\u002Fgarden\u002Facting-on-a-humans-behalf","Acting on a Human's Behalf",".",[15,158,159],{},"Note how cleanly these last two fit together: if every resource server validates audience, and no server forwards tokens, then a token's audience always tells you truthfully where it was meant to go. Each rule is what makes the other one worth enforcing.",[15,161,162,169,170,172],{},[22,163,164,165,168],{},"Include ",[103,166,167],{},"scope"," in the challenge."," This one is a SHOULD, not a MUST — the ",[103,171,113],{}," header should name the scope required, so a client can request the right thing on its second attempt rather than guessing.",[27,174,176],{"id":175},"transport-obligations","Transport obligations",[15,178,179],{},"Independent of authorization, and easy to overlook because they aren't about tokens:",[35,181,182],{},[15,183,184,185,187,188,191],{},"\"Servers ",[22,186,97],{}," validate the ",[103,189,190],{},"Origin"," header on all incoming connections\"",[15,193,194,195,197],{},"An invalid ",[103,196,190],{}," gets a 403. This is what stops a web page the user happens to have open from driving a local MCP server through the browser — an attack that needs no credentials at all, because the browser helpfully supplies them.",[15,199,200,201,204,205,156],{},"Additionally: servers running locally ",[22,202,203],{},"SHOULD"," bind only to localhost rather than all interfaces, and there is to be exactly ",[22,206,207],{},"one endpoint path",[27,209,211],{"id":210},"the-actual-shape-of-the-decision","The actual shape of the decision",[15,213,214],{},"Reordered as a thing you can act on:",[216,217,218,225],"ul",{},[219,220,221,224],"li",{},[22,222,223],{},"stdio transport"," → no authorization layer. Credentials from the environment. The spec recommends against anything more.",[219,226,227,230,231,233,234,236],{},[22,228,229],{},"HTTP transport"," → OAuth 2.1 resource server: RFC 9728 metadata, strict audience validation, no passthrough, ",[103,232,167],{}," in the challenge, ",[103,235,190],{}," validation, localhost binding when local.",[15,238,239],{},"Most of the confusion in this area comes from reading advice written for the second case and applying it to the first.",[27,241,243],{"id":242},"where-this-actually-stands","Where this actually stands",[15,245,246,249],{},[22,247,248],{},"Budding."," Sourced directly from one specification revision and quoted rather than paraphrased, so it's as reliable as that document — and it will age exactly as fast as the spec does. The revision is stamped at the top for that reason.",[15,251,252],{},"What this note doesn't cover: how any particular SDK implements the above, whether the client side holds up its end, or the dynamic client registration story. Those were not checked and aren't asserted.",{"title":254,"searchDepth":255,"depth":255,"links":256},"",2,[257,258,259,260,261,262],{"id":29,"depth":255,"text":30},{"id":52,"depth":255,"text":53},{"id":80,"depth":255,"text":81},{"id":175,"depth":255,"text":176},{"id":210,"depth":255,"text":211},{"id":242,"depth":255,"text":243},"Whether an MCP server needs OAuth at all depends on its transport — and over stdio the spec says it shouldn't have any.",false,"md",{},true,null,"\u002Fgarden\u002Fmcp-server-authorization",{"title":6,"description":263},"budding",[273,274],"security","identity","mcp-auth","z-V6MLWNhR2V4fupN2eyFYJchodqruriGx8djSrlAUE",[278],{"id":279,"title":155,"body":280,"description":621,"draft":264,"extension":265,"meta":622,"navigation":267,"notice":268,"path":154,"seo":623,"stage":271,"stem":284,"tags":624,"topic":625,"__hash__":626},"garden_en\u002Facting-on-a-humans-behalf.md",{"type":8,"value":281,"toc":612},[282,285,292,295,312,315,319,330,333,359,370,373,377,380,387,398,405,409,416,426,432,436,439,461,472,475,479,482,493,503,516,523,526,536,556,559,563,566,584,595,598,600,605],[11,283,155],{"id":284},"acting-on-a-humans-behalf",[15,286,287,288,291],{},"Put a service between a person and a backend and you've created an identity question, whether or not you notice. The person authenticated to ",[67,289,290],{},"your service",". Your service now has to say something to the backend. What, exactly?",[15,293,294],{},"There are two credentials in play here, and the entire design rests on keeping them apart:",[296,297,298,305],"ol",{},[219,299,300,301,304],{},"The one the ",[22,302,303],{},"caller"," presented to your service.",[219,306,307,308,311],{},"The one your ",[22,309,310],{},"service"," presents to the backend.",[15,313,314],{},"The tempting move — and the one worth naming as a mistake up front — is to make the second a copy of the first.",[27,316,318],{"id":317},"why-passing-the-token-through-breaks-things","Why passing the token through breaks things",[15,320,321,322,325,326,329],{},"If a service simply forwards the caller's token to the backend, the backend can no longer tell whether a request arrived ",[67,323,324],{},"through the service"," or ",[67,327,328],{},"directly",". Both look identical on the wire, because they are identical.",[15,331,332],{},"That sounds abstract until you list what depends on being able to tell:",[216,334,335,341,347,353],{},[219,336,337,340],{},[22,338,339],{},"Rate limits"," scoped per client stop meaning anything, because there's only one apparent client.",[219,342,343,346],{},[22,344,345],{},"Audit trails"," record the human, with no record that a service was involved at all.",[219,348,349,352],{},[22,350,351],{},"Anomaly detection"," loses its baseline: traffic from an automated component and traffic from a person at a keyboard have very different shapes, and merging them hides both.",[219,354,355,358],{},[22,356,357],{},"Revocation"," gets coarse. You can no longer cut off the service without cutting off the person.",[15,360,361,362,365,366,369],{},"Every one of those controls is keyed on the token's ",[67,363,364],{},"audience"," — who the token was minted for. Passthrough destroys that field's meaning. This isn't a policy preference; it's why the ",[152,367,368],{"href":269},"MCP specification forbids it outright"," rather than merely discouraging it.",[15,371,372],{},"So the service needs its own credential. That leaves exactly two shapes.",[27,374,376],{"id":375},"option-one-service-identity","Option one: service identity",[15,378,379],{},"The service holds a credential of its own. It authenticates to the backend as itself.",[15,381,382,383,386],{},"The backend sees ",[67,384,385],{},"the service",", cleanly and unambiguously. Audience checks work. Rate limits work. Revoking the service is one operation.",[15,388,389,390,393,394,397],{},"The cost is stated plainly: ",[22,391,392],{},"the human's trail ends at the service."," The backend knows \"this service did it\", not \"this service did it for Amir\". If you need to answer ",[67,395,396],{},"which person"," triggered a given backend call, you have to answer it from the service's own logs, and you have to trust those logs, and they're now a separate system from your backend's audit trail.",[15,399,400,401,404],{},"This option's real virtue is that it works everywhere. Every OAuth server does ",[103,402,403],{},"client_credentials",". There is no feature to shop for.",[27,406,408],{"id":407},"option-two-delegation","Option two: delegation",[15,410,411,412,415],{},"The service exchanges the caller's token for a ",[67,413,414],{},"different"," token, minted for the backend, that carries both identities.",[15,417,418,419,425],{},"RFC 8693 (OAuth 2.0 Token Exchange) is the standard for this, and its mechanism is the ",[22,420,421,424],{},[103,422,423],{},"act"," claim",": the subject of the token is the human, and the actor is the service. Both are present in one token, and a backend that reads the claim sees \"X, acting through Y.\" Whether a given backend reads it is a separate question, taken up further down — the answer is not automatically yes.",[15,427,428,429,431],{},"The ",[103,430,423],{}," claim nests. A chain of services each add themselves, and the resulting token describes the whole path rather than flattening it.",[27,433,435],{"id":434},"delegation-is-not-impersonation","Delegation is not impersonation",[15,437,438],{},"This is the distinction most worth carrying away, because the two are frequently discussed as one thing and they have opposite properties.",[216,440,441,451],{},[219,442,443,446,447,450],{},[22,444,445],{},"Impersonation",": the service ",[67,448,449],{},"becomes"," the human. The resulting token says \"X\". The service's involvement is gone — not obscured, gone. Downstream, there is no way to recover the fact that a machine was in the path.",[219,452,453,456,457,460],{},[22,454,455],{},"Delegation",": the service acts ",[67,458,459],{},"as itself, on behalf of"," the human. The resulting token says \"X, via Y\". Both identities survive.",[15,462,463,464,467,468,471],{},"Mechanically, the difference between them is a ",[22,465,466],{},"single parameter",": whether the exchange request includes an ",[103,469,470],{},"actor_token",". Send it, and you get delegation. Omit it, and you get impersonation.",[15,473,474],{},"That's a startlingly small lever for a large semantic difference, and it's worth knowing which one a given implementation gives you by default — and, more to the point, whether it supports both at all. Several do not.",[27,476,478],{"id":477},"but-does-the-backend-read-it","But does the backend read it?",[15,480,481],{},"Putting the identity into the token and having something downstream act on it are different achievements, and the standard only guarantees the first.",[15,483,484,485,488,489,492],{},"This got measured rather than assumed: Zitadel 2.71.7 issuing tokens against Stalwart 0.16.17. The exchange itself works exactly as described above — ",[103,486,487],{},"sub"," is the human, ",[103,490,491],{},"act.sub"," is the service, and Stalwart accepts the token and acts as the human.",[15,494,495,496,498,499,502],{},"Then it stops. Stalwart never reads ",[103,497,423],{},". And a successful bearer authentication produces ",[22,500,501],{},"no authentication event at all"," — checked with a trace-level tracer — where a password login produces one. So on the backend side, a delegated request is indistinguishable from the person acting directly, and neither one is written down.",[15,504,505,506,508,509,512,513,156],{},"Worth being precise about what that is and isn't. It's not a defect, and it isn't carelessness: reading ",[103,507,423],{}," is a capability that simply isn't present, which is the ordinary state of most backends today. The RFC defines what a token may ",[67,510,511],{},"say",". It obliges no resource server to ",[67,514,515],{},"care",[35,517,518],{},[15,519,520],{},[22,521,522],{},"Delegation puts the identity in the token. Whether the backend reads it is a second question — and it often isn't asked.",[15,524,525],{},"The consequence lands directly on the choice this page is about. If you picked delegation to get an end-to-end audit trail, you've done half the work. The other half is confirming the backend uses what you sent. Where it doesn't, the trail has to be produced by your own service instead — which is precisely the cost option one was already charged for above.",[15,527,528,529,532,533,535],{},"So delegation's advantage over service identity is ",[22,530,531],{},"smaller than the earlier sections imply",", whenever the backend ignores ",[103,534,423],{},". What survives that discount is still real:",[216,537,538,544,550],{},[219,539,540,543],{},[22,541,542],{},"Short-lived tokens"," rather than a long-lived shared secret sitting in the service's configuration.",[219,545,546,549],{},[22,547,548],{},"Central revocation"," — cut the service off at the issuer instead of rotating a credential everywhere it was deployed.",[219,551,552,555],{},[22,553,554],{},"No backend credential in the service's config"," at all.",[15,557,558],{},"Those are security properties, not audit properties. If audit was the reason for reaching for delegation, check the far end before counting the win.",[27,560,562],{"id":561},"the-questions-this-actually-turns-into","The questions this actually turns into",[15,564,565],{},"Notice what happened. \"How should my service authenticate?\" resolved into two much more specific questions, both answerable before committing to anything:",[296,567,568,576],{},[219,569,570],{},[22,571,572,573,575],{},"Does my token issuer support RFC 8693 with an ",[103,574,470],{},"?",[219,577,578],{},[22,579,580,581,583],{},"Does my backend do anything with the ",[103,582,423],{}," claim once it arrives?",[15,585,586,587,590,591,156],{},"The first is a yes\u002Fno you can settle from documentation — and plenty of identity providers answer ",[67,588,589],{},"no"," while still advertising RFC 8693 support, because issuing a token for yourself and issuing a token that names two parties are different features filed under one RFC number. That's the subject of the next note: ",[152,592,594],{"href":593},"\u002Fgarden\u002Fquestions-to-ask-an-idp","Questions to Ask an IdP",[15,596,597],{},"The second is the one that's easy to skip, because the standard says nothing about it and the token looks correct either way. It can only be answered against the specific backend — and, as above, the answer is often no.",[27,599,243],{"id":242},[15,601,602,604],{},[22,603,248],{}," The model is settled and the vocabulary is standard — none of it is invented here. One end of it has since been measured rather than read: the Zitadel\u002FStalwart result above is a real test of a real pair, not a documentation claim. The deployment itself still hasn't happened, so most of the operational story is still ahead.",[15,606,607,608,611],{},"The honest summary, updated: service identity is always available and gives up the human's trail. Delegation preserves that trail ",[67,609,610],{},"in the token",", and constrains your choice of issuer considerably — but it only pays off in audit terms if the backend reads what it's sent. Pick knowing which you're paying for, and check the far end before assuming you got it.",{"title":254,"searchDepth":255,"depth":255,"links":613},[614,615,616,617,618,619,620],{"id":317,"depth":255,"text":318},{"id":375,"depth":255,"text":376},{"id":407,"depth":255,"text":408},{"id":434,"depth":255,"text":435},{"id":477,"depth":255,"text":478},{"id":561,"depth":255,"text":562},{"id":242,"depth":255,"text":243},"A service that calls a backend for a person needs two credentials — and the first must never become the second.",{},{"title":155,"description":621},[273,274],"delegation","uKdI0phUDX6P87X_uCGwFwgfIRwYhscK0xZhZiTTZik",1789414695065]