# Add a server

Register an MCP server, check that Straza reaches it, and give a role access to its tools.

- Who: Admin
- Where: Console or strazactl

In short: Registering an MCP server tells Straza how to reach it and which credential to add to its calls, and gives nobody access. Straza checks the connection and creates the server's own admin role with it. A session sees the server's tools only once a role it holds has access to them.


Registering a server tells Straza how to reach it and which credential to add to its calls. It gives nobody access. A session sees the server's tools only once a role it holds has access to them, and a catalog preview shows the result.

## Before you start

- A login that may install MCP servers: a holder of `straza-admin` or `straza-global-mcp-admin`. The CLI and the API also take an admin API token with the `apps:write` scope. The holder of one server's own admin role sees `Add MCP server is not available to this account.`
- An address the Straza server reaches. Test it from the Straza host or container, because your browser can take a different network path. A Compose service address such as `http://demo-tools:3001/mcp` works only from the Compose network that provides it.

Some addresses Straza never dials, whatever the network allows: a link-local address, a cloud metadata address, and an unspecified address such as `0.0.0.0`. Under the enterprise profile it also refuses a loopback address, such as `127.0.0.1` or `localhost`, unless `apps.allowLoopbackUpstreams` is true. The standalone profile allows loopback by default, because a server there often runs on the same machine. Private addresses always pass. The check runs on every address a name resolves to, so a name that points at a refused address is refused like the address itself. The install still succeeds, and the server stays degraded with a sentence that names the address and why. [Standalone and enterprise compared](https://docs.straza.ai/reference/standalone-and-enterprise/index.md#loopback) lists this beside the other differences between the profiles.

## Describe the server

In the console:

Click path in the console: "MCP servers" › "Add MCP server"

![Add MCP server, step Server, with the name scout-tools and the URL of a server you run over HTTP](https://docs.straza.ai/shots/server-add-server-dark.png)

The Server step with the name `scout-tools`, the card **A server you run, over HTTP** and the address Straza dials.

The wizard has four steps: Server, Credential, Review and Check. On Server, type the name, then pick how Straza reaches the server:

| Card | What the card says |
|---|---|
| A server you run, over HTTP | Straza proxies streamable HTTP to it and checks health with an MCP ping. |
| A command Straza starts | A process Straza starts on its own host as its own user. It can read Straza's keys and data, so use it only for code you trust. |
| A container Straza runs | An image Straza runs with docker on the strazad host, restarted with backoff. |
| A registry server.json | Paste the MCP registry record. Straza converts it the way strazactl apps import does and fills the cards above. |

For a server you run, enter its address. The step checks the manifest it writes on the server as you type. Under the enterprise profile the command card is off and reads `Not available on this server: the enterprise profile does not run servers inside Straza. Run it as its own service or pod and pick HTTP.`

With the CLI:

The example uses the `demo-tools` server of the [demo stack](https://docs.straza.ai/evaluate/try-it-on-the-demo-stack/index.md) and registers it again as `scout-tools`. Its address is reachable from Straza on the Compose network and from no other host, so put your own endpoint in its place on another deployment.

`metadata.name` is the server's identity in policy and the prefix of its tool names on the wire. Straza keeps the `server` block, the server's registry record, as data. What Straza needs sits in the `straza` block.

Terminal, administration:

```sh
cat > scout-tools.yaml <<'EOF'
apiVersion: straza.dev/v1beta1
kind: App
metadata:
  name: scout-tools
  description: Copy of the demo MCP server, with a header credential
server:
  name: scout-tools
  version: "0"
straza:
  runtime:
    kind: remote
    remote:
      url: http://demo-tools:3001/mcp
  credential:
    kind: static
    inject:
      as: header
      name: X-Demo-Key
      template: "{{secret}}"
  exposure:
    tools: ["echo", "get-sum", "get-env"]
EOF
strazactl spec validate app -f scout-tools.yaml
```

You should see: `scout-tools.yaml: app OK`

The manifest names three tools in `exposure.tools`, because the upstream serves more than these guides use.

The name becomes part of every tool name, such as `scout-tools__echo`, so a server cannot be renamed later.

## Choose whose credential Straza adds

In the console:

On Credential, pick one of four cards. Each card has one line, and the chosen card's fields open in a box below them:

| Card | Its line |
|---|---|
| None | The server takes no credential. Straza's audit still says who called. |
| One shared secret for this server | One secret for everyone, kept sealed by Straza. The server sees one identity. |
| Each caller's own token | People paste their own vendor token once. The server sees each person. |
| Each caller's own sign-in | People sign in once through keycloak. The server sees each person. Your provider's name stands in place of keycloak. |

![Add MCP server, step Credential, with One shared secret for this server and the secret box](https://docs.straza.ai/shots/server-add-credential-dark.png)

**One shared secret for this server** picked, with the box for the secret under the cards.

For one shared secret, type the secret in the box. On a command or container server the two caller cards are off and read `Not on a command or container server: one process is one identity.` When strazad has no identity provider configured, the sign-in card is off and reads `No identity provider is configured on this server, so nobody can sign in through one yet. Add oauth.providers.<name> to the strazad config first, or use one shared secret.`

The two caller cards also ask what agents with no token or sign-in of their own run on:

| Card | Choices for agents |
|---|---|
| Each caller's own token | `Get nothing`, the default, `Run on their sponsor's token` and `Use this server's shared secret` |
| Each caller's own sign-in | `Get nothing`, `Run on their sponsor's sign-in`, the default, and `Use a shared account` |

A fold under the cards, `More about this choice`, holds the long form of the chosen card and of each agent choice.

With the CLI:

Your manifest declares its credential in `straza.credential`: one shared secret, `kind: static`, sent as the header `X-Demo-Key`. You store the secret after the install.

[Credentials](https://docs.straza.ai/guides/serve-mcp-apps/credentials/index.md) explains the shared secret, and [Each caller's own credential](https://docs.straza.ai/guides/serve-mcp-apps/caller-credentials/index.md) explains the token and sign-in kinds, the agent choices and the provider block of the config.

## Publish the server

In the console:

On Review, read the summary of what the console sends, then press **Save and publish**. The console publishes the server, stores the secret you typed and checks the connection. **Save draft** adds the server to your working draft instead. When your choice needs a secret, the step then says `Save draft keeps the manifest only. A secret never goes into a draft, so store it on the server's page once the draft is published.` Once the server is published, leaving the wizard does not remove it.

![Add MCP server, step Review, with the manifest it writes and Save and publish](https://docs.straza.ai/shots/server-add-review-dark.png)

The foot of Review, with what will happen and the buttons **Save draft** and **Save and publish**.

With the CLI:

Installing validates locally first, so a bad manifest fails offline, and then uploads it.

Terminal, administration:

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

You should see: One line with the health, the reason and the command that follows from it: `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.`

Store the secret as [Credentials](https://docs.straza.ai/guides/serve-mcp-apps/credentials/index.md#set-the-secret) shows. A manifest with no credential block, like the demo stack's own `demo-tools`, prints `Health: running` and its number of tools at once.

Installing the same name again updates the server in place, which is how you roll out a new version. A paused server takes the update and stays paused until an administrator enables it, and the command says so: `installed scout-tools (remote runtime). Health: stopped. It stays paused: run strazactl apps enable scout-tools to start it with this manifest.`

A manifest whose credential is each caller's own sign-in, through a provider strazad does not know, is refused with `credential.oauth.provider "github" is not configured on this server. Add oauth.providers.github to the strazad config, or pick one of: keycloak.`

## Check the connection

In the console:

The Check step shows what landed and what the server answered. If authentication was refused, correct the credential. If the address is unreachable, check it and the network path, then press **Recheck**. You can leave and finish later on the server's own page:

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

The server's page has the tabs Overview, Tools, Server roles, Activity and Manifest. Overview holds the cards Connection, Server authentication, Tools and limits, and Server administration. Tools lists each tool with its description. Activity holds Straza's own record of the server, and for a command or container server it also shows the process's log.

![The scout-tools server page, Tools tab, with each tool and its description](https://docs.straza.ai/shots/server-tools-dark.png)

The Tools tab right after the install, with every tool the server lists and no role that reaches one yet.

With the CLI:

The listing carries the reason and the roles that reach each server. A long reason is cut to its column, and `strazactl apps show` prints it whole.

Terminal, administration:

```sh
strazactl apps list
```

```table
NAME         VERSION    RUNTIME  STATUS    REASON                                    SOURCE  TOOLS  REACHED BY                                 CHECKED
demo-tools   2026.8.31  remote   running   -                                         api     14     demo-tools-readers,demo-tools-sandbox      16s ago
midpoint     0.3.1-dev  remote   running   -                                         api     27     midpoint-operations,midpoint-self-service  16s ago
scout-tools  0          remote   degraded  requires a credential and none is stored  api     0      -                                          1s ago
```

`strazactl apps show scout-tools` is one read of the server: its health with the full reason, its tools, the role that administers it, every access row with how each tool runs for that role, and the stored secrets by fingerprint. Right after the install it reads `degraded` with the missing credential as the reason, and `tools: none known`. Under ACCESS it says `no role has access to scout-tools. Create one with strazactl roles create scout-tools-<word> --app scout-tools --tools <tool,...>.`, and under SECRETS it says `none stored`. `strazactl apps tools --app scout-tools` lists the tools with their upstream descriptions.

`strazactl apps logs scout-tools` prints the server's recent runtime lines, oldest first, 100 unless `--limit` says otherwise. For every server they hold Straza's connection attempts and status changes. For a command or container server they also hold what the process wrote to its standard error.

A server that has never answered a probe has no tool list to serve, so its tools are missing from every catalog. A server that answered once and then turned degraded keeps serving the list it last reported, and the call itself fails with the reason. Straza creates the server's own admin role, `mcp-admin-scout-tools`, with the server, and the console shows it on the Server administration card. Give it to the people who own the server, and they administer it without administering the rest of Straza, as [Delegated admin](https://docs.straza.ai/guides/operate/delegated-admin/index.md) shows.

If this fails:

`requires a credential and none is stored`
: Store the server's secret, as [Credentials](https://docs.straza.ai/guides/serve-mcp-apps/credentials/index.md) shows. The server turns running within seconds.

`Straza does not dial 127.0.0.1 for the server scout-tools because it is a loopback address on strazad's own host. An administrator publishes an address other machines can reach, or sets apps.allowLoopbackUpstreams when strazad runs beside the server on purpose.`
: Register the server at an address other machines reach. When strazad runs beside the server on purpose, set `apps.allowLoopbackUpstreams: true` in the strazad config and restart strazad.

`Straza does not dial 169.254.169.254 for the server scout-tools because it is a cloud metadata address, which reaches the metadata service of strazad's cloud. An administrator publishes an address other machines can reach.`
: No setting lifts this refusal. Give the server a private or a public address.

`this server cannot run containers (no docker on the strazad host). Use the remote or command runtime, or run strazad where docker is installed.`
: Install docker on the strazad host, or run the server yourself and register it over HTTP. Under the enterprise profile the sentence names the remote runtime alone.

## Give a role its tools

In the console:

Once the server runs, the Check step says `Nobody reaches scout-tools yet.` and offers one button:

Click path in the console: "Create a role for scout-tools"

![Add MCP server, step Check, with the connection result and Create a role for scout-tools](https://docs.straza.ai/shots/server-add-check-dark.png)

The Check step once the server runs, with the tools it found, the line `Nobody reaches scout-tools yet.` and the button.

New role opens on Application role with `scout-tools` picked. Type the word that completes the role's name after the server's name, then tick the tools on the Access step and say which calls need a person's approval. The fold `The same as commands` under the button holds the same role as one `strazactl roles create` line.

With the CLI:

Terminal, administration:

```sh
strazactl roles create scout-tools-readers --app scout-tools --tools echo,get-sum --description "Tool access to the scout-tools server"
```

An application role that reaches a server belongs to that server, so the identity manager shows it as that server's role. Assign the role to the person or agent through Users or your identity manager. [Access per role](https://docs.straza.ai/guides/serve-mcp-apps/catalogs-per-role/index.md) walks this step and checks which tools the holder's session can call and which need approval.

## When the server's tools change

Straza reads each server's tool list at every health check, every 20 seconds by default, and at once when you press **Recheck** or run `strazactl apps recheck scout-tools`. It does not act on a server's own notice that its tool list changed, so a tool that a server adds, removes or changes shows up in Straza within one health check. A remote server is checked each time, and a command or container server while its process runs. `apps.healthInterval` in the config file sets the pace.

Straza compares the names, descriptions, input schemas and `ai.straza/` marks of the tools with the last list it read. When anything differs, the server reads `degraded` until the next health check, with a reason that starts `inventory drift:` and names the tools added and removed, and Straza records `straza.apps.drift`. Calls to the server go on meanwhile, and it reads `running` again at the next check that finds no further change.

The gateway builds each session's tool list from the new list at once, and within about a second it tells every open session that its list changed. A removed tool leaves every tool list, and a call to it gets the unknown-tool answer. A new tool reaches a session only when the manifest's exposure lets it through, as `tools: ["*"]` does, and an access row of one of the session's roles names it, as a row on every tool and tools added later does.

`straza mcp` on the agent's machine lists again at a random moment within 5 seconds of that notice, so a fleet of sessions does not list all at once. It then changes its own tool list, which tells the coding tool that the list changed, and a coding tool that acts on that notice shows the change in the running session. A notice can be lost on a slow connection, so `straza mcp` also lists again every 10 to 11 minutes.

On a server that pins its objects, as [Pin the objects a server reaches](#objects) explains, a changed tool can also narrow who may call it. A new tool that the pinned copy does not name reads as reaching every object, so only a role on every object may call it until a person pins again. A tool whose mark or input schema no longer matches its pinned reach is refused to roles on some objects, with a sentence such as `pr_create on ghapp changed how it names its repo since an admin pinned it, so roles on some repos cannot use it until an admin publishes the change. Ask an admin to review ghapp's Repos tab.` Roles on every object keep calling it. The server's object tab and `strazactl apps objects ghapp` then say `ghapp's marks differ from the pinned repos. Draft the change with strazactl apps objects draft ghapp.`

## Pin the objects a server reaches

Some servers reach many separate things with one credential. ghapp, a GitHub App server, is one: it reaches every repository the App is installed on. Its tools say so in their tool list. Each tool that works on one repository marks its argument `repo` as the one that names it, and `repo_list` marks itself as the tool that lists them all. Straza reads those marks and acts on them only once a person pins them in the server's manifest, under `straza.objects`. [Object marks for server authors](https://docs.straza.ai/reference/object-marks/index.md) is the reference for the server's author. A pinned server then gets a tab named with the server's own word, here Repos, that lists each repository with its attributes, the roles that cover it and its id.

From the pin on, the gateway checks every call to the server against the repositories each role covers. At the first pin no role loses or gains a repository, because the draft that pins a server for the first time gives every role that already reaches it `covers: every`, the reach it had. Its check says so in a line such as `Pinning repos on ghapp keeps today's reach: ghapp-readers now covers every repo. Narrow it in this draft or later.` A role on every repository keeps working before the first listing too, because `every` also covers the repositories the list does not hold yet. Two things do change for every role. Straza refuses a call whose `repo` argument it cannot read, such as one that sends `repo` twice or leaves it out, and an approval or ticket given before the pin, for a tool that names its repository, is asked for again, because the approval then carries the repository.

Add the server first, as the steps above do, and pin its objects in a later publish. A manifest that starts a server and pins the block in one publish can meet a server that is still starting, and that first listing then fails and runs again in about a minute. For ghapp the first listing after the pin fails on the missing listing credential in any case, and storing the credential lists again with no refresh, as the failures under the listing below explain. On a running server that pins nothing, **Pin repos** on its Overview opens a draft whose manifest pins the `straza.objects` block its marks declare. The button carries the server's own word, and [Limit a role to some objects](https://docs.straza.ai/guides/serve-mcp-apps/limit-a-role-to-some-objects/index.md) walks its dialog. From a terminal, `strazactl apps objects ghapp` prints that block, and `strazactl apps objects draft ghapp` opens the same draft, with you as its proposer. You publish it as any other draft. A change under `straza.objects` alone never restarts the server. The draft's check compares the block with the server's live tools. The listing tool must be marked read-only, each argument the block names must be a required string argument of its tool, and no tool may be pinned looser than the server's own mark. A tool the block leaves out reads as reaching every repository, and the check lists it under `Needs a decision`. ghapp's whole block, as a manifest file holds it, is in [The apps directory](https://docs.straza.ai/guides/serve-mcp-apps/gitops-apps-directory/index.md#objects).

A remote server whose manifest names a credential, as ghapp's does, needs a listing credential of its own. Straza calls the listing tool with that credential and nothing else, and it never sends it on a tool call or a health probe. Without one the listing fails and says so, because Straza never falls back to the server's own secret or a role's. A server on the `command` or `oci` runtime, or a remote one that takes no credential, keeps none. Store the listing credential once the pin is published, because a server that pins nothing refuses one. For ghapp it is the value of its `GHAPP_MCP_LISTING_TOKEN`, which ghapp accepts on `repo_list` alone. In the console it goes in the row **Listing credential** of the Server authentication card, where **Generate** can make a value for you to put in the server's config before you press **Store**. The command asks for the value at a hidden prompt:

Terminal, administration:

```sh
strazactl apps secret set ghapp --listing
```

Until one is stored, the pin's draft warns `ghapp has no listing credential, so Straza cannot list its repos, and only roles on every repo can use its repo tools until it has one. After you publish, set one under Server authentication on the Overview of ghapp, or with strazactl apps secret set ghapp --listing.` [Credentials](https://docs.straza.ai/guides/serve-mcp-apps/credentials/index.md#listing-credential) sets it beside the server's other secrets.

Straza lists the repositories every 10 minutes, within about 15 seconds after a publish that pins or changes the block, and at once when the listing credential changes. One replica lists at a time, and every other replica holds the new list within 30 seconds. A listing that fails, or that breaks a limit such as 100,000 repositories per server, changes nothing, and the last good list stays. `strazactl apps objects refresh ghapp` asks for a listing now, and so does `POST /v1/admin/apps/{id}/objects/refresh`. On the Repos tab, **List again** does the same when the last listing failed and the listing credential is stored. A call that names a repository the list does not hold asks for one as well, and the two share a limit of one a minute per server. Each listing that changes the list, and each listing whose outcome turns from success to failure or back, writes `apps.objects.list` to the audit log. In the console the tab is under **MCP servers**, then the server, and it shows the last listing, a failure's reason and what the server's marks declare. `apps.objects.enabled`, true by default, can be set to false to stop every listing, and [Configuration](https://docs.straza.ai/reference/configuration/index.md#config-apps) says what it does to the roles on such a server.

If this fails:

`ghapp has no listing credential, so Straza cannot list its repos. Set one on its server page under Server authentication, or with strazactl apps secret set ghapp --listing. Then press List again on its repos tab, or run strazactl apps objects refresh ghapp.`
: Store the listing credential. Storing it starts a listing at once, so **List again** or the refresh is needed only when that listing failed too.

`ghapp is not running, so Straza could not call repo_list. Start it, then refresh.`
: When the listing ran, the server was still starting or had failed to start, or someone had paused or stopped it. One publish that adds a server and pins its objects can meet the first case, and Straza then lists it again in about a minute. A server that failed to start is tried again each minute too. A paused or stopped server is listed again 10 minutes after the failed listing, so once ghapp runs again, press **List again** on its Repos tab or run `strazactl apps objects refresh ghapp`.

`ghapp refused the listing credential with HTTP 401 Unauthorized, so Straza could not list its repos. ghapp's own config must hold the value Straza stores: put it there and restart ghapp, or store a new value under Server authentication on its server page and give ghapp that one. Then press List again on its repos tab, or run strazactl apps objects refresh ghapp.`
: ghapp did not accept the value Straza sent, as when the value was stored before ghapp ran with it. A server that checks its token on every request refuses it before the listing tool runs. Straza lists again 10 minutes later, so once ghapp holds the value, press **List again** on its Repos tab.

`Straza has not read ghapp's tool list yet, so it cannot check repo_list before it lists ghapp's repos. It tries again in about a minute. If ghapp stays degraded, read why with strazactl apps show ghapp.`
: Straza started ghapp, but ghapp has not answered its tools probe yet, so Straza cannot tell whether `repo_list` is there and marked read-only. A start that failed reads the same way. Straza lists ghapp again in about a minute, and you do not need to refresh it. When ghapp does not come up, `strazactl apps show ghapp` says why.

## Limit a role to some repositories

Once a server pins its repositories, each role's access row on it says which of them it covers: `covers: every`, or `covers: {objects: [...]}` with each repository named. [Access per role](https://docs.straza.ai/guides/serve-mcp-apps/catalogs-per-role/index.md#covers) writes both forms, lists what a draft refuses and says what the gateway does on each call.

## Serve git through Straza

A server that holds a git host's credential, such as ghapp, can also serve git to agents that run plain git. Its manifest then carries a `straza.git` block with the server's git address, the git host it serves and the tools that decide a fetch and a push, and the objects block pins both tools to the argument that names the repository. [Git through Straza](https://docs.straza.ai/guides/serve-mcp-apps/git-through-straza/index.md) writes the block for ghapp and gives roles the two tools.

## Runtimes, limits and timeouts

`runtime.kind` selects exactly one of three runtimes, and the manifest is invalid when the matching block is missing or a second one is present.

| Kind | Block | How Straza runs it |
|---|---|---|
| `remote` | `remote: {url, auth}` | streamable HTTP to a server you run, health by MCP ping |
| `command` | `command: {exec, args, env, workdir}` | a child process over stdio, restarted with backoff, refused under the enterprise profile |
| `oci` | `oci: {image, sandbox, env}` | a container over stdio, which installs but stays `degraded` and never starts where strazad finds no docker |

A `command` server is a process of strazad itself, on strazad's host and as strazad's user, so it can read Straza's keys and data. The enterprise profile therefore refuses the `command` runtime, with no setting to turn it back on. An install or a draft that names one is refused with a sentence that says why, a stored one stays `degraded` and never starts, and `/version` leaves `command` out of its `runtimes`. Run such a server as its own service or pod and add it as `remote`. The standalone profile still runs `command` servers, so use one there only for code you trust.

`oci.sandbox` is `default` unless you set it. The default runs the container with a read-only root file system, every capability dropped, no new privileges, at most 256 processes and no network. `sandbox: none` runs the image with docker's own defaults, which gives the container a network and a writable file system.

`remote.auth` is `inject` unless you set it, and the gateway then adds the credential that `straza.credential` declares. `passthrough` is reserved for a later token exchange and today means that the gateway adds no credential. In both modes the gateway never forwards the agent's own `Authorization` header, because it carries the Straza session token.

`exposure.tools` caps what exists in any catalog, `["*"]` by default, and a role's access row narrows it further. `limits.rps` bounds the calls of one session to the server at the gateway. `limits.timeoutSeconds` caps one upstream call, and without it the server-wide `apps.upstreamTimeout` applies, 30 seconds by default. `limits.cpu` and `limits.mem` are parsed and stored, and nothing enforces them yet. strazad checks each server's health and compares its tools with the last list every `apps.healthInterval`, 20 seconds by default. Both server-wide settings live in the strazad config file, and [Lifetimes and timeouts](https://docs.straza.ai/reference/lifetimes-and-timeouts/index.md#mcp-servers) lists them with the other intervals.

## Import a registry record

`strazactl apps import` turns an MCP Registry entry, its `server.json`, into a manifest without touching the server. Its first `streamable-http` remote becomes a `remote` runtime, a stdio container package becomes `oci`, an npm or PyPI package becomes `command`, and exactly one secret header or variable becomes the credential declaration, a static credential. A record with two secrets is refused. When a record offers several, the remote wins, then the container, then npm, then PyPI. `--runtime remote`, `--runtime oci` or `--runtime command` restricts the choice to one kind, and the import fails with a sentence such as `registry import: no stdio oci package in server.json` when the record has none. Under the enterprise profile, a record whose only package is npm or PyPI converts to a `command` server, which the install then refuses. In the console, the card `A registry server.json` runs the same conversion and fills the wizard's cards.

Terminal, administration:

```sh
cat > server.json <<'EOF'
{
  "name": "io.modelcontextprotocol/server-everything",
  "description": "Reference MCP server exercising every protocol feature.",
  "version": "2026.7.4",
  "remotes": [
    {
      "type": "streamable-http",
      "url": "http://demo-tools:3001/mcp",
      "headers": [
        { "name": "X-Demo-Key", "value": "Bearer {demo_key}", "isSecret": true }
      ]
    }
  ]
}
EOF
strazactl apps import server.json --name scout-imported
```

```text
apiVersion: straza.dev/v1beta1
kind: App
metadata:
    name: scout-imported
    namespace: io.modelcontextprotocol
server:
    name: io.modelcontextprotocol/server-everything
    version: 2026.7.4
straza:
    runtime:
        kind: remote
        remote:
            url: http://demo-tools:3001/mcp
            auth: inject
    credential:
        kind: static
        inject:
            as: header
            name: X-Demo-Key
            template: Bearer {{secret}}
    exposure:
        tools:
            - '*'
```

That output is trimmed of the verbatim `server` fields the input carried. Write it to a file with `-o`, review it, and install it as above.

## Register through the API

The API takes the manifest as the request body and answers with the server's record. The same request with `?dryRun=1` validates the manifest without installing anything, which is what the wizard's Server step does as you type. `ADMIN_API_TOKEN` holds an admin API token minted with `strazactl api-token create --name docs --scope apps:write`:

```sh
curl -s -X POST http://localhost:8420/v1/admin/apps -H "Authorization: Bearer $ADMIN_API_TOKEN" \
  -H 'Content-Type: application/yaml' --data-binary @scout-tools.yaml
```

The answer is one JSON object: the server's `id`, `name`, `version`, `runtime`, `status` and `source`, the reason in `detail`, the probe times, `reached_by` with the roles that reach it, its server admin role in `admin_role` and `admin_role_id`, and its `tools` once a probe has listed them. For this manifest `status` reads `degraded`, `detail` reads `requires a credential and none is stored`, and `tools` is left out until the secret is stored. An invalid manifest answers `422` with the parser's sentence, the same one the CLI prints.

## Remove the server

Removing the server stops its runtime and drops its tools from every catalog. It removes the server's access rows and every stored credential, the per-user sign-ins included, so a server installed again under the same name starts with none. It also deletes the server's admin role and every role the server owns, with their memberships. The removal is an audit record that names who did it and which roles lost access.

In the console:

Click path in the console: "MCP servers" › "scout-tools" › "Remove server" › "Remove server…"

![The Remove server confirmation on the demo-tools page](https://docs.straza.ai/shots/server-remove-dark.png)

The same question on the server demo-tools, with **Save draft** beside **Remove server…**.

The console publishes the removal through a draft. **Save draft** in the same dialog keeps it as a draft for later.

With the CLI:

Terminal, administration:

```sh
strazactl apps remove scout-tools
```

You should see: `removed scout-tools`, and nothing of it stays in `strazactl apps list`.

## Next

[Credentials](https://docs.straza.ai/guides/serve-mcp-apps/credentials/index.md) stores the secret this server waits for.


Walked on v1.1.0 on 2026-09-28, except the console steps, read from the console's source. Linux, against the enterprise demo stack, with strazactl logged in as an administrator and curl from the host. The server was installed under a name of the tester's own, and the install, list and removal lines shown here match what it printed apart from that name. The console steps were read from the console's source, not run in a browser. Console screenshots show strazad v1.0.0-1753-ga27c516c, standalone.

