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.
On this page
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-adminorstraza-global-mcp-admin. The CLI and the API also take an admin API token with theapps:writescope. The holder of one server’s own admin role seesAdd 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/mcpworks 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 lists this beside the other differences between the profiles.
Describe the server
- MCP servers
- Add MCP server
The Server step with the name scout-tools, the card A server you run, over HTTP and the address Straza dials. Show the whole screenThe 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.The example uses the
demo-toolsserver of the demo stack and registers it again asscout-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.nameis the server’s identity in policy and the prefix of its tool names on the wire. Straza keeps theserverblock, the server’s registry record, as data. What Straza needs sits in thestrazablock.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.yamlYou should see
scout-tools.yaml: app OKThe 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
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.
One shared secret for this server picked, with the box for the secret under the cards. Show the whole screen 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 readsNo 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 tokenandUse this server's shared secretEach caller’s own sign-in Get nothing,Run on their sponsor's sign-in, the default, andUse a shared accountA fold under the cards,
More about this choice, holds the long form of the chosen card and of each agent choice.Your manifest declares its credential in
straza.credential: one shared secret,kind: static, sent as the headerX-Demo-Key. You store the secret after the install.Credentials explains the shared secret, and Each caller’s own credential explains the token and sign-in kinds, the agent choices and the provider block of the config.
Publish the server
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.
The foot of Review, with what will happen and the buttons Save draft and Save and publish. Show the whole screen Installing validates locally first, so a bad manifest fails offline, and then uploads it.
strazactl apps install -f scout-tools.yamlYou 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 shows. A manifest with no credential block, like the demo stack’s own
demo-tools, printsHealth: runningand 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
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:
- 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 Tools tab right after the install, with every tool the server lists and no role that reaches one yet. Show the whole screen The listing carries the reason and the roles that reach each server. A long reason is cut to its column, and
strazactl apps showprints it whole.strazactl apps listNAME 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 agostrazactl apps show scout-toolsis 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 readsdegradedwith the missing credential as the reason, andtools: none known. Under ACCESS it saysno role has access to scout-tools. Create one with strazactl roles create scout-tools-<word> --app scout-tools --tools <tool,...>., and under SECRETS it saysnone stored.strazactl apps tools --app scout-toolslists the tools with their upstream descriptions.strazactl apps logs scout-toolsprints the server’s recent runtime lines, oldest first, 100 unless--limitsays 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 shows.If this fails
requires a credential and none is stored- Store the server’s secret, as Credentials 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: truein 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
Once the server runs, the Check step says
Nobody reaches scout-tools yet.and offers one button:- Create a role for scout-tools
The Check step once the server runs, with the tools it found, the line Nobody reaches scout-tools yet.and the button. Show the whole screenNew role opens on Application role with
scout-toolspicked. 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 foldThe same as commandsunder the button holds the same role as onestrazactl roles createline.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 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 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 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 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.
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:
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 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 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_listis 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 ghappsays 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 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 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 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.
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
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:
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.
- MCP servers
- scout-tools
- Remove server
- Remove server…
The console publishes the removal through a draft. Save draft in the same dialog keeps it as a draft for later.
strazactl apps remove scout-tools
You should see
removed scout-tools, and nothing of it stays in strazactl apps list.
Next
Credentials 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.