Authenticate to an MCP server with more than a bearer token
Many MCP servers do not take Authorization: Bearer <token>. One wants
X-API-Key. Another wants Authorization: Token <key>, or a user name and
password. A vendor's server may also want a tenant header next to the key, or a
header that says which end user is calling so it can apply its own limits.
From 1.9.0, each MCP server in DVARA has an Upstream Authentication setting. It says where the credential goes, which other headers go with it, and which of the caller's own headers are passed on. It works the same on every transport and when DVARA reads the server's tool list.
Where the credential goes
The credential is still the one Credential Reference names: a credential on the Credentials page. Choose how it is sent:
| Placement | What the server receives |
|---|---|
| Bearer (default) | Authorization: Bearer <credential> |
| Header | The header you name, such as X-API-Key: <credential>. Add a scheme to get Authorization: Token <credential>. |
| Basic | Authorization: Basic ..., built from a credential that holds user:password. |
A server you registered before 1.9.0 keeps sending a bearer token.
Extra headers
Add one header per line, as Name: value. A value can be one of three kinds:
| You write | It sends |
|---|---|
X-Region: eu-west | The text as written. Use this only for values that are not secret. |
X-Vendor-Key: secret:mcp.vendor-key | The credential with that secret key, from the Credentials page. The value is never stored on the server, shown on the page, written to a record or put in an export. |
X-User: {{user.id}} | A value filled from the caller, so the server can scope the call to that user. |
The placeholders are {{user.id}}, {{workspace.id}}, {{key.id}},
{{auth.issuer}}, {{client.id}} and, for callers who sign in with OAuth,
{{claim.<name>}} for a claim in their token.
DVARA does not guess. If a secret cannot be found, or the caller has no value
for a placeholder, the call is refused with MCP_UPSTREAM_AUTH_REFUSED and
nothing is sent to the server.
Passing on the caller's headers
Nothing the caller sends is passed on by default. To pass a header on, list it
under Forward Client Headers, for example X-Tenant-Id. Only the headers
you list reach the server. A listed header the caller did not send is simply
not sent.
What cannot be set
Some headers decide how the request is read, or carry the caller's identity.
They can never be set or passed on: Authorization (except as the credential),
cookies, Host, Content-Length and the other framing headers, connection
headers, the MCP protocol's own headers (Mcp-*), trace headers, and DVARA's
own (X-Dvara-*). A value with a line break is refused, so one header can never
be turned into two. These rules apply when you save the server, when a
configuration file is imported, and again on every call.
What the records show
Records name headers, never their values:
- Each tool call records how DVARA authenticated (
bearer,headerorbasic) and the names of the headers it sent. - Saving a server records the placement and each header's name and kind.
- A refused call records the reason and the header's name.
- Pointing a secret header at another credential, or rotating the credential it names, is recorded with a fingerprint of the old and new value, as for the server's main credential.
An export writes each secret header's reference as ***. Importing the file
back keeps the reference you had.
Where to set it
Open the MCP server's page in Flightdeck and use the Upstream Authentication section. Platform administrators and workspace administrators both have it. A secret header must name a credential that belongs to the server's workspace.