MCP setup templates

Botyard's MCP catalog gives teams a repeatable way to create MCP servers without starting from a blank form every time.

The catalog can contain:

• Botyard Builtin entries maintained by Botyard, such as common server images or hosted integrations.
• Custom Template entries created for your organization.
• Custom, which opens the full MCP setup form for a one-off server.

You can search the catalog and filter it by Source (the three kinds above) and Pricing.

Creating from the catalog

Open User menu › Settings › MCP Servers › Browse MCP catalog, choose a catalog entry, and review the create form before submitting it. Catalog entries prefill the same fields used by manual setup: name, description, runtime kind, image or endpoint, command, args, port, and environment variables.

Creating from a catalog entry still creates a normal MCP server owned by your organization. You can inspect it, edit supported configuration, and delete it like any other server.

Botyard also stores the catalog source name, logo, form spec version, and setup form shape on the MCP server when it is created. That lets the edit page keep showing a Snowflake-style configuration form, with the Snowflake logo and field labels, instead of reverting to raw MCP runtime settings later.

Template forms

Some catalog entries may show a smaller setup form tailored to that template. For example, a Snowflake template can ask for account, user, database, warehouse, and key material instead of exposing raw environment variables.

Those forms are compiled into the normal MCP server configuration before the server is created. This means the runtime behavior stays consistent whether the server came from a curated template or from the full Custom form.

Template JSON also declares which low-level settings are locked by the catalog entry. A locked template can hide runtime kind, image, port, transport, launch arguments, and the raw environment editor while still using those values behind the scenes. The NMAP scanner is an example: its image, port, transport, launch settings, and environment are fixed by the template, so there are no setup fields to fill in.

Plain values and secret references

For credentials and other sensitive settings, a template can let you choose how to provide the value:

• paste the value directly into the setup form
• reference an existing Runtime Vault key path

Both choices configure the same environment variable in the MCP server. Botyard stores the result in only one place:

{
  "env_plaintext": {
    "CLIENT_ID": "abc"
  },
  "env_secret_refs": {}
}

or:

{
  "env_plaintext": {},
  "env_secret_refs": {
    "CLIENT_ID": "mcp.snowflake.client_id"
  }
}

The same environment variable cannot be both a pasted value and a secret reference.

Changing a value that is linked to the vault

On some catalog integrations, credential fields can be linked to Runtime Vault variables. Typing a new value into a linked field updates the vault variable itself, not only this server. Before anything is saved, Botyard shows an Update the vault secret? confirmation that lists where the secret is used. Cancel writes nothing. If you aren't allowed to manage Runtime Vault variables, linked fields are locked.

Secret files

Some servers need a credential as a file rather than an environment variable, such as a TLS client certificate or key. Servers that Botyard runs itself (container images and npm or PyPI packages) have a Secret files list, unless the template locks the environment settings. The list (secret_file_mounts) maps an absolute path inside the container to a Runtime Vault key path. When the server starts, Botyard resolves the variable and mounts its value read-only at that path:

{
  "secret_file_mounts": {
    "/etc/mcp-secrets/client.key": "mcp.postgres.client_key"
  }
}

Mount paths must be:

• absolute and normalized (no ., .., trailing, or doubled slashes)
• at least two levels deep, for example /etc/mcp-secrets/ca.crt
• outside /tmp, /var/tmp, /home/mcp, and /spiffe-workload-api
• not nested inside another mount path

Request headers

Servers that Botyard proxies to a vendor-hosted URL send their credentials as HTTP headers. The Request headers list (hidden when the template locks runtime settings) holds two kinds:

• Plain headers (static_headers) are stored and returned as entered. Use them for non-sensitive values such as Accept or an API version.
• Vault headers (secret_headers) map a header name to a Runtime Vault key path. Botyard resolves the value on every request, and the API never returns it.

{
  "static_headers": { "Accept": "application/json" },
  "secret_headers": { "Authorization": "mcp.example.api_token" }
}

Rules:

• Authorization must be a vault header, never a plain header.
• A server can have at most 32 headers, and names must be unique regardless of case.
• Connection-level headers such as Host, Connection, Content-Length, and Proxy-Authorization can't be set.
• Unless the template says otherwise, a vault header's value is sent exactly as stored. For Authorization, store the scheme with the token: Bearer abc123, not just abc123.

Vault headers send your organization's secrets to the server's host. When you create a server with vault headers at a URL you entered yourself, or move one to a different host or port, Botyard asks you to confirm that destination first and records the confirmation in the audit log. Changing only the URL path doesn't need a new confirmation.

Who can use a server

Each MCP server has its own access settings, on the server's Members and Assignments tabs.

• Access mode. This server's members only (the default) limits ordinary access to the server and its tools to the people, bots, and API keys on the member list. Administrators are the exception (see below). Everyone in the organization opens it to every member and viewer, every bot, and every API key. Botyard asks you to confirm before opening a server, and records the change in the audit trail.
• Members. Whoever creates a server becomes its first owner. If a bot creates it, the people on that bot's member list are copied onto the server's list too. Owners can add and remove members, including other owners, but a server always keeps at least one owner. On an open server the list only decides who can change these settings.
• Assignments. Shows which bots hold this server's tools, and how much of the toolset each one holds. Use Add bot to give a bot access.

A server's owners can change its access mode and members. There is one administrative exception: organization owners, anyone granted organization-wide MCP server management, and Botyard platform administrators can see every server and change its access mode and members without being on its member list. A restricted server can therefore always be repaired. Someone who holds only the MCP server management permission can add members but cannot make anyone an owner.

When to use Custom

Use Custom when you need full control over the MCP server definition or when no catalog entry matches what you are deploying. Custom setup exposes the full form instead of a curated template form.

npm-hosted MCP servers

Some MCP servers are distributed as npm packages and documented for local clients as npx -y <package>. Botyard can run these with the shared ghcr.io/botyard-ai/npx-mcp image, which starts the npm package over stdio and exposes Streamable HTTP on /mcp.

For a custom npm-backed server, use a container image runtime with:

{
  "image": "ghcr.io/botyard-ai/npx-mcp:latest",
  "port": 8080,
  "env_plaintext": {
    "NPX_PACKAGE": "example-mcp"
  }
}

Add any provider credentials as environment variables or secret references. For example, the Resend built-in template uses NPX_PACKAGE=resend-mcp and maps your API key to RESEND_API_KEY.

For catalog templates, set packaging_kind: npx. Botyard still creates the server as a container-image MCP under the hood, using the shared npx-mcp image and the same provisioner path as bespoke wrappers.

Python servers published on PyPI work the same way with the shared ghcr.io/botyard-ai/uvx-mcp image, which runs the package with uvx. Set UVX_PACKAGE (and optionally UVX_PACKAGE_VERSION) in env_plaintext.

Related docs

• Runtime Vault
• Manage Botyard with Terraform to declare MCP servers as code

For a product overview, see governed MCP tools on botyard.io.