diff --git a/src/_data/sidebars/help.yml b/src/_data/sidebars/help.yml index 3cc64c7b..0a5b4421 100644 --- a/src/_data/sidebars/help.yml +++ b/src/_data/sidebars/help.yml @@ -161,8 +161,8 @@ resources: link: /mcp-servers/use-mcp-server/ - label: Access management link: /mcp-servers/access-management/ - - label: Secrets - link: /mcp-servers/secrets/ + - label: Secrets and config + link: /mcp-servers/secrets-and-config/ - label: Runtime expressions link: /mcp-servers/runtime-expressions/ - label: Debug sessions diff --git a/src/_help/mcp-servers/access-management.md b/src/_help/mcp-servers/access-management.md index b84c3bbd..2adb513f 100644 --- a/src/_help/mcp-servers/access-management.md +++ b/src/_help/mcp-servers/access-management.md @@ -31,4 +31,4 @@ Once authorized, the tool gets access to workflows provided by the MCP server. ### Authenticating with APIs While the visibility of the MCP server defines if a user has access to it, or not, your workflow APIs themselves can require authentication. -Setting [secrets](/help/mcp-servers/secrets) in Bump.sh is the way to go. \ No newline at end of file +[Secrets and config](/help/mcp-servers/secrets-and-config/) cover both server-wide credentials and per-user values forwarded at runtime. \ No newline at end of file diff --git a/src/_help/mcp-servers/index.md b/src/_help/mcp-servers/index.md index 6112c4e2..6026601a 100644 --- a/src/_help/mcp-servers/index.md +++ b/src/_help/mcp-servers/index.md @@ -38,7 +38,7 @@ Both formats support multi-step sequences, conditional logic (retry, goto, end), ## Go further -- [Secrets](/help/mcp-servers/secrets/): store API keys and tokens so they are never exposed in your workflow documents. +- [Secrets and config](/help/mcp-servers/secrets-and-config/): store API keys and tokens, or let each user pass their own values at runtime. - [Access management](/help/mcp-servers/access-management/): control who can use your MCP server. - [Debug sessions](/help/mcp-servers/debug-sessions/): inspect execution traces to troubleshoot workflows step by step. - [Runtime expressions](/help/mcp-servers/runtime-expressions/): reference dynamic data between steps. diff --git a/src/_help/mcp-servers/runtime-expressions.md b/src/_help/mcp-servers/runtime-expressions.md index 22ad16da..1b26892b 100644 --- a/src/_help/mcp-servers/runtime-expressions.md +++ b/src/_help/mcp-servers/runtime-expressions.md @@ -117,18 +117,31 @@ headers: Secret names must start with a letter, followed by letters, digits, or underscores (e.g. `API_KEY`, `myToken2`). -> See [Secrets](/help/mcp-servers/secrets) for how to configure secrets on your MCP server. +> See [Secrets and config](/help/mcp-servers/secrets-and-config/) for how to configure secrets on your MCP server. {: .info} -### Current user token (`$current_user.token`) +### Current user (`$current_user`) -Returns the OAuth token of the currently authenticated user. Only available on [private MCP servers](/help/mcp-servers/access-management/). Useful for forwarding the user's identity to external APIs. +Reference values tied to the user currently invoking the MCP server. Only available on [private MCP servers](/help/mcp-servers/access-management/). + +| Expression | Source | Description | +|---|---|---| +| `$current_user.token` | `Authorization: Bearer ...` | OAuth token of the authenticated user | +| `$current_user.` | `Config-` header | Per-user config sent by the client | ```yaml headers: Authorization: "Bearer $current_user.token" + X-Org-Id: "$current_user.org_id" ``` +For `$current_user.`, matching is case-insensitive, and underscores in the expression map to dashes in the header. All of `$current_user.api_key`, `$current_user.API_KEY` and `$current_user.Api-Key` resolve the same `Config-Api-Key` header. + +If no matching header is sent by the client, the expression resolves to an empty string. + +> See [Per-user config](/help/mcp-servers/secrets-and-config/#per-user-config) for how clients send these values. +{: .info} + ## Accessing data diff --git a/src/_help/mcp-servers/secrets-and-config.md b/src/_help/mcp-servers/secrets-and-config.md new file mode 100644 index 00000000..5e100562 --- /dev/null +++ b/src/_help/mcp-servers/secrets-and-config.md @@ -0,0 +1,104 @@ +--- +title: Secrets and config +--- + +- TOC +{:toc} + +Workflows can read sensitive or user-specific values without hard-coding them. Bump.sh exposes two complementary mechanisms: + +- **Secrets**: stored on Bump.sh, scoped to a single MCP server, shared across all users of that server. Useful for API keys you control yourself. +- **Per-user config**: sent by the client at runtime through HTTP headers, never stored on Bump.sh. Useful for values that differ per user, like a personal API key or an organization ID. + +## Secrets + +Secrets let you store sensitive values, such as API keys or tokens, separately from your workflow documents. They are injected at runtime so that your MCP server can authenticate with external APIs without exposing credentials in plain text. + +### Creating a secret + +Go to the **Secrets** section of your MCP server settings, then enter a name and a value. + +![MCP server secrets creation form](/docs/images/help/mcp-servers/mcp-servers-secrets.png) + +> Secrets are scoped to a single MCP server. They can only be accessed by that server's workflows. +{: .info} + +### Using a secret in a workflow + +Reference a secret with the `$secrets.{name}` expression wherever you would otherwise hard-code a sensitive value: + +```yaml +flows: + - id: book-train-trip + description: ... + inputs: {} + steps: [] + security: $secrets.booking-api-key +``` + +### Storage and security + +Secret values are encrypted at rest (AES-256-GCM) and stored on an isolated infrastructure, separate from the main Bump.sh application. The Bump.sh application itself never has access to decrypted secret values. + +At runtime, secrets are decrypted in memory only for the duration of a workflow execution. They are never written to logs, included in workflow outputs, or returned in API responses. + +## Per-user config + +Per-user config lets each end-user supply their own values when they connect to your MCP server. The values are passed as HTTP headers prefixed with `Config-`, never stored on Bump.sh, and resolved in workflows through `$current_user.`. + +Typical use cases: + +- Each user authenticates against the underlying API with their own API key. +- The workflow needs a per-user identifier (organization ID, workspace slug, region, ...). +- A custom OAuth flow, where the user pastes a token they obtained themselves. + +### Sending a config value + +Any header sent by the client and prefixed with `Config-` is forwarded as a config value. The header name (after the prefix) becomes the config name. + +For instance, the following Cursor configuration sends two values, `api_key` and `org_id`: + +```json +{ + "mcpServers": { + "My Bump.sh MCP server": { + "url": "https://run.bump.sh/my-org/my-mcp-server/mcp", + "headers": { + "Config-Api-Key": "sk-personal-1234", + "Config-Org-Id": "acme-eu" + } + } + } +} +``` + +> Headers without the `Config-` prefix are never forwarded to workflows. This protects sensitive headers (cookies, internal auth, ...) from being leaked through `$current_user.*`. +{: .info} + +### Using a config value in a workflow + +Reference the config value with `$current_user.`: + +```yaml +steps: + - id: list_projects + request: + method: GET + url: https://api.example.com/v1/orgs/$current_user.org_id/projects + headers: + Authorization: "Bearer $current_user.api_key" +``` + +The matching between the runtime expression and the header name is case-insensitive, and underscores in the expression are mapped to dashes in the header. All these expressions resolve the same `Config-Api-Key` header: + +| Expression | Resolves to | +|---|---| +| `$current_user.api_key` | `Config-Api-Key` header | +| `$current_user.API_KEY` | `Config-Api-Key` header | +| `$current_user.Api-Key` | `Config-Api-Key` header | + +See [Runtime expressions](/help/mcp-servers/runtime-expressions/#current-user-current_user) for the full reference. + +### Storage and security + +Config values are not stored on Bump.sh. They live only for the duration of a single workflow execution, in the data plane's memory. They are never written to logs, included in workflow outputs, or returned in API responses. diff --git a/src/_help/mcp-servers/secrets.md b/src/_help/mcp-servers/secrets.md deleted file mode 100644 index 30455c79..00000000 --- a/src/_help/mcp-servers/secrets.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: Secrets ---- - -- TOC -{:toc} - -Secrets let you store sensitive values, such as API keys or tokens, separately from your workflow documents. They are injected at runtime so that your MCP server can authenticate with external APIs without exposing credentials in plain text. - -## Creating a secret - -Go to the **Secrets** section of your MCP server settings, then enter a name and a value. - -![MCP server secrets creation form](/docs/images/help/mcp-servers/mcp-servers-secrets.png) - -> Secrets are scoped to a single MCP server. They can only be accessed by that server's workflows. -{: .info} - -## Using a secret in a workflow - -Reference a secret with the `$secrets.{name}` expression wherever you would otherwise hard-code a sensitive value: - -```yaml -flows: - - id: book-train-trip - description: ... - inputs: {} - steps: [] - security: $secrets.booking-api-key -``` - -## Storage and security - -Secret values are encrypted at rest (AES-256-GCM) and stored on an isolated infrastructure, separate from the main Bump.sh application. The Bump.sh application itself never has access to decrypted secret values. - -At runtime, secrets are decrypted in memory only for the duration of a workflow execution. They are never written to logs, included in workflow outputs, or returned in API responses. diff --git a/src/_help/mcp-servers/security.md b/src/_help/mcp-servers/security.md index d71e7a1b..5875e62e 100644 --- a/src/_help/mcp-servers/security.md +++ b/src/_help/mcp-servers/security.md @@ -12,7 +12,7 @@ Bump.sh MCP servers are designed so that sensitive data never leaves the executi Bump.sh MCP servers rely on two separate components: - The **Bump.sh application** handles server configuration, workflow deployments, and access management. It never processes API calls or accesses secret values. -- The **data plane** is an isolated infrastructure that executes your workflows at runtime. It is the only component that resolves [secrets](/help/mcp-servers/secrets/), performs HTTP requests to external APIs, and handles responses. +- The **data plane** is an isolated infrastructure that executes your workflows at runtime. It is the only component that resolves [secrets](/help/mcp-servers/secrets-and-config/), performs HTTP requests to external APIs, and handles responses. Because the data plane executes API requests on behalf of the LLM, the LLM itself never directly calls APIs. This means credentials, tokens, and sensitive response data are never exposed to the model. @@ -35,6 +35,6 @@ These two components communicate over encrypted channels (TLS) and are deployed The data plane does not persist sensitive data. Specifically: -- **Secret values** are encrypted at rest (AES-256-GCM) and only decrypted in memory for the duration of a workflow execution. See [Secrets](/help/mcp-servers/secrets/) for details. +- **Secret values** are encrypted at rest (AES-256-GCM) and only decrypted in memory for the duration of a workflow execution. See [Secrets and config](/help/mcp-servers/secrets-and-config/) for details. - **API responses** are processed in memory and discarded after each execution. They are not stored or forwarded to the Bump.sh application. - **Logs** never contain secret values, request bodies, or response payloads. diff --git a/src/_redirects b/src/_redirects index c0b55242..f658320f 100644 --- a/src/_redirects +++ b/src/_redirects @@ -2,6 +2,7 @@ https://help.bump.sh/markdown-support https://docs.bump.sh/help/documentation-ex https://help.bump.sh/references https://docs.bump.sh/help/specifications-support/references/ https://help.bump.sh/* https://docs.bump.sh/:splat 301! / /help/ 302 +/help/mcp-servers/secrets/ /help/mcp-servers/secrets-and-config/ /help/getting-started/api-platform/ /guides/bump-sh-tutorials/api-platform/ /help/getting-started/fastapi/ /guides/bump-sh-tutorials/fastapi/ /help/publish-documentation/release-management/ /help/publish-documentation/deploy-and-release-management/