Credential Vault

A credential vault is a secure repository for centrally managing authentication information for external services. Specific credentials (e.g., API keys, tokens) are stored inside the vault and bound to sessions at creation time, enabling MCP services and skills to reference them at runtime.

Structure

Credentials follow a two-level hierarchy:

• Vault: A container for grouping and managing credentials.
• Credential: A specific secret stored within a vault, consisting of a variable name and its corresponding value.

Creating a Vault

1. On the Credentials page, click Create Vault.
2. Enter a vault name and click Create.

Adding Credentials

After creating a vault, add individual credentials on the vault's detail page:

1. Click the vault name to navigate to its detail page.
2. In the Credential List section, click New Credential.
3. Fill in the following fields:
   • Name: A display name for the credential.
   • Type: Fixed to Environment Variable. The credential is referenced as an environment variable by the agent and replaced with the real value by the gateway at egress.
   • Variable Name: The key used by tools to reference this credential (e.g., MY_API_KEY). Must match ^[a-zA-Z][a-zA-Z0-9_]*$: start with a letter; only letters, digits, and underscores are allowed. Cannot be changed after creation.
   • Variable Value: The actual secret value. After saving, the console and API display only the last 4 digits; the plaintext is never returned, and the value is decrypted and injected server-side only when referenced by tools.
   • Injection Location: Fixed to HTTP request header. The gateway substitutes the placeholder in whichever request header carries it. Placeholders in the request body and query parameters are not replaced.
   • Allowed Hosts: Restricts which hosts receive the real credential—only requests sent to these hosts have the placeholder replaced; all other hosts only see the placeholder. Separate entries with commas or newlines, support *.example.com wildcard subdomains, up to 10 hosts. Enter * to apply to all hosts; acknowledge the risk and confirm.
4. Check the shared credential acknowledgement, then click Create to complete.

Credential Injection Mechanism

Credentials are injected via placeholders + gateway rewriting, so the agent itself never touches the real secret:

1. Placeholder reference: The agent references the credential via the ${VARIABLE_NAME} environment variable in tool or MCP code, and puts the placeholder in the request header that carries authentication. For example, Authorization: Bearer ${MY_API_KEY} or X-API-Key: ${MY_API_KEY}.
2. Gateway rewriting: At egress, the gateway checks whether the target host is in the Allowed Hosts list. On a match, it replaces the placeholder in the request header with the real credential; on no match, it leaves the placeholder as-is, so the target host only receives the placeholder.
3. Scope: Only placeholders in request headers are replaced; placeholders in the request body and query parameters remain untouched.
4. Host matching rules: Exact and wildcard matching; matching is case-insensitive and ignores ports; *.example.com matches its subdomains but not the bare domain example.com — list the bare domain separately.
5. Redirect safety: If a request is redirected (3xx) across domains to a host outside Allowed Hosts, the redirected request is not replaced.

Choosing Allowed Hosts

• * (open): Requests to all hosts are replaced with the real credential, for workloads that don't need to restrict where the credential is sent. Acknowledge the risk and confirm.
• Specific hosts (restricted): e.g. api.example.com, *.example.com. Only requests to matching hosts receive the real credential; all others receive the placeholder, which contains no credential value, so a leaked placeholder does not expose the credential. For cases where the credential should only reach your own services.

Referencing Credentials in Code

No special SDK is required: read the environment variable as usual in tool or MCP code, and put the placeholder in the request header that carries authentication. The value read is a placeholder; the gateway replaces it with the real credential when the request goes to a matching host:

import os, requests

# What you read is a placeholder; no need to know the real value
token = os.environ["MY_API_KEY"]
requests.get("https://api.example.com/v1/data",
             headers={"X-API-Key": token})

If the target service uses Authorization: Bearer, write headers={"Authorization": f"Bearer {token}"} instead.

Difference from Environment Variables

A session can obtain external values in two ways: session environment variables (environment_variables) and vault credentials. Both are read by name as environment variables in code, but they differ in value form and security posture:

Dimension	Session environment variables	Vault credentials
Value inside the container	Real value	Placeholder
When the real value appears	Readable inside the container at all times	Only at the moment the egress gateway matches an allowed host
Domain restriction	None	Only requests sent to allowed hosts are replaced with the real value
Authentication method restriction	None; the value can be used freely in code	Placeholders in request headers are replaced; placeholders in the request body and query parameters are not replaced
Reuse and rotation	Configured per session; changes require a session update	Vaults are reusable across sessions, with centralized updates and rotation
Suitable scenarios	Non-sensitive configuration, or SDKs/skills whose underlying authentication method is unknown	High-sensitivity scenarios where the credential must not leak

• When a third-party SDK or skill carries authentication in the request body or query parameters, the gateway cannot replace it — use session environment variables instead.
• The real value of a session environment variable can be read or printed by code in the container and may enter logs and model context; use a vault for highly sensitive credentials.

Binding to a Session

When creating a session, select an existing vault from the Credential Vault dropdown field. During session execution, MCP services and skills can reference credential values using their variable names.

Next Steps

• Initiate a Session: Bind a vault when creating a session.
• Define an Agent: Attach MCP services or skills requiring authentication to your agent.