Fix/update docs for secrets tags #497
Conversation
WalkthroughAdds cloud secrets documentation and examples, introduces a raw secrets example for cloud, updates multiple example READMEs (formatting and tool lists), significantly rewrites CLI README to simplify deploy/config flows and secret semantics, and removes the older SECRETS.md. No code or API exports changed. Changes
Sequence Diagram(s)sequenceDiagram
autonumber
actor Dev as Developer
participant CLI as mcp-agent CLI
participant Cloud as MCP Agent Cloud
participant App as Deployed App
rect rgb(235, 245, 255)
note over Dev,CLI: Deploy (simplified, config-dir based)
Dev->>CLI: mcp-agent deploy -c <config_dir>
CLI->>CLI: Load config + raw secrets (cloud)
CLI->>Cloud: Create app + register developer secrets
Cloud-->>CLI: app_id, transformed secret refs
CLI-->>Dev: Deployment output (app URL/status)
end
rect rgb(240, 255, 240)
note over Dev,CLI: Configure
Dev->>CLI: mcp-agent configure <app_id|server_url>
CLI->>Dev: Prompt/select user secrets (as required)
CLI->>Cloud: Store user secrets / config instance
Cloud-->>CLI: Configuration complete
CLI-->>Dev: Instance ready
end
rect rgb(255, 250, 235)
note over App,Cloud: Run / Status / Control
Dev->>Cloud: Trigger run / get_status / resume / cancel
Cloud->>App: Launch with resolved secrets
App-->>Cloud: Execution status (may include execution_id)
Cloud-->>Dev: Status/result
end
note right of CLI: New docs emphasize simplified flows and raw cloud secrets example.
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Suggested reviewers
Poem
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ Finishing touches🧪 Generate unit tests
Tip 👮 Agentic pre-merge checks are now available in preview!Pro plan users can now enable pre-merge checks in their settings to enforce checklists before merging PRs.
Please see the documentation for more information. Example: reviews:
pre_merge_checks:
custom_checks:
- name: "Undocumented Breaking Changes"
mode: "warning"
instructions: |
Pass/fail criteria: All breaking changes to public APIs, CLI flags, environment variables, configuration keys, database schemas, or HTTP/GraphQL endpoints must be documented in the "Breaking Change" section of the PR description and in CHANGELOG.md. Exclude purely internal or private changes (e.g., code not exported from package entry points or explicitly marked as internal).Please share your feedback with us on this Discord post. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
examples/workflows/workflow_evaluator_optimizer/README.md (1)
159-173: Confirm README tool names vs actual exportsThe README in examples/workflows/workflow_evaluator_optimizer/README.md (lines ~160-165) uses singular names (
workflow-list,workflow-run-list,workflow-run) which do not match the server/docs usage (pluralworkflows-...and workflow-specificworkflows-<Workflow>-run). Update the README to the actual exposed tool identifiers (e.g.workflows-list,workflows-<Workflow>-run,workflows-get_status,workflows-resume,workflows-cancel) so they match the server registrations and other docs.
🧹 Nitpick comments (15)
docs/cloud/getting-started.mdx (2)
182-186: Add an explicit gitignore warning and cloud‑only note next to the secrets example.Readers may accidentally commit keys, and some earlier text suggests env vars; cloud uses raw secrets only. Add a short warning below this block.
```yaml mcp_agent.secrets.yaml openai: api_key: "sk-..."+
+Addmcp_agent.secrets.yamlto.gitignore. For cloud deployments, environment variables are not read—use this secrets file and thecloud configureflow.
+--- `471-478`: **Potential confusion: Best Practices shows env vars in Python while cloud ignores env vars.** Consider appending a note: “For local dev only; cloud deployments use mcp_agent.secrets.yaml and cloud configure.” </blockquote></details> <details> <summary>examples/basic/mcp_basic_agent/README.md (1)</summary><blockquote> `133-144`: **Standardize Inspector table labels to “SSE URL”.** Other docs use “SSE URL”; align for consistency. ```diff -| _SSE_ | _https://[your-agent-server-id].deployments.mcp-agent.com/sse_ | +| _SSE URL_ | _https://[your-agent-server-id].deployments.mcp-agent.com/sse_ |examples/basic/mcp_model_selector/README.md (1)
109-119: Unify Inspector label to “SSE URL”.Keeps wording consistent with other pages.
-| _SSE_ | _https://[your-agent-server-id].deployments.mcp-agent.com/sse_ | +| _SSE URL_ | _https://[your-agent-server-id].deployments.mcp-agent.com/sse_ |docs/configuration.mdx (1)
693-704: Clarify that env vars are ignored on cloud.Helps reconcile guidance with local env-var examples elsewhere in this page.
<Tab title="Cloud Secrets"> - For mcp-agent cloud deployments, only raw secrets (not environment variables) are supported: + For mcp-agent cloud deployments, only raw secrets are supported. Environment variables are ignored by cloud apps: ```yaml openai: api_key: "sk-..." ``` During deployment, you will be prompted to specify which secrets should be used for the deployed app and which secrets will be excluded (and require a subsequent 'configure' command to configure with user secrets). </Tab>examples/workflows/workflow_intent_classifier/README.md (1)
97-107: Use “SSE URL” label for Inspector.Match the label used in other examples.
-| _SSE_ | _https://[your-agent-server-id].deployments.mcp-agent.com/sse_ | +| _SSE URL_ | _https://[your-agent-server-id].deployments.mcp-agent.com/sse_ |examples/workflows/workflow_orchestrator_worker/README.md (1)
112-122: Consistent Inspector label: “SSE URL”.-| _SSE_ | _https://[your-agent-server-id].deployments.mcp-agent.com/sse_ | +| _SSE URL_ | _https://[your-agent-server-id].deployments.mcp-agent.com/sse_ |examples/usecases/mcp_github_to_slack_agent/README.md (2)
112-122: Align Inspector label to “SSE URL”.-| _SSE_ | _https://[your-agent-server-id].deployments.mcp-agent.com/sse_ | +| _SSE URL_ | _https://[your-agent-server-id].deployments.mcp-agent.com/sse_ |
131-139: Fix tool description typos.
- “workflows-resume” should resume, not pause.
- Grammar: “Tools your agent exposes”.
- MCP Agent Cloud Default Tools: @@ - - workflows-resume: signal workflow to pause run + - workflows-resume: resume a paused run @@ -- Tool's that your agent expose: +- Tools your agent exposes:examples/mcp_agent_server/asyncio/README.md (4)
158-174: Add language to fenced blocks and fix capitalization.
- Add bash to the login command/code fences to satisfy MD040.
- “Github” → “GitHub”.
-``` +```bash uv run mcp-agent login-2. You will be redirected to the login page, create an mcp-agent cloud account through Google or Github
+2. You will be redirected to the login page, create an mcp-agent cloud account through Google or GitHub```diff -``` +```bash andrew_lm@Mac sdk-cloud % uv run mcp-agent login INFO: Directing to MCP Agent Cloud API login... Please enter your API key 🔑:--- `176-181`: **Use the correct app name in the deploy command.** Earlier examples and output use “basic_agent_server”; this line uses “mcp_agent_server”. Align them. ```diff -uv run mcp-agent deploy mcp_agent_server -c /absolute/path/to/your/project +uv run mcp-agent deploy basic_agent_server -c /absolute/path/to/your/project
184-221: Mark output block with a language and redact realistic IDs.
- Add text to the large output block (MD040).
- Consider obfuscating IDs/URLs consistently.
-``` +```text andrew_lm@Mac sdk-cloud % uv run mcp-agent deploy basic_agent_server -c /Users/andrew_lm/Documents/GitHub/mcp-agent/examples/mcp_agent_server/asyncio/ ... INFO: App URL: https://770xdsp22y321prwv9rasdfasd9l5zj5.deployments.mcp-agent.com INFO: App Status: OFFLINE ▹▹▹▹▹ ✅ MCP App deployed successfully!--- `196-213`: **Tighten the “Secrets Processing Summary” formatting.** Add a language to the summary table fence and make the label match surrounding terminology (“Reused” → “♻️ Reused” is fine, but ensure consistency across docs). ```diff - Secrets Processing Summary + Secrets Processing Summary +```text ┏━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┓ ┃ Type ┃ Path ┃ Handle/Status ┃ Source ┃ ┡━━━━━━━━━━━╇━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━┩ │ Developer │ openai.api_key │ mcpac_sc...b1e4qwe9 │ ♻️ Reused │ └───────────┴────────────────┴─────────────────────┴──────────┘ Summary: 0 new secrets created, 1 existing secrets reused SUCCESS: Secrets file processed successfully INFO: Transformed secrets file written to /Users/andrew_lm/Documents/GitHub/mcp-agent/examples/mcp_agent_server/asyncio/mcp_agent.deployed.secrets.yaml -╭───────────────────────────────────────── Deployment Ready ───────────────────────────────────────────────╮ +``` +╭───────────────────────────────────────── Deployment Ready ───────────────────────────────────────────────╮src/mcp_agent/cli/README.md (2)
80-86: Align example with “UUID strings” wording above.Section “Secret IDs” says IDs are UUID strings. The example shows a prefixed handle. Use a plain UUID here or adjust the earlier wording.
- key: mcpac_sc_123e4567-e89b-12d3-a456-426614174000 # Deployment secret transformed to UUID + key: 123e4567-e89b-12d3-a456-426614174000 # Deployment secret transformed to UUIDAlternatively, change the “Secret IDs” text to “opaque IDs (often UUIDs with a prefix)”.
131-135: Fix Python snippet syntax (commas and quotes).Current example won’t parse.
await deploy_config( - app_name="My MCP Agent App" - config_dir="path/to/project/configuration, + app_name="My MCP Agent App", + config_dir="path/to/project/configuration", api_key="your-api-key", - non_interactive=True + non_interactive=True, )
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (1)
uv.lockis excluded by!**/*.lock
📒 Files selected for processing (11)
docs/cloud/getting-started.mdx(1 hunks)docs/configuration.mdx(1 hunks)examples/basic/mcp_basic_agent/README.md(2 hunks)examples/basic/mcp_model_selector/README.md(2 hunks)examples/mcp_agent_server/asyncio/README.md(3 hunks)examples/usecases/mcp_github_to_slack_agent/README.md(2 hunks)examples/workflows/workflow_evaluator_optimizer/README.md(3 hunks)examples/workflows/workflow_intent_classifier/README.md(2 hunks)examples/workflows/workflow_orchestrator_worker/README.md(2 hunks)src/mcp_agent/cli/README.md(4 hunks)src/mcp_agent/cli/SECRETS.md(0 hunks)
💤 Files with no reviewable changes (1)
- src/mcp_agent/cli/SECRETS.md
🧰 Additional context used
🪛 markdownlint-cli2 (0.17.2)
examples/mcp_agent_server/asyncio/README.md
177-177: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: checks / test
🔇 Additional comments (4)
examples/workflows/workflow_evaluator_optimizer/README.md (1)
144-149: Inspector table looks good.Labels and formatting are clear and consistent with proposed standard.
examples/usecases/mcp_github_to_slack_agent/README.md (1)
143-149: LGTM: sample now includes execution_id.The added field improves parity with get_status output.
src/mcp_agent/cli/README.md (2)
42-49: Rewording looks good and matches the removal of !developer_secret.Clear distinction between developer vs user secrets. No references to !developer_secret remain.
Confirm that retaining the !user_secret placeholder is intentional and still supported by the toolchain.
100-105: CLI deploy syntax LGTM.Single -c config dir flow is clearer and consistent with the README changes.
2 participants
Description
We're no longer using !developer_secret tags so update remaining documentation
Summary by CodeRabbit