Skip to content

docs: document secret injection and upstream escaping workaround for MCP env values #131

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
johnturcoo wants to merge 1 commit into from
Closed

docs: document secret injection and upstream escaping workaround for MCP env values #131

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 21 additions & 0 deletions src/content/docs/agent-platform/cloud-agents/mcp.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -97,6 +97,27 @@ Pass this file when running a cloud agent:
oz agent run-cloud --environment <ENV_ID> -f my-agent-config.json --prompt "Check for regressions in the last deploy"
```

## Injecting secrets into MCP env values

Values in the `env` (and `headers`) map support two ways to reference [Warp-managed secrets](/agent-platform/cloud-agents/secrets/):

* **Explicit template syntax** — set the value to `{{SECRET_NAME}}`. Oz resolves the named secret and substitutes its value before the MCP server process starts.
* **Implicit key-name match** — if the env key matches a managed secret name and the value contains no `{{...}}` placeholder, Oz injects the secret automatically.

The `{{SECRET_NAME}}` syntax is recommended because it makes the secret reference explicit and works regardless of what default value is set.

### Escaping `{{...}}` when using upstream templating systems

Some systems that trigger cloud agent runs — such as Jira/Atlassian Automation — process `{{...}}` as their own smart-value syntax before the payload reaches Oz. This means a webhook body containing `{{MY_SECRET}}` can arrive at Oz as an empty string, and the MCP server never receives the secret.

**Workaround:** Use JSON unicode escapes for the curly braces:

```json
"MY_ENV_VAR": "\u007b\u007bMY_SECRET\u007d\u007d"

@oz-for-oss oz-for-oss Bot May 22, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 [SUGGESTION] Make this a valid JSON object so readers can copy the example directly into a config file.

Suggested change
"MY_ENV_VAR": "\u007b\u007bMY_SECRET\u007d\u007d"
{
"env": {
"MY_ENV_VAR": "\u007b\u007bMY_SECRET\u007d\u007d"
}
}

```

`\u007b` is `{` and `\u007d` is `}`. The upstream system passes the unicode escapes through unchanged, and standard JSON decoding restores `{{MY_SECRET}}` so Oz can resolve the secret normally.

## Requirements and defaults

* MCP configuration must be valid JSON, or YAML when embedded in a broader agent config file.
Expand Down
Loading