An MCP server over HTTP is sent the headers its entry names, each written as it is or as an {env:VAR} read when the server starts; an import carries them and never copies a value written out; no keychain¶
Decision 820 · accepted · 2026-10-09 · issue #60 · supersedes 700
- What the person writes.
headerson aurlentry, inmcp.jsonand inconfig.yaml'smcp:: a map of name to string, each value as it is or with{env:VAR}in it, read as every other string of the entry is, when the layers are resolved, which is when a session starts its servers and when a reload or a check reads them again. An unset variable refuses the server, naming the variable, and nothing is sent in its place. The value read is held by the session's server and never written anywhere. A header on acommandserver is not sent. Refused, naming why, rather than dropped: a name that is not an HTTP token, a value with a line break or another control character (it would split the request), and a name the client sends itself (Accept,Content-Type,Content-Length,Host,Connection,Transfer-Encoding,Mcp-Session-Id,Mcp-Protocol-Version), since a person who wrote a header must not find out from the server that it never went. - Sent on every request.
Server.headers/1is whatTroupe.MCP.Clientreads for each request, so the headers go withinitializeandnotifications/initializedas with the listing and every call, and with theDELETEthat ends the session, which keeps the headers it was opened with (746). The session key (746) is a hash of all of them: they are part of the credential, and a changed one opens another session. - The credential wins one of the same name. On a server with
oauththe sign-in's token is theAuthorizationthat goes out, and a bundle's service credential its own header; an entry's header of that name, compared without case, is left out, so one goes. The token is the one kept fresh (741): refreshed before it runs out, tried again on a401, dropped when refused, and a secondAuthorizationfrom a file would be a stale credential beside it.oauthis also the narrower statement of how the server is reached. On a server withoutoauth, anAuthorizationinheadersis what goes out. - Shown by name.
mcp.listandmcp.add's answers carryheadersas names, asenv(700).mcp.<name>.headersis a secret in the key table, sotroupe config --explainmasks a value as it masks a key, with the{env:VAR}it came from beside it.Server'sinspectleaves the headers out, andTroupe.Session.MCP'sformat_status/1prints a server'senvandheadersby name, for a crash report and:sys.get_status/1. An import's warnings name the variable, never the value. - A workspace's server says it sends them. A header can read the person's own
variable and send it to a URL a cloned repository chose, so the trust question (700)
names the headers ("notes (https://…, sending the headers X-Api-Key, X-Team)"), and
the fingerprint takes them as read, as it takes
env: changed headers ask again, and so does a variable whose value changed, as anenvvalue's does. - Import carries them. Claude Code's, Cursor's and VS Code's
headers, with${VAR}read as{env:VAR}and a VS Code${input:…}skipping the server, as before. opencode'smcpblock is read too:type: localwith acommandlist and anenvironment,type: remotewithurlandheaders,enabled: falseas off; itstimeout(how long the tool listing is waited for, not a call) andoauth: falseare not read, and a{file:…}skips the server, since only opencode reads one. It is read from the file's text, soTroupe.Config.OpenCodeis not touched. Claude Code'sheadersHelper, a command that prints headers, is not run, and the import says so. - A copy never copies a value written out.
mcp.addwithfromand nolink(Import.parse(text, copy: true)) writes a header whose value reads no variable as{env:<SERVER>_<HEADER>}, upper case with_(a leading digit getsMCP_), aBearer,BasicorTokenkept in front so the variable holds the credential alone, and a warning names the variable and says the value is in the file it came from. Every such header, not only one named like a credential: an importer cannot tell fromX-Honeycomb-Teamthat it is a key, and a header on an MCP server is nearly always how it is keyed; a value that is not a secret is one edit to write back. One rule, the one 741 gives formcp.json: it is linked, copied and committed, and a credential does not belong in it. A link reads the other tool's file where it is, where the value already was, and writes nothing. Anenvvalue is copied as 700 copies it, since one is as often a log level as a key; whether a literal one should follow this rule is left for its own issue. - No keychain. The maintainer's answer to #60's one open question: a header's
secret stays in the person's environment, as
{env:VAR}, and an OAuth server's tokens in<state>/mcp-oauth.json(741). For the token store's reasons: the daemon has no keychain in this build (the model key is inconfig.yamlfor the same reason), and it is the process that sends the header, so a keychain only the desktop app could read would leave a terminal-only person with nothing.{env:VAR}already keeps a secret out of every file Troupe writes, reads the same on every platform and in CI, and is what the other tools' files already say (${VAR}), so an import needs no second place to put one. If the daemon gains a keychain for its own model key, headers and tokens move with it.
Governs: apps/troupe_core/lib/troupe/config.ex, apps/troupe_core/lib/troupe/config/schema.ex, apps/troupe_core/lib/troupe/mcp/import.ex, apps/troupe_core/lib/troupe/mcp/local.ex, apps/troupe_core/lib/troupe/session/mcp.ex, apps/troupe_gateway/lib/troupe/gateway/local_sources.ex, apps/troupe_protocol/lib/troupe/mcp/client.ex, apps/troupe_protocol/lib/troupe/mcp/server.ex