# Credentials

Store one shared secret for an MCP server, so the gateway adds it to every call and no agent ever sees it.

- Who: Admin
- Where: Console or strazactl, and the agent's machine

In short: A server that declares a `static` credential takes one shared secret, which Straza seals with its key-encryption key. The gateway adds it to every upstream call, so no agent ever sees it, and a role can carry its own override. Every view names a stored secret by its fingerprint, never by its value.


The gateway adds the credential a server declares to each upstream call. A static credential is the server's shared secret, or the override of the caller's role. When no credential can be found for a call that needs one, the call fails before it reaches the upstream. Every view identifies a stored secret by its scope and fingerprint, never by its value.

The server's manifest declares whose credential the upstream sees. This page covers the shared secret, `static`:

| The upstream needs | Credential kind | Who completes the next step |
|---|---|---|
| No credential | `none` | You register the server. |
| One shared secret for its calls | `static` | You declare the injection and store the server's secret or a role's override. |
| A token belonging to each person | `token` | You declare the server, and each person pastes their token on their self-service page or runs `straza connect <server>`. |
| A browser sign-in belonging to each person | `oauth` | You configure the provider and declare the server, and each person signs in from their self-service page. |

`none` is the default. [Each caller's own credential](https://docs.straza.ai/guides/serve-mcp-apps/caller-credentials/index.md) covers `token` and `oauth`, and what agents run on there, because an agent cannot finish a browser sign-in.

## Before you start

- An installed server that declares `static`, such as the `scout-tools` server from [Add a server](https://docs.straza.ai/guides/serve-mcp-apps/add-a-server/index.md).
- A login of the server's own admin, of `straza-global-mcp-admin`, or of an admin whose areas include MCP servers.

## Declare the credential

In the console:

In the Add MCP server wizard, pick **One shared secret for this server** on the Credential step and type the secret there. For a server that already runs, change the credential on its page:

Click path in the console: "MCP servers" › "scout-tools" › "Overview" › "Change"

Press the **Change** of the Server authentication card. The sheet saves through a draft, like every change to a server.

With the CLI:

The `credential` block says what kind of secret the server needs and how the gateway renders it. This is the block of the `scout-tools` manifest from Add a server:

```yaml
straza:
  runtime:
    kind: remote
    remote:
      url: http://demo-tools:3001/mcp
  credential:
    kind: static
    inject:
      as: header
      name: X-Demo-Key
      template: "{{secret}}"
```

Installing the manifest says what is missing and what to run:

Terminal, administration:

```sh
strazactl apps install -f scout-tools.yaml
```

You should see: `installed scout-tools (remote runtime). Health: degraded, requires a credential and none is stored. Set one with strazactl apps secret set scout-tools, which asks for the value at a hidden prompt.`

`inject.as: header` is valid only for the `remote` runtime, and `inject.as: env` only for `command` and `oci`, because a stdio process has no headers and a remote server gets no process environment. `template` must contain `{{secret}}`, and the rendered value exists only on the gateway side. The parser refuses a `credential.inject` block with `kind: none` with `credential.inject is forbidden with kind none`. It refuses a static kind without one with a message that names the field, says why, and says what to set. For example, a header inject on a command runtime is refused with "credential.inject.as header needs a remote runtime, because a command or oci runtime starts a process that reads an environment variable and gets no request headers. Use as: env with the variable name the process reads, for example API_TOKEN". The gateway never dials a server that takes a shared secret until that secret is stored, so a freshly installed one lists no tools until then.

A `command` or `oci` server starts with `PATH`, `HOME` and `LANG` from strazad, the manifest's `env` entries and the injected credential, and nothing else from strazad's environment. Secrets strazad reads from its own environment, the store DSN and the metrics token among them, never reach the child. When the server needs a proxy or a certificate variable, put it in the manifest's `env`. The `oci` runtime also passes every `DOCKER_` variable to the docker command line, so a rootless or remote daemon keeps working, and the container never sees them. Because such a server holds its static secret in its environment, give no role a tool that prints the environment, such as `get-env`.

## Set the secret

In the console:

Click path in the console: "MCP servers" › "scout-tools" › "Overview" › "Set one"

**Set one** sits on the row Stored here of the Server authentication card. Type the secret and press **Store it**. The value is stored at once and never rides a draft. Once a secret is stored, the same row offers **Set it again**, which rotates it.

![The Server authentication card with the box that sets the shared secret again](https://docs.straza.ai/shots/server-secret-set-dark.png)

The box that opens under **Stored here**, where you type the secret and press **Store it**.

A role's override goes on the row Per-role secrets: press **Add one for a role**, pick the role under `Pick an application role`, type its secret and press **Store it**.

With the CLI:

Without `--role`, the command sets the server's shared secret. Run in a terminal, it asks for the value at a hidden prompt, so the secret never lands in a command line that shell history keeps.

Terminal, administration:

```sh
strazactl apps secret set scout-tools
```

```text
Secret for the MCP server scout-tools (input hidden):
secret set for the MCP server scout-tools: the server's own secret, fingerprint 19c6
```

A script fills `STRAZA_SECRET_VALUE` from its secret manager instead, and the command then reads it without a prompt. `--value` also works, but it puts the secret in the process arguments and the shell history.

The server turns `running` within seconds:

Terminal, administration:

```sh
strazactl apps list
```

```table
NAME         VERSION  RUNTIME  STATUS   REASON  SOURCE  TOOLS  REACHED BY  CHECKED
scout-tools  0        remote   running  -       api     3      -           4s ago
```

The listing is trimmed to the one server. Setting the secret again with the same command rotates it. A role's override is the same command with `--role`, and the role must exist first, as [Access per role](https://docs.straza.ai/guides/serve-mcp-apps/catalogs-per-role/index.md) creates it:

Terminal, administration:

```sh
strazactl apps secret set scout-tools --role scout-tools-readers
```

```text
Secret for the MCP server scout-tools, role scout-tools-readers (input hidden):
secret set for the MCP server scout-tools, role scout-tools-readers, fingerprint f0b5
```

The server seals the value with its key-encryption key, stored under the data directory unless `secrets.kekFile` names another path, and keeps only the ciphertext. It answers with a fingerprint, the first four hex characters of the value's SHA-256, so you can tell which value is stored without ever reading it. It probes the server again under the new credential, and a rotation closes the pooled upstream sessions opened under the old value. A role's override is used for that role's calls in place of the server's own secret.

If this fails:

`the MCP server demo-tools declares no credential (credential.kind none), so a secret would never be used. Change the manifest's credential block first.`
: Declare a credential in the manifest, then store the secret.

An override for a business role is refused with a sentence that ends in `Set the secret for an application role instead, or for the server itself.`, because a business role reaches tools only through the application roles it composes. An override for an approver role or a Straza role is refused with a sentence that ends in `cannot hold a secret`.

## Read what is stored

In the console:

Click path in the console: "MCP servers" › "scout-tools" › "Overview"

![The scout-tools server page, Overview tab, with the Server authentication card](https://docs.straza.ai/shots/server-overview-dark.png)

The **Server authentication** card, with the type, how the secret is sent and its fingerprint under **Stored here**.

The Server authentication card shows the type and how the secret is sent. Its row Stored here gives the time the secret was set, its fingerprint and `Never shown again.`, and its row Per-role secrets gives one line per role with the fingerprint. On a server that pins its objects, the row Listing credential reads `Stored, sealed` once one is stored. No row shows a value.

With the CLI:

Terminal, administration:

```sh
strazactl apps show scout-tools
```

```text
SECRETS
SCOPE  ROLE                 KIND    FINGERPRINT  SET
app    -                    static  19c6         2026-10-06T21:08:38Z
role   scout-tools-readers  static  f0b5         2026-10-06T21:09:02Z
```

The output is trimmed to the secrets table.

No endpoint reads a secret back. The value goes in once and is only ever decrypted in memory for an upstream call or a health probe.

## Prove the agent never sees it

CLI only: This check runs on the agent's enrolled machine, where the console has no part.

Drive a governed call through the gateway from a machine enrolled as a holder of the role. The proxy carries the session token, and the gateway resolves the secret in memory, renders the header, calls the server and returns the result:

Agent's machine, client:

```sh
{ printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"docs-example","version":"1"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"scout-tools__echo","arguments":{"message":"hello through the gateway"}}}'; sleep 5; } \
  | straza mcp --harness claude-code
```

```text
{"jsonrpc":"2.0","id":3,"result":{"content":[{"type":"text","text":"Echo: hello through the gateway"}]}}
```

A `sleep` holds the pipe open while the replies come back, because the proxy stops when its input ends. The initialize reply is trimmed from the output. Nothing beyond the echo reached the agent, and the audit record of the call names the credential row that was used, by id, never by value. On your side, the server record the API returns carries health, tool names and the roles that reach it, and no field that holds a stored secret.

## When a session has no secret

Resolution runs role first, then server. The override of the role whose access row allowed the call is used first. On a server that pins its objects, that is the first role by name whose covers line covers the call. When that role has no override, the override of the role whose name sorts first among the session's other roles is used, even though that role did not allow the call. Only when none of the session's roles holds an override for the server is the server's own secret used. When neither exists the call fails closed, the upstream is never contacted, and the agent reads "Straza: the call was not sent to the MCP server scout-tools: app scout-tools requires a credential and none is stored for the server or bound to your roles. An administrator sets one with strazactl apps secret set scout-tools, which asks for the value at a hidden prompt." The health probe resolves the same way, so a server with only per-role rows is probed under the row of the role whose name sorts first.

On a server that pins its objects, a tool whose pinned reach is `credential` names no object in its calls and leaves the limit to the secret the call carries. Straza does not yet check what a role's own secret reaches, so such a tool goes only in a role on every object. The draft refuses it in a role on some, with a sentence that ends `Straza does not check a role's own login yet. Make a role on every repo for it.`, where your server's own type stands in place of repo. A call to such a tool is therefore granted by a role on every object, and its secret follows the order above. ghapp marks no tool this way, because every ghapp tool but `repo_list` names its repository, and `repo_list` is marked `all`.

## The listing credential

A server that pins its objects, as [Limit a role to some objects](https://docs.straza.ai/guides/serve-mcp-apps/limit-a-role-to-some-objects/index.md) pins ghapp's repositories, holds a third kind of stored secret beside its own and the role overrides: the listing credential. Straza calls the server's listing tool itself, in the background, to keep the list of objects a role can pick from, and the listing credential is the token on that call. It is a second token for the server's MCP endpoint, which the server accepts for its listing tool only. It is neither a GitHub token nor a database password: ghapp keeps its GitHub App's key, and adaptive-pg-mcp keeps its own database logins. You make the value, put it in the server's config, and give Straza the same value. ghapp, set up without client credentials, reads it as `GHAPP_MCP_LISTING_TOKEN` beside its own secret `GHAPP_MCP_GATEWAY_SECRET`, and refuses to start while the two are the same.

Straza sends the listing credential on its listing call and on nothing else. No agent's call and no health probe carries it, so the order above never reaches it, and the listing never falls back to the server's own secret or a role's. It is kept apart from the server's own secret because that secret travels on agents' calls, so a leaked listing credential can only list names. A server that takes no credential needs none, and neither does a server on the `command` or `oci` runtime: Straza lists such a server without one and refuses to store one for it.

In the console:

Click path in the console: "MCP servers" › "ghapp" › "Overview" › "Set one"

The Server authentication card has the row **Listing credential** under **Stored here**. Before the pin it reads `Pin repos first. ghapp has nothing to list for Straza until then.`, with your own server's name and plural, and after it `Not set.` with **Set one**. A value the server already runs with goes in the box after `or paste`, and **Store** sends it. **Generate** fills the box with a random value made in the browser, shown in clear with **Copy** and `Put this value in ghapp's config and restart ghapp, then press Store.` Store it only once the server runs with it, because storing starts a listing that fails until then. Once one is stored, the row reads `Stored, sealed` with **Set it again** and **Remove**, and with the fingerprint until you leave the page.

With the CLI:

Store it once the pin is published, with the same command and `--listing`, which asks for the value at a hidden prompt too: `strazactl apps secret set ghapp --listing`. `strazactl apps secret remove ghapp --listing` removes it.

A server that pins nothing refuses it with `ghapp pins no object type, so a listing credential has no use. Pin its objects first with strazactl apps objects draft ghapp, then publish the draft.` The answer names the fingerprint and never the value, as for the other secrets. Each set and each removal writes its `apps.secret.set` or `apps.secret.remove` record with the scope `listing`. The SECRETS table of `strazactl apps show` lists the server's own secret and the role overrides only, and a missing listing credential shows on the server's Repos tab and in `strazactl apps objects ghapp` instead.

## Remove a secret

A secret is removed on its own, without touching the server. Removing the server's own secret leaves every role's override stored. Each removal is an audit record with the actor. With no secret left, the server reads `degraded` again, with the same reason as before the first set.

In the console:

On the Server authentication card, press **Remove** on the row of the secret, then **Remove secret**. The dialog says what changes first, such as `Calls by scout-tools-readers fall back to the shared secret, or run without one when none is stored.`

With the CLI:

Terminal, administration:

```sh
strazactl apps secret remove scout-tools --role scout-tools-readers
strazactl apps secret remove scout-tools
```

```text
removed the secret for the MCP server scout-tools, role scout-tools-readers
removed the server's own secret for the MCP server scout-tools
```

Removing a row that is not there answers "no secret is stored for the MCP server scout-tools (role scout-tools-readers)".

## Keep secrets out of the manifest

Straza stores each server's manifest in plain text, exactly as it was written. The database, every backup of it and a file in the apps directory therefore hold every environment value, argument and address of a manifest in clear, and the host's process list shows a command server's arguments. Straza shows these values masked, as `[REDACTED]`, `?…` and `#…`, on the admin API, in `strazactl apps export`, on the console, in a health reason and in the server log. That covers every environment value, every value and default in the server block, each argument or other value the secret scan reads as a secret, and the user part, the query, the fragment and a generated path part of every address. A value the scan does not flag still prints in the server log when the server itself writes it there. Keep a secret in a stored credential with `credential.inject`, which Straza keeps encrypted. Straza injects one secret per server, as a header or an environment entry.

The gateway never forwards the agent's own `Authorization` header upstream. That header carries the Straza session token, which has no business at the server, and the injected header wins even when a client sends one. A server that expects the client's own bearer therefore needs the `oauth` or the `token` kind, where the credential is the person's, as [Each caller's own credential](https://docs.straza.ai/guides/serve-mcp-apps/caller-credentials/index.md) shows.

## Next

[Access per role](https://docs.straza.ai/guides/serve-mcp-apps/catalogs-per-role/index.md) gives a role the server's tools.


Walked on v1.1.0-117-g106081a8 on 2026-10-06, except the console steps, read from the console's source. A throwaway standalone server in an Alpine container on Linux, beside the demo stack's MCP reference server, with strazactl on an admin API token minted in the console and the gateway call made through straza mcp from alice's enrolled machine in a second container. Every CLI step ran. The console steps were read from the console's source and not clicked. Console screenshots show strazad v1.0.0-1753-ga27c516c, standalone.

