diff --git a/frontend/styles/atoms/table.css b/frontend/styles/atoms/table.css index fa247858..60316602 100644 --- a/frontend/styles/atoms/table.css +++ b/frontend/styles/atoms/table.css @@ -49,11 +49,15 @@ thead { } th, td { - padding: var(--spacing-4); + padding: var(--spacing-2) var(--spacing-4); } td { border-bottom: var(--border-default); + + code { + white-space: nowrap; + } } tr { @@ -64,12 +68,12 @@ tr { td:last-child { border-right: var(--border-default); } - + &:last-child { td:first-child { border-bottom-left-radius: var(--border-radius-large); } - + td:last-child { border-bottom-right-radius: var(--border-radius-large); } diff --git a/frontend/styles/layouts/documentation.css b/frontend/styles/layouts/documentation.css index d512459f..49350046 100644 --- a/frontend/styles/layouts/documentation.css +++ b/frontend/styles/layouts/documentation.css @@ -70,6 +70,10 @@ max-width: 100%; max-height: 600px; } + + table { + margin: 1em 0; + } } @media(max-width: 800px) { diff --git a/src/_components/shared/sidebar/item.erb b/src/_components/shared/sidebar/item.erb index 9a037e6a..76279747 100644 --- a/src/_components/shared/sidebar/item.erb +++ b/src/_components/shared/sidebar/item.erb @@ -20,7 +20,7 @@ diff --git a/src/_components/shared/sidebar/item.rb b/src/_components/shared/sidebar/item.rb index ee87da10..d73a0f17 100644 --- a/src/_components/shared/sidebar/item.rb +++ b/src/_components/shared/sidebar/item.rb @@ -1,7 +1,8 @@ class Shared::Sidebar::Item < Bridgetown::Component - def initialize(page:, current:) + def initialize(page:, current:, parent_id: nil) @page = page @current = current + @parent_id = parent_id @resource = @page[:resource] @icon = @page[:icon] @label = @page[:label] @@ -11,7 +12,11 @@ def initialize(page:, current:) end def category_id - @label.parameterize + if @parent_id + "#{@parent_id}--#{@label.parameterize}" + else + @label.parameterize + end end def is_parent diff --git a/src/_data/sidebars/help.yml b/src/_data/sidebars/help.yml index c1a3a936..da04e793 100644 --- a/src/_data/sidebars/help.yml +++ b/src/_data/sidebars/help.yml @@ -11,6 +11,8 @@ resources: link: /getting-started/concepts/ - label: Upload your first API definition link: /getting-started/upload-your-first-definition/ + - label: Start your first MCP server + link: /getting-started/start-your-first-mcp-server/ - label: Going further link: /getting-started/going-further/ icon: zap @@ -142,6 +144,31 @@ resources: link: /continuous-integration/cli/ - label: API (advanced) link: /continuous-integration/api/ + - type: category + label: MCP servers + link: /mcp-servers/ + icon: mcp + items: + - label: Create and manage MCP servers + link: /mcp-servers/create-and-manage-mcp-servers/ + - label: Deploy workflows + link: /mcp-servers/deploy-workflows/ + - label: Use an MCP server + link: /mcp-servers/use-mcp-server/ + - label: Access management + link: /mcp-servers/access-management/ + - label: Secrets + link: /mcp-servers/secrets/ + - label: Runtime expressions + link: /mcp-servers/runtime-expressions/ + - label: Debug sessions + link: /mcp-servers/debug-sessions/ + - label: Security + link: /mcp-servers/security/ + - label: Specification support + items: + - label: Flower support + link: /mcp-servers/specification-support/flower-support/ - type: category label: Organizations link: /organizations/ diff --git a/src/_help/continuous-integration/cli.md b/src/_help/continuous-integration/cli.md index a66c99f1..19b277b4 100644 --- a/src/_help/continuous-integration/cli.md +++ b/src/_help/continuous-integration/cli.md @@ -15,6 +15,10 @@ Using [OpenAPI](https://spec.openapis.org/) (v3.x and v2.0) or [AsyncAPI](https: Under the hood, it uses the API of [developers.bump.sh](https://developers.bump.sh). And is built with the [`oclif`](https://oclif.io) framework in Typescript. +> You can use the CLI to interact with your MCP server: +> see how to [deploy a workflow document on your MCP server](#deploy-a-workflow-document-on-your-mcp-server). +{: .info} + ## Installation The Bump.sh CLI is a node package currently distributed via NPM. This means you must have the Node v20+ interpreter installed on your computer or CI servers. @@ -72,7 +76,7 @@ $ bump --help The Bump.sh CLI is used to interact with your API documentation hosted on Bump.sh by using the API of developers.bump.sh VERSION - bump-cli/2.9.2 linux-x64 node-v20.18.1 + bump-cli/2.9.12 linux-x64 node-v20.18.1 USAGE $ bump [COMMAND] @@ -113,10 +117,14 @@ bump deploy path/to/api-document.yml --doc my-documentation --token $DOC_TOKEN You can also deploy a given API document to a different branch of your documentation with the `--branch ` parameter. Please note the branch will be created if it doesn’t exist. More details about the branching feature are available on [this dedicated help page](/help/branching). E.g. deploy the API document to the `staging` branch of the documentation: + ```shell bump deploy path/to/api-document.yml --doc my-documentation --token $DOC_TOKEN --branch staging ``` +> You can also use this command to interact with your MCP server, see [how to deploy a workflow definition](#deploy-a-workflow-document-on-your-mcp-server). +{: .info} + #### Deploy a folder all at once If you already have a hub in your [Bump.sh](https://bump.sh) account, you can automatically create documentation and deploy it into that hub by publishing a whole directory containing multiple API documents in a single command: @@ -159,10 +167,24 @@ bump deploy path/to/api-document.yml --dry-run --doc my-documentation --token $D Please check `bump deploy --help` for more usage details. +#### Deploy a workflow document on your MCP server + +Use the `bump deploy` command with the `--mcp-server` flag to deploy a [Flower](/help/mcp-servers/specification-support/flower-support/) or Arazzo (soon) workflow document. + +```shell +bump deploy path/to/flower-document.yml --mcp-server my-mcp-server-id-or-slug --token $BUMP_TOKEN +``` + +> You can find your `mcp-server-id-or-slug` and `$BUMP_TOKEN` API key in your MCP server settings. +{: .info} + +This feature is currently in closed beta. +Request an early access at [hello@bump.sh](mailto:hello@bump.sh) + ### The `diff` command Using the `diff` command can help to spot differences between the local API -document and the latest deployed version. +document and the latest deployed version. #### Public API diffs @@ -180,7 +202,7 @@ Modified: GET /consommations By default the command will always exit with a successful return code. If you want to use this command in a CI environment and want the command to fail **in case of a breaking change**, you will need to add the `--fail-on-breaking` flag -to your diff command. +to your diff command. By default if the environment variable `CI=1` is present (in most continuous integration environment), the flag will be enabled. In that case you can disable @@ -254,7 +276,7 @@ Please check `bump preview --help` for more usage details ### The `overlay` command -The [Overlay Specification](https://spec.openapis.org/overlay/v1.0.0.html) from the OpenAPI Initiative makes it possible to modify the content of an API definition by adding a layer on top of it. That layer helps adding, removing or changing some or all of the content of the original definition. +The [Overlay Specification](https://spec.openapis.org/overlay/v1.0.0.html) from the OpenAPI Initiative makes it possible to modify the content of an API definition by adding a layer on top of it. That layer helps adding, removing or changing some or all of the content of the original definition. The `bump overlay` command takes an original API document (an OpenAPI or AsyncAPI document), applies the changes from the overlay document, and outputs a modified version. No changes are made directly to the original document. diff --git a/src/_help/continuous-integration/github-actions.md b/src/_help/continuous-integration/github-actions.md index c9eb7e97..0829a6bd 100644 --- a/src/_help/continuous-integration/github-actions.md +++ b/src/_help/continuous-integration/github-actions.md @@ -23,6 +23,10 @@ Then you can pick from one of the three following API workflow files. - [Deploy documentation only](#deploy-documentation-only) - [Diff on pull requests only](#diff-on-pull-requests-only) +> You can use the GitHub Action to interact with your MCP server: +> see how to [deploy a workflow document on your MCP server](#deploy-a-workflow-document-for-your-mcp-server). +{: .info} + ### Deploy documentation & diff on pull requests This is the [recommended workflow](/help/continuous-integration#integrate-with-your-ci), which will create two steps in your automation flow: a validation & diff step on code reviews, followed by a deployment step on merged changes. @@ -154,7 +158,7 @@ jobs: ### Deploy a single documentation on a hub -You can deploy a documentation inside a hub by adding a `hub` slug or id. +You can deploy a documentation inside a hub by adding a `hub` slug or id. Note that the documentation will be automatically created if it doesn't exist by using the slug you defined with the `doc:` input. `.github/workflows/bump-deploy.yml` @@ -249,6 +253,39 @@ In order to deploy the 3 services API definition files from this folder (`privat filename_pattern: '*-api-{slug}-service' ``` +### Deploy a workflow document for your MCP server + +Replace `BUMP_MCP_SERVER_ID_OR_SLUG`with the slug (or id) of your MCP server. It can be found in your MCP server settings. Don't forget to replace the `file` path with the path to your [Flower](/help/mcp-servers/specification-support/flower-support/) or Arazzo (soon) workflow document. + +`.github/workflows/bump.yml` + +```yaml +name: Deploy workflow document for your MCP server + +on: + push: + branches: + - main + +jobs: + deploy-workflow-document: + name: Deploy workflow document for MCP server on Bump.sh + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + - name: Deploy workflow document + uses: bump-sh/github-action@v1 + with: + command: deploy + mcp_server: + token: ${{secrets.BUMP_TOKEN}} + file: doc/flower-document.yml +``` + +This feature is currently in closed beta. +Request an early access at [hello@bump.sh](mailto:hello@bump.sh) + ## Inputs * `doc` (required unless you deploy a directory on a hub): Documentation slug or id. Can be found in the documentation settings on [your API dashboard](https://bump.sh/dashboard). @@ -267,7 +304,7 @@ In order to deploy the 3 services API definition files from this folder (`privat * `command`: Bump.sh command to execute. _Default: `deploy`_ - * `deploy`: deploy a new version of the documentation + * `deploy`: deploy a new version of the documentation (or MCP server ✨) * `diff`: automatically comment your pull request with the API diff * `dry-run`: dry-run a deployment of the API definition file * `preview`: create a temporary preview @@ -276,6 +313,8 @@ In order to deploy the 3 services API definition files from this folder (`privat * `fail_on_breaking` (optional): Mark the action as failed when a breaking change is detected with the diff command. This is only valid with `diff` command. +* `mcp_server` (required to deploy workflow documents on an MCP server): MCP Server id or slug. It can be found in MCP server settings. This is only valid with the `deploy` command (default command). + ## Contributing Bug reports and pull requests are welcome on GitHub at [https://github.com/bump-sh/github-action](https://github.com/bump-sh/github-action). This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct. diff --git a/src/_help/continuous-integration/index.md b/src/_help/continuous-integration/index.md index 1943aecb..2b2b6313 100644 --- a/src/_help/continuous-integration/index.md +++ b/src/_help/continuous-integration/index.md @@ -27,6 +27,12 @@ We advise to setup two steps in your automation flow: - a [**validation** and **diff** step](#api-diff--validation-of-the-documentation-file) during development - followed by a [**deployment** step](#deploy-your-api-document) on production merges. + +> You can use the CI to interact with your MCP server, +> see examples with [the CLI](/help/continuous-integration/cli#deploy-a-workflow-document-on-your-mcp-server) +> or [the GitHub Action](/help/continuous-integration/github-actions#deploy-a-workflow-document-for-your-mcp-server). +{: .info} + ### API diff & validation of the documentation file When suggesting a change to your API, you probably follow a pull request flow (also known as merge request) and make the changes on a development branch. You can integrate Bump.sh at this stage to generate an API diff or only validate your changed API document. @@ -49,6 +55,10 @@ The GitHub action example uses a dedicated action we crafted especially for you. - [API diff & validation step](/help/continuous-integration/github-actions/#diff-on-pull-requests-only) - [Deploy to your documentation](/help/continuous-integration/github-actions/#deploy-documentation-only) +The GitHub Action can be used to interact with your MCP server: + +- [Deploy a workflow document for your MCP server](/help/continuous-integration/github-actions/#deploy-a-workflow-document-for-your-mcp-server). + ### Other Continuous Integration tools (CI) The CI examples are here to help you build a similar process described with our GitHub action. We try to keep some specially crafted scripts for you to build the same experience for your own tools: @@ -62,7 +72,7 @@ The CI examples are here to help you build a similar process described with our The CLI can be used in your custom CI scripts with the two available recommendeded steps: - [`bump diff`](/help/continuous-integration/cli/#api-diff-of-your-changes) to check the changes & validate the API document -- [`bump deploy`](/help/continuous-integration/cli/#deploy-a-file) to publish to your Bump.sh documentation +- [`bump deploy`](/help/continuous-integration/cli/#deploy-a-file) to publish to your Bump.sh documentation, or MCP server ## Recommendation diff --git a/src/_help/getting-started/concepts.md b/src/_help/getting-started/concepts.md index fc1255e8..84a1a613 100644 --- a/src/_help/getting-started/concepts.md +++ b/src/_help/getting-started/concepts.md @@ -10,7 +10,26 @@ The terminology used here aims to be as accurate as possible, but you may encoun ![Bump.sh global workflow including deploying, release and access management](/docs/images/help/bump-sh-global-workflow.png) -## API definition +## Global concepts + +### Specification + +Specifications are the official standards used to describe, among other things: +- an API (OpenAPI, AsyncAPI, ...), +- an API workflow (Flower, Arazzo, ...). +These standards outline a set of elements and rules to follow when writing an API definition. + +We support OpenAPI, AsyncAPI (up to 2.6), and Flower (our internal workflow specification). Arazzo will be supported soon. To learn more about the supported specifications, we have written dedicated guides on [OpenAPI](/guides/openapi) and [AsyncAPI](/guides/asyncapi/what-is-asyncapi/). We also made a guide on [Flower](/help/mcp-servers/specification-support/flower-support), our own workflow standard. + +### Deployment + +A deployment is the processing of an API or a workflow document by Bump.sh: after the upload, it validates the definition against its specification, analyses its content and either: +- makes it available on the MCP server, for a workflow document, +- prepares the [release](/help/publish-documentation/deploy-and-release-management/), for an API document. + +## API documentation + +### API definition An API definition is the representation of an API written in compliance with an existing specification. It is sometimes referred to as an API schema, API contract, or even [API specification](/help/getting-started/concepts/#specification) (which is something different). @@ -19,33 +38,23 @@ As of today, Bump.sh supports the following specifications: [OpenAPI (Swagger)]( We provide a detailed introduction to API definitions [through this guide](/guides/api-basics/api-contracts-extended-introduction/). -## API contract +### API contract An API contract represents the use of an API definition when it defines an agreement, a contract between API developers, its consumers, how it is used, and the tools that surround it. -## API document +### API document An API document refers to the file containing an API definition. -## Specification - -Specifications are the official standards that define a format for describing an API, such as OpenAPI or AsyncAPI. These standards outline a set of elements and rules to follow when writing an API definition. - -To learn more about the supported specifications, we have written dedicated guides on [OpenAPI](/guides/openapi) and [AsyncAPI](/guides/asyncapi/what-is-asyncapi/). - -## Deployment - -A deployment is the processing of an API document by Bump.sh: after the upload, it validates the definition against its specification, analyses its content and prepares the [release](/help/publish-documentation/deploy-and-release-management/). - -## Release +### Release The step following a successful deploy. During the [release](/help/publish-documentation/deploy-and-release-management/), the documentation is updated, the changelog reflects the related changes, and notifications, if configured, are sent out. The release step can be automatic, or manual. -## API change +### API change An API change refers to a change in the structure of an API. After the release of an API definition, it is represented by a new entry in the [API changelog](/help/changes-management/changelog/). -## Breaking change +### Breaking change Breaking changes are the ones your API consumers should not miss and are highlighted in the changelog. Here is a non-exhaustive list of criteria that help us determine if a change is breaking or not: - Renaming/Deleting an endpoint or operation @@ -55,6 +64,24 @@ Breaking changes are the ones your API consumers should not miss and are highlig - Marking an existing property as required - Add or delete a security requirement -## Changelog +### Changelog After each deployment, Bump.sh updates the documentation's [changelog](/help/changes-management/changelog/), listing all API changes between the current deployment and the previous one. If the "Track all changes" option is enabled, the changelog will also display changes in the documentation. + +## MCP servers + +### MCP server + +An MCP (Model Context Protocol) server makes your API workflows available to LLM-based applications and agents. It processes API workflow documents and handles the runtime execution of these workflows. The MCP standard is supported by many AI tools: adding an MCP server is often just a matter of pasting the server URL into the "Connectors" or "Tools" section of the AI app. + +### Workflow + +A workflow is a chain of multiple API calls designed to achieve specific business goals, rather than just providing a list of endpoints. + +### Workflow definition + +A workflow definition is the representation of an API workflow written in compliance with a workflow specification like Arazzo or Flower. It describes a sequence of API operations and the goal of this sequence, their dependencies, and the data flow between them (inputs and outputs). + +### Workflow document + +A workflow document refers to the file containing a workflow definition. These documents are deployed to Bump.sh where they're validated, processed, and made available on MCP servers for execution. \ No newline at end of file diff --git a/src/_help/getting-started/going-further.md b/src/_help/getting-started/going-further.md index 49f306f1..1192a8dd 100644 --- a/src/_help/getting-started/going-further.md +++ b/src/_help/getting-started/going-further.md @@ -5,15 +5,7 @@ title: Going further - TOC {:toc} -Now that your first documentation has been published, you may want to personalize it further. There are numerous options available to you to enhance your use of Bump.sh. - -## Publish more documentation - -Your ecosystem might include multiple APIs that also need their own documentation, and Bump.sh offers various tools to assist you. - -Learn how to add additional stand-alone documentation or consider [creating a hub](/help/hubs/), a library of API documents. - -You also have the option to choose [how to upload your API documents](/help/continuous-integration/) to Bump.sh and have finer [control over their release](/help/publish-documentation/deploy-and-release-management/). +Now that you have a good view of what Bump.sh has to offer, you may want to go further. There are numerous options available to you to enhance your use of Bump.sh. ## Access management @@ -23,10 +15,18 @@ You can create an organization and [assign roles to members of your team and API To go even further, you could configure access management for each of [your documentation](/help/publish-documentation/documentation-access-management/) or [hubs](/help/hubs/). +## Group documentation in hubs + +Your ecosystem might include multiple APIs that also need their own documentation, and Bump.sh offers various tools to assist you. + +Learn how to add additional stand-alone documentation or consider [creating a hub](/help/hubs/), a library of API documents. + +You also have the option to choose [how to upload your API documents](/help/continuous-integration/) to Bump.sh and have finer [control over their release](/help/publish-documentation/deploy-and-release-management/). + ## Customization options There are numerous possibilities to customize your documentation and incorporate your brand. Using a [custom domain](/help/customization-options/custom-domains/) allows you to integrate your API documentation under your domain and a unified URL. You can also customize the [logo or colors](/help/customization-options/color-logo-meta-images/) of your documentation to display your brand. -Feel free to take a look at our [dedicated help page](/help/customization-options/) for more information. +Feel free to take a look at our [dedicated help page](/help/customization-options/) for more information. \ No newline at end of file diff --git a/src/_help/getting-started/index.md b/src/_help/getting-started/index.md index 5e5c95ed..bfebb8c1 100644 --- a/src/_help/getting-started/index.md +++ b/src/_help/getting-started/index.md @@ -1,14 +1,14 @@ --- -title: Quick Start +title: Quick start --- - TOC {:toc} -Bump.sh connects people with REST and event-driven APIs, by centralizing a reference point: their documentation, highlighted with the latest changes and updates. +Bump.sh connects people with REST and event-driven APIs by centralizing their documentation, highlighted with the latest changes and updates, while also powering MCP servers that execute API workflows for AI agents and tools. -From your API definition (OpenAPI and AsyncAPI), Bump.sh automatically generates the documentation you need, a detailed changelog of the latest changes, and offers you many options to customize it to provide a unique experience that is your own. +From your API definitions (OpenAPI and AsyncAPI), Bump.sh automatically generates documentation and detailed changelogs. From your workflow definitions (Flower, and Arazzo soon), it deploys MCP servers that execute real business workflows. Both offerings include extensive customization options to provide a unique experience that reflects your brand. -This Getting Started guide aims to get you started quickly if you're writing OpenAPI or AsyncAPI files or if you know where these files are located in your code repository. +This setting started guide aims to get you started quickly, whether you're working with API definitions, workflow documents, or both. -You will start by [deploying your first API documentation](/help/getting-started/upload-your-first-definition/) and then explore initial customization options before [digging further](/help/getting-started/going-further/). \ No newline at end of file +You can start by [deploying your first API documentation](/help/getting-started/upload-your-first-definition/) and exploring customization options, or dive into [MCP servers](/help/getting-started/start-your-first-mcp-server/) for workflow execution. Either path will help you get the most out of Bump.sh before [digging further](/help/getting-started/going-further/) into advanced features. \ No newline at end of file diff --git a/src/_help/getting-started/start-your-first-mcp-server.md b/src/_help/getting-started/start-your-first-mcp-server.md new file mode 100644 index 00000000..74a66687 --- /dev/null +++ b/src/_help/getting-started/start-your-first-mcp-server.md @@ -0,0 +1,36 @@ +--- +title: Start your first MCP server +--- + +- TOC +{:toc} + +Having a running MCP server with Bump.sh in a matter of minutes. Create your account, upload your workflow document, and you're good to go. + +## Create your Bump.sh account + +You can either create your account by using your email address or directly sign up using your GitHub account. + +![](/docs/images/help/signup.png) + +## Create your first MCP server + +### Step 1: Create your organization + +Organizations allow you to work alone or collaboratively on your MCP servers, API documentation, and hubs (collections of documentation). + +![](/docs/images/help/org-creation.png) + +### Step 2: Create your MCP server + +You are now ready to create your MCP server. Some information are required: the most important one is the server URL. It's the URL you'll use to add the MCP server to your AI tool. + +![MCP server creation form](/docs/images/help/mcp-servers/mcp-servers-creation-flow.png) + +The last step is to upload your workflow definition. You can do it using our web upload service, but also with our multiple CI methods. + +![MCP server web upload module](/docs/images/help/mcp-servers/mcp-servers-web-upload.png) + +### Step 3: Use your MCP server + +And just like that, your first MCP server is live! You can now [add it to your favorite AI tool](/help/mcp-servers/use-mcp-server) and start using it. \ No newline at end of file diff --git a/src/_help/index.md b/src/_help/index.md index 3d0a773e..504019f8 100644 --- a/src/_help/index.md +++ b/src/_help/index.md @@ -7,14 +7,18 @@ title: Bump.sh Documentation Learn how to get the most of Bump.sh for your API ecosystem. +### Global +- [Manage your Bump.sh organization](/help/organizations/index) -- Invite teammates or partners to your ecosystem. - [Getting started](/help/getting-started) -- Learn about Bump.sh, how to deploy your first specification file and explore the possibilities. + +### API doc portal - [Specification support](/help/specification-support) -- Which and how specifications are supported. - [Changes management](/help/changes-management) -- Never miss any changes of your API, check them with the diff. - -## Manage your documentation and access - [Hubs](/help/hubs) -- Create groups of documentation. - [Enhance your documentation content](/help/enhance-documentation-content) -- Best ways to improve your documentation for your API consumers. -- [Organizations](/help/organizations/index) -- Invite teammates or partners to your ecosystem. - -## Customization - [Customization options](/help/customization-options) -- Various options to customize your documentation and hubs to your needs. + +### MCP servers +- [Flower specification](/help/mcp-servers/specification-support/flower-support) -- Learn how to write your workflow definition. +- [Use your MCP server](/help/mcp-servers/use-mcp-server/) -- Connect your MCP server to your favorite AI tools. +- [Debug sessions](/help/mcp-servers/debug-sessions) -- See how agents use your APIs, track errors, and optimize workflows. \ No newline at end of file diff --git a/src/_help/mcp-servers/access-management.md b/src/_help/mcp-servers/access-management.md new file mode 100644 index 00000000..b84c3bbd --- /dev/null +++ b/src/_help/mcp-servers/access-management.md @@ -0,0 +1,34 @@ +--- +title: Access management +--- + +- TOC +{:toc} + +### MCP server visibility + +You can choose whether your MCP server is public or private: +- Public means anyone can access your MCP server, given they have the server URL, +- Private means users need to be authenticated with their Bump.sh account and be members of your organization to access your MCP server. + +Server visibility is set during the MCP server creation, and can be changed at any time in your MCP server settings. + +![Access management module of the MCP server](/docs/images/help/mcp-servers/mcp-servers-access-management.png) + +#### Authenticating with private MCP servers + +Users are required to authenticate before interacting with private MCP servers. This is the typical flow: +- The MCP server is added to a tool: Claude, ChatGPT, Cursor, ... ([see our tutorials](/help/mcp-servers/use-mcp-server)), +- The tool reaches the MCP server and gets notified that the server is private, +- A "connect" button appears next to the MCP server entry, or an authorization page automatically opens, +- If the user isn't signed in to Bump.sh yet, he has to sign in, +- Then, if the user is an authorized member of the MCP server on Bump.sh, he gets an authorization page. + +Once authorized, the tool gets access to workflows provided by the MCP server. + +![MCP server authorization page when adding the server to a tool](/docs/images/help/mcp-servers/mcp-servers-authorization-page.png) + +### 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 diff --git a/src/_help/mcp-servers/create-and-manage-mcp-servers.md b/src/_help/mcp-servers/create-and-manage-mcp-servers.md new file mode 100644 index 00000000..74bdcc0b --- /dev/null +++ b/src/_help/mcp-servers/create-and-manage-mcp-servers.md @@ -0,0 +1,51 @@ +--- +title: Create and manage MCP servers +--- + +- TOC +{:toc} + +## Where can I find my MCP servers? + +Your MCP servers are listed in your dashboard, alongside your APIs and hubs. If you don't have any MCP servers, the dedicated section will be at the bottom of your dashboard, below your API docs. + +![MCP server category in Bump.sh dashboard](/docs/images/help/mcp-servers/mcp-servers-dashboard.png) + +## Create an MCP server + +To create a new MCP server, go to your dashboard and click on the "New MCP server" button. A few essential information are required. + +| Server name | The name of the MCP server as it will appear to those who have access to it. | +| Server URL | The server URL allows you to define the URL of your MCP server, in the format `https://run.bump.sh/your_organization_slug/your_server_slug/mcp`. If empty, the path will be generated based on the server name. | +| Deployment method | Allows you to choose the deployment type that best suits your workflow. You can modify it at any time. | + +![MCP server creation form](/docs/images/help/mcp-servers/mcp-servers-creation-flow.png) + +The next step is to deploy a workflow document so that the MCP server knows which workflows to expose and process. The web upload is great to quickly test your MCP server, but we have ways to integrate in your development workflow, detailed in our next section named [**Deploy workflows**](/help/mcp-servers/deploy-workflows). + +![MCP server web upload module](/docs/images/help/mcp-servers/mcp-servers-web-upload.png) + +## Start and stop an MCP server + +You can start and stop your MCP server in your server settings. Note that the MCP server will start automatically following your first deployment. + +![MCP server status module](/docs/images/help/mcp-servers/mcp-servers-start-stop-server.png) + + +## Delete an MCP server + +To delete your MCP server, go to your server settings. + +> All deletions are final. The server won't be available anymore, and we cannot restore or recover any portion of the data once it’s deleted. +{: .warning} + +![MCP server deletion module](/docs/images/help/mcp-servers/mcp-servers-delete-server.png) + +## MCP server states + +You can check the state of your MCP server at any time in your dashboard or in your MCP server settings, next to its name. + +| **State** | **Description** | +| ⚪️ Stopped | Your MCP server is offline and doesn't process any requests. | +| 🟢 Running | Your MCP server is live and is processing requests based on your last workflow deployment. | +| 🔴 Errored | An error on our infrastructure prevents your MCP server from running. We are working on it. | \ No newline at end of file diff --git a/src/_help/mcp-servers/debug-sessions.md b/src/_help/mcp-servers/debug-sessions.md new file mode 100644 index 00000000..950301d9 --- /dev/null +++ b/src/_help/mcp-servers/debug-sessions.md @@ -0,0 +1,155 @@ +--- +title: Debug sessions +--- + +- TOC +{:toc} + +A debug session is a temporary authorization to access execution traces on the [data plane](/help/mcp-servers/#data-plane). It lets you see which API calls your MCP server actually executes, what responses it receives, and how it produces its final output. Sessions last 4 hours max and only one can be active at a time. + +## Start a debug session + +Go to your MCP server settings and create a new session. You will get a unique token to authenticate your requests. + +From the debug session page, select a tool to get a pre-filled cURL command. The request uses 4 variables: + +- `ORGANIZATION_SLUG`: your Bump.sh organization slug. +- `MCP_SERVER_SLUG`: your MCP server slug. +- `DEBUG_TOKEN`: your unique session token. +- `TOOL_NAME`: the tool to debug, as defined in your workflow file. + +### Pass inputs + +If the workflow requires inputs, you can pass them in two ways. + +**As query parameters** (simplest, with a GET request): + +```curl +$ curl \ + --request GET "run.bump.sh/$ORGANIZATION_SLUG/$MCP_SERVER_SLUG/debug/$TOOL_NAME?city=paris&format=celsius" \ + --header "Authorization: Token $DEBUG_TOKEN" +``` + +**As a JSON body** (with a POST request): + +```curl +$ curl \ + --request POST "run.bump.sh/$ORGANIZATION_SLUG/$MCP_SERVER_SLUG/debug/$TOOL_NAME" \ + --header "Authorization: Token $DEBUG_TOKEN" \ + --header "Content-Type: application/json" \ + --data '{"city": "paris", "format": "celsius"}' +``` + +![MCP server debug session page](/docs/images/help/mcp-servers/mcp-servers-debug-session.png) + +> Debug sessions run on the production environment. Responses may include sensitive data. Handle them with care. +{: .warning} + +## Read the response + +The debug endpoint returns a JSON object with two keys: + +- `outputs`: the final values returned to the AI agent after running the workflow. +- `trace`: the full execution trace, showing every step the data plane ran. + +### Quick check + +Start by looking at `outputs`. If the values are wrong or missing, dive into the `trace` to find where things went wrong. + +### Understand the trace + +The `trace` object contains: + +- **Flow-level inputs and outputs**: what the workflow received and what it returned. +- **Steps** (`step.run`): each HTTP request the data plane executed, with the full request (method, URL, query, body) and the API response (status, body). +- **Actions** (`action.run`): flow control decisions between steps. If your workflow uses conditions (retry, goto, end), this is where they are evaluated. + +### Example + +Here is a shortened trace from our Weather MCP server. The workflow resolves a city name to coordinates, then fetches the current weather. + +```json +{ + "outputs": { + "temperature": "18.2 °C", + "rain": "0.0", + "snowfall": "0.0" + }, + "trace": { + "name": "flow.run", + "duration_ms": 181.44, + "flow_id": "weather_current", + "inputs": { + "city": "paris" + }, + "outputs": { + "temperature": "18.2 °C", + "rain": "0.0", + "snowfall": "0.0" + }, + "children": [ + { + "name": "step.run", + "duration_ms": 61.2, + "step_id": "get_lat_lon", + "request": { + "method": "get", + "url": "https://nominatim.openstreetmap.org/search?q=paris&format=jsonv2", + "query": { "q": "paris", "format": "jsonv2" } + }, + "response": { + "status": 200, + "body": [ + { "lat": "48.8534951", "lon": "2.3483915", "name": "Paris" } + ] + } + }, + { + "name": "action.run", + "duration_ms": 0.13, + "action": { "type": "next" } + }, + { + "name": "step.run", + "duration_ms": 118.45, + "step_id": "get_weather_current", + "request": { + "method": "get", + "url": "https://api.open-meteo.com/v1/forecast?latitude=48.8534951&longitude=2.3483915¤t=temperature_2m,rain,snowfall", + "query": { + "latitude": "48.8534951", + "longitude": "2.3483915", + "current": "temperature_2m,rain,snowfall" + } + }, + "response": { + "status": 200, + "body": { + "current": { + "temperature_2m": 18.2, + "rain": 0.0, + "snowfall": 0.0 + } + } + } + }, + { + "name": "action.run", + "duration_ms": 0.12, + "action": { "type": "next" } + } + ] + } +} +``` + +## Security and access + +Trace data is not persisted. Nothing is stored between requests. + +Maintainers, admins, and owners of your organization can create debug sessions. Session activity is visible on the history page. + +![MCP server debug sessions history](/docs/images/help/mcp-servers/mcp-servers-debug-sessions.png) + +> Admins and owners can stop other members' sessions. +{: .info} diff --git a/src/_help/mcp-servers/deploy-workflows.md b/src/_help/mcp-servers/deploy-workflows.md new file mode 100644 index 00000000..c6c652f6 --- /dev/null +++ b/src/_help/mcp-servers/deploy-workflows.md @@ -0,0 +1,38 @@ +--- +title: Deploy workflows +--- + +- TOC +{:toc} + +## What are deployments + +Similar to API deployments, a deployment is the processing by Bump.sh servers of a workflow document containing Arazzo or [Flower](/help/mcp-servers/specification-support/flower-support) workflows. After processing, workflows contained by this document are made available by your MCP server. + +![MCP servers deployments page](/docs/images/help/mcp-servers/mcp-servers-deployments.png) + +> MCP servers always run workflows of the last deployment. +{: .info} + +## Deploy from the dashboard + +You can deploy workflow documents directly from your MCP server settings. To do so, click on the "Deploy new workflow document" button. + +![MCP servers deploy new workflow document button](/docs/images/help/mcp-servers/mcp-servers-deploy-new-document-button.png) + +## Deploy from the CLI + +You can deploy a workflow document using our CLI using the `TBD` command. The complete process is available on the dedicated [CLI page](/help/continuous-integration/cli/). + +## Deploy using the GitHub Action + +Our [GitHub Action](/help/continuous-integration/github-actions/) allows you to easily integrate Bump.sh into your projects. + +## Deployment states +You can check the state of a deployment in the deployments page and verify which one is served by the MCP server. + +| **State** | **Description** | +| Active | Exposed by the MCP server. | +| Deployed | Previous deploy, no longer exposed by the MCP server. | +| Deploying | Being processed by Bump.sh. | +| Errored | Encountered an error during deployment. | \ No newline at end of file diff --git a/src/_help/mcp-servers/index.md b/src/_help/mcp-servers/index.md new file mode 100644 index 00000000..2da18f1d --- /dev/null +++ b/src/_help/mcp-servers/index.md @@ -0,0 +1,48 @@ +--- +title: MCP servers +--- + +- TOC +{:toc} + +## What is MCP + +The [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) is an open standard that lets AI agents discover and call external tools. An MCP server exposes a set of tools that agents (ChatGPT, Claude, Cursor, etc.) can invoke to interact with APIs, databases, or any external service. + +## What Bump.sh offers + +Bump.sh lets you create MCP servers by declaring workflows in a simple document. You describe the API calls and their sequencing, and Bump.sh generates a fully hosted MCP server that executes them. + +This approach is **declarative**: you define *what* the server should do, not *how* to run it. There is no code to write, no server to deploy, no infrastructure to manage. Because every execution follows your workflow definition exactly, the behavior is **deterministic** and **predictable**, which is critical when AI agents interact with real APIs. + +### The data plane {#data-plane} + +All API calls are executed by an isolated component called the data plane. The AI agent never calls your APIs directly. Instead, it invokes a tool on your MCP server, and the data plane runs the corresponding workflow: resolving secrets, executing HTTP requests, and returning only the declared outputs to the agent. + +This architecture keeps credentials and sensitive API responses away from the LLM. See [Security](/help/mcp-servers/security/) for details. + +### Workflow specifications + +Workflows can be written in two formats: + +- [**Flower**](/help/mcp-servers/specification-support/flower-support): a lightweight specification designed by Bump.sh. Ideal for small projects, quick prototyping, or workflows calling APIs for which you don't have an OpenAPI document. +- **Arazzo**: the workflow specification from the OpenAPI Initiative. Better suited for complex projects that need to reference existing OpenAPI documents. + +Both formats support multi-step sequences, conditional logic (retry, goto, end), runtime expressions, and secrets. + +## Get started + +1. [Create an MCP server](/help/mcp-servers/create-and-manage-mcp-servers/) from your dashboard. +2. [Deploy a workflow document](/help/mcp-servers/deploy-workflows/) that describes the API calls your server can perform. +3. Share the server URL so that end-users can [add it to their AI tool](/help/mcp-servers/use-mcp-server/). + +## Go further + +- [Secrets](/help/mcp-servers/secrets/): store API keys and tokens so they are never exposed in your workflow documents. +- [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. +- [Security](/help/mcp-servers/security/): understand the architecture and data handling guarantees. + +> MCP servers are in closed beta. [Contact us to be among our first users](mailto:hello@bump.sh). +{: .info} diff --git a/src/_help/mcp-servers/runtime-expressions.md b/src/_help/mcp-servers/runtime-expressions.md new file mode 100644 index 00000000..22ad16da --- /dev/null +++ b/src/_help/mcp-servers/runtime-expressions.md @@ -0,0 +1,332 @@ +--- +title: Runtime expressions +--- + +- TOC +{:toc} + +Runtime expressions let you dynamically reference values during workflow execution: inputs from the caller, responses from previous steps, secrets, and more. They are used in both [Flower](/help/mcp-servers/specification-support/flower-support) and Arazzo workflow definitions. + +Expressions start with a `$` prefix and are resolved at runtime. + +## Expression variables + +### Flow inputs (`$inputs`) + +Access values passed by the caller when invoking a flow. + +```yaml +query: + q: $inputs.city +``` + +Nested access and array indexing are supported (see [Accessing data](#accessing-data) for all syntaxes): + +| Expression | Description | +|---|---| +| `$inputs.city` | Top-level input | +| `$inputs.address.zipcode` | Nested object property | +| `$inputs.items.0.name` | Array element (dot notation) | +| `$inputs.items[0].name` | Array element (JMESPath) | + +### Current step response (`$response`) + +Reference the HTTP response of the current step. + +```yaml +outputs: + lat: $response.body.0.lat + lon: $response.body.0.lon + status: $response.status +``` + +| Path | Description | +|---|---| +| `$response.body` | Parsed response body (JSON) | +| `$response.body.` | Deep access into the body | +| `$response.status` | HTTP status code | +| `$response.headers` | Response headers | +| `$statusCode` | Shortcut for `$response.status` | +| `$status` | Shortcut for `$response.status` | + +### Current step request (`$request`) + +Reference the request sent for the current step. + +| Path | Description | +|---|---| +| `$request.method` | HTTP method (`GET`, `POST`, etc.) | +| `$request.url` | Full URL including query string | +| `$request.query` | Query parameters | +| `$request.headers` | Request headers | +| `$request.body` | Request body | +| `$method` | Shortcut for `$request.method` | +| `$url` | Shortcut for `$request.url` | + +### Current step outputs (`$outputs`) + +Reference resolved outputs of the current step. Useful when an output depends on another output's value. + +```yaml +outputs: + lat: $response.body.0.lat + coordinates: "$outputs.lat, $response.body.0.lon" +``` + +### Previous step results (`$steps`) + +Access the request, response, or outputs of a previously executed step. + +```yaml +steps: + - id: get_lat_lon + request: + method: GET + url: https://nominatim.openstreetmap.org/search + query: + q: $inputs.city + format: jsonv2 + outputs: + lat: $response.body.0.lat + + - id: get_weather + request: + method: GET + url: https://api.open-meteo.com/v1/forecast + query: + latitude: $steps.get_lat_lon.outputs.lat +``` + +The pattern is `$steps...` where `` is one of: + +| Pattern | Description | +|---|---| +| `$steps..outputs.` | A resolved output value | +| `$steps..response.body.` | Response body access | +| `$steps..response.status` | Response status code | +| `$steps..request.url` | Request URL | + +### Server secrets (`$secrets`) + +Reference secrets stored on the server. Secret values are never included in workflow outputs. + +```yaml +headers: + Authorization: "Bearer $secrets.API_KEY" +``` + +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. +{: .info} + +### Current user token (`$current_user.token`) + +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. + +```yaml +headers: + Authorization: "Bearer $current_user.token" +``` + + +## Accessing data + +Two syntaxes are available: + +- **Dot notation** covers property access and array indexing. Sufficient for most use cases. +- **JMESPath** adds projections, filtering, slicing, and functions for advanced queries. + +Both work with any expression variable (`$response`, `$inputs`, `$steps`, etc.). + +### Dot notation + +``` +$response.body.current.temperature_2m # object property +$response.body.0.lat # array element (0-based) +$response.body.users.0.address.city # combined +``` + +### JMESPath + +> JMESPath support is a Bump.sh extension. It is not part of the Arazzo specification. +{: .warning} + +When dot notation is not enough, Bump.sh supports [JMESPath](https://jmespath.org/), a query language for JSON. An expression is automatically treated as JMESPath when it contains bracket syntax (`[*]`, `[0]`, `[?...]`, `[0:3]`) or a function call (`avg(...)`, `length(...)`, etc.). + +#### Projections (`[*]`) + +Extract a property from every element of an array: + +```yaml +# Given response body: {"users": [{"name": "Alice"}, {"name": "Bob"}]} +outputs: + names: $response.body.users[*].name + # -> ["Alice", "Bob"] +``` + +#### Indexing (`[n]`) + +```yaml +outputs: + first_user: $response.body.users[0].name + # -> "Alice" +``` + +#### Slicing (`[start:end]`) + +```yaml +outputs: + first_three: $response.body.items[0:3] +``` + +#### Filtering (`[?condition]`) + +Select array elements matching a condition: + +```yaml +# Given: [{"name": "Alice", "age": 25}, {"name": "Bob", "age": 35}] +outputs: + seniors: $response.body.users[?age > `30`].name + # -> ["Bob"] +``` + +> Literal numbers in filter conditions must be wrapped in backticks (`` `30` ``), as per JMESPath syntax. +{: .info} + +#### Functions + +```yaml +outputs: + avg_temp: avg($response.body.hourly.temperature_2m) + count: length($response.body.items) +``` + +**Numeric** + +| Function | Description | Example | +|---|---|---| +| `abs(val)` | Absolute value | `abs($inputs.delta)` | +| `avg(arr)` | Average of a numeric array | `avg($response.body.temps[*])` | +| `ceil(num)` | Round up | `ceil($response.body.score)` | +| `floor(num)` | Round down | `floor($response.body.score)` | +| `sum(arr)` | Sum of a numeric array | `sum($response.body.prices[*])` | + +**Array and object** + +| Function | Description | Example | +|---|---|---| +| `length(val)` | Length of array, object, or string | `length($response.body.items)` | +| `keys(obj)` | Keys of an object | `keys($response.body.config)` | +| `values(obj)` | Values of an object | `values($response.body.config)` | +| `sort(arr)` | Sort an array | `sort($response.body.scores[*])` | +| `sort_by(arr, &expr)` | Sort by expression | `sort_by($response.body.users[*], &age)` | +| `max(arr)` | Maximum value | `max($response.body.scores[*])` | +| `max_by(arr, &expr)` | Max by expression | `max_by($response.body.users[*], &age)` | +| `min(arr)` | Minimum value | `min($response.body.scores[*])` | +| `min_by(arr, &expr)` | Min by expression | `min_by($response.body.users[*], &age)` | +| `reverse(arr)` | Reverse array or string | `reverse($response.body.items)` | +| `flatten(arr)` | Flatten nested arrays (1 level) | `flatten($response.body.nested)` | +| `to_array(val)` | Wrap value in an array | `to_array($inputs.value)` | + +**String** + +| Function | Description | Example | +|---|---|---| +| `to_string(val)` | Convert to string | `to_string($response.body.id)` | +| `to_number(val)` | Convert to number | `to_number($response.body.count)` | + +**Type** + +| Function | Description | Example | +|---|---|---| +| `type(val)` | Returns the JSON type of a value | `type($response.body.result)` | + +> Nested function calls (like `length(sort($ref[*]))`) are not supported. +{: .warning} + +## String interpolation + +Multiple expressions can coexist in a single string: + +```yaml +outputs: + summary: "$steps.get_weather.outputs.temperature in $inputs.city" + # -> "22.5 in Marseille" +``` + +> String interpolation only works with dot notation expressions. JMESPath expressions (containing `[*]`, `[0]`, functions, etc.) are resolved as a whole and cannot be combined with other expressions in the same string. +{: .warning} + +## Conditions + +Expressions inside `when` clauses are resolved, then evaluated with standard operators. + +```yaml +actions: + - when: "$statusCode == 200" + do: next + - when: "$statusCode == 202" + do: retry + wait: 2 + - when: "$response.body.status == 'pending'" + do: retry +``` + +Supported operators: `==`, `!=`, `>`, `<`, `>=`, `<=`, `AND`, `OR`, `!`. + + +## Complete example + +```yaml +flower: "0.1" +id: weather +title: Get the weather for a specific city + +flows: + - id: weather_forecast + description: Get the weather forecast for a specific city + inputs: + properties: + city: + type: string + required: + - city + + steps: + - id: get_lat_lon + request: + method: GET + url: https://nominatim.openstreetmap.org/search + query: + q: $inputs.city + format: jsonv2 + outputs: + lat: $response.body.0.lat + lon: $response.body.0.lon + + - id: get_weather_forecast + request: + method: GET + url: https://api.open-meteo.com/v1/forecast + query: + latitude: $steps.get_lat_lon.outputs.lat + longitude: $steps.get_lat_lon.outputs.lon + daily: temperature_2m_min,temperature_2m_max + hourly: temperature_2m + outputs: + temperature_avg: avg($response.body.hourly.temperature_2m) + temperature_min: $response.body.daily.temperature_2m_min + temperature_max: $response.body.daily.temperature_2m_max + actions: + - when: "$statusCode == 200" + do: next + - when: "$statusCode == 429" + do: retry + wait: 10 + + outputs: + temperature_avg: $steps.get_weather_forecast.outputs.temperature_avg + temperature_min: $steps.get_weather_forecast.outputs.temperature_min + temperature_max: $steps.get_weather_forecast.outputs.temperature_max +``` diff --git a/src/_help/mcp-servers/secrets.md b/src/_help/mcp-servers/secrets.md new file mode 100644 index 00000000..30455c79 --- /dev/null +++ b/src/_help/mcp-servers/secrets.md @@ -0,0 +1,36 @@ +--- +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 new file mode 100644 index 00000000..d71e7a1b --- /dev/null +++ b/src/_help/mcp-servers/security.md @@ -0,0 +1,40 @@ +--- +title: Security +--- + +- TOC +{:toc} + +Bump.sh MCP servers are designed so that sensitive data never leaves the execution environment and is never exposed to the LLM. This page explains the architecture and the security measures in place. + +## Architecture + +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. + +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. + +These two components communicate over encrypted channels (TLS) and are deployed independently. + +> The default data plane is hosted on Bump.sh infrastructure. On Custom plans, it can be installed on-premise in your own infrastructure. +{: .info} + +## What each component can access + +| | Bump.sh application | Data plane | +|---|---|---| +| Server configuration | Yes | Yes | +| Workflow documents | Yes | Yes | +| Secret values (decrypted) | No | Yes, in memory at runtime only | +| API requests and responses | No | Yes, during execution only | +| Execution logs with sensitive data | No | No | + +## Data handling + +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. +- **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/_help/mcp-servers/specification-support/flower-support.md b/src/_help/mcp-servers/specification-support/flower-support.md new file mode 100644 index 00000000..93c8e283 --- /dev/null +++ b/src/_help/mcp-servers/specification-support/flower-support.md @@ -0,0 +1,259 @@ +--- +title: Flower support +--- + +- TOC +{:toc} + +Flower is the internal specification powering the Bump.sh [data plane](/help/mcp-servers/#data-plane). It was designed to keep workflow files as simple as possible, with no external dependencies. For a standardized approach to defining API workflows, we recommend using [Arazzo](/arazzo/v1.0/), the workflow specification from the OpenAPI Initiative. + +That said, thanks to its simplicity, Flower can replace Arazzo for small projects that don't require linking to OpenAPI files, or to describe workflows calling external APIs for which you don't have an OpenAPI document. + +The specification, along with a JSON Schema for validation and a set of utilities, is available on [GitHub](https://github.com/bump-sh/flower-spec). + +## Quick example + +This workflow looks up the current weather for a city by chaining two API calls: + +```yaml +flower: "0.1" +id: weather +title: Get the weather for a specific city + +flows: + - id: weather_current + description: Get the current weather for a specific city + inputs: + properties: + city: + type: string + required: + - city + + steps: + - id: get_lat_lon + request: + method: GET + url: https://nominatim.openstreetmap.org/search + query: + q: $inputs.city + format: jsonv2 + outputs: + lat: $response.body.0.lat + lon: $response.body.0.lon + + - id: get_weather_current + request: + method: GET + url: https://api.open-meteo.com/v1/forecast + query: + latitude: $steps.get_lat_lon.outputs.lat + longitude: $steps.get_lat_lon.outputs.lon + current: temperature_2m,is_day,wind_speed_10m + outputs: + temperature: $response.body.current.temperature_2m + + outputs: + temperature: $steps.get_weather_current.outputs.temperature +``` + +A Flower document defines a set of **flows**, each composed of sequential **steps**. Each step makes an HTTP request and extracts outputs that subsequent steps can reference. Flower documents can be written in YAML or JSON. YAML is recommended for readability. + +## Root properties + +| Property | Required | Description | +|----------|----------|-------------| +| `flower` | Yes | Specification version. Currently `"0.1"`. | +| `id` | Yes | Unique identifier for this workflow set. Use lowercase letters, numbers, and hyphens. | +| `title` | No | Human-readable title. | +| `description` | No | What this workflow set does. | +| `flows` | Yes | Array of flow definitions. | + +```yaml +flower: "0.1" +id: weather-service +title: Weather Information Service +description: Provides current weather and forecast information +flows: + - ... +``` + +## Flows + +A flow accepts inputs, executes a series of steps, and produces outputs. + +| Property | Required | Description | +|----------|----------|-------------| +| `id` | Yes | Unique identifier within the workflow set. | +| `description` | No | What this flow does. | +| `inputs` | No | Input parameters, defined using [JSON Schema](https://json-schema.org/) format. | +| `steps` | Yes | Array of step definitions, executed sequentially. | +| `outputs` | No | Values extracted from step results using [runtime expressions](#runtime-expressions). | + +### Inputs + +Inputs use JSON Schema to validate the parameters a flow accepts. + +```yaml +inputs: + properties: + city: + type: string + description: The name of the city + format: + type: string + enum: [celsius, fahrenheit] + default: celsius + required: + - city +``` + +Supported JSON Schema properties: `type` (`string`, `number`, `boolean`, `array`, `object`), `description`, `enum`, `default`, `required`. + +### Outputs + +Flow outputs extract data from step results. Each key maps to a [runtime expression](#runtime-expressions). + +```yaml +outputs: + temperature: $steps.get-weather.outputs.temperature + city_name: $steps.get-coords.outputs.city +``` + +## Steps + +A step represents a single HTTP request. Steps run sequentially within a flow. + +| Property | Required | Description | +|----------|----------|-------------| +| `id` | Yes | Unique identifier within the flow. Referenced by subsequent steps. | +| `request` | Yes | The HTTP request to execute. | +| `outputs` | No | Values extracted from the response. | +| `actions` | No | Conditional logic for flow control after this step. | + +### Request + +| Property | Required | Description | +|----------|----------|-------------| +| `method` | Yes | HTTP method: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`. | +| `url` | Yes | Endpoint URL. Supports [runtime expressions](#runtime-expressions). | +| `headers` | No | HTTP headers as key-value pairs. Values can use runtime expressions. | +| `query` | No | Query parameters as key-value pairs. | +| `body` | No | Request body (object or string). Typically used with `POST`, `PUT`, `PATCH`. | + +```yaml +steps: + - id: create_diff + request: + method: POST + url: https://bump.sh/api/v1/diffs + body: + previous_url: "$inputs.left_url" + url: "$inputs.right_url" + outputs: + id: $response.body.id +``` + +### Step outputs + +Outputs extract values from the HTTP response using [runtime expressions](#runtime-expressions). They become available to subsequent steps via `$steps..outputs.`. + +```yaml +outputs: + lat: $response.body.0.lat + lon: $response.body.0.lon +``` + +## Actions + +Actions control flow execution after a step completes. They are evaluated in order: the first matching action is executed. + +Each action has two properties: +- **`when`** (optional): A condition expression. If omitted, the action always matches. +- **`do`** (required): The action type. + +| Action type | Description | Extra properties | +|-------------|-------------|------------------| +| `next` | Continue to the next step. | | +| `retry` | Retry the current step. | `wait` (seconds, default: 5), `max_retry` (default: 5) | +| `goto` | Jump to a different step. | `step` (target step ID) | +| `end` | Terminate the flow and return outputs. | | + +```yaml +actions: + - when: "$statusCode == 202" + do: retry + wait: 2 + max_retry: 5 + - when: "$response.body.error" + do: end + - do: next +``` + +## Runtime expressions + +Runtime expressions reference dynamic data during execution. They use a `$` prefix with dot notation. + +| Expression | Description | +|------------|-------------| +| `$inputs.city` | Flow input parameter. | +| `$response.body.field` | Current step's response body. | +| `$response.body.0.lat` | Array index access. | +| `$steps.step_id.outputs.key` | Output from a previous step. | +| `$statusCode` | HTTP status code of the current response. | +| `$secrets.name` | Secret value (never exposed in outputs). | + +For the complete reference (JMESPath queries, conditions, resolution order), see [Runtime expressions](/help/mcp-servers/runtime-expressions). + +## Full example: API diff with retry + +This workflow creates an API diff and polls until the result is ready: + +```yaml +flower: "0.1" +id: bump +title: Bump.sh API diff + +flows: + - id: diff + description: Get a diff between 2 API documents + inputs: + properties: + left_url: + type: string + description: First API contract URL + right_url: + type: string + description: Second API contract URL + required: + - left_url + - right_url + + steps: + - id: create_diff + request: + method: POST + url: https://bump.sh/api/v1/diffs + body: + previous_url: "$inputs.left_url" + url: "$inputs.right_url" + outputs: + id: $response.body.id + + - id: get_diff + request: + method: GET + url: https://bump.sh/api/v1/diffs/$steps.create_diff.outputs.id + outputs: + result: $response.body.markdown + breaking: $response.body.breaking + actions: + - when: "$statusCode == 202" + do: retry + wait: 2 + - do: next + + outputs: + breaking: $steps.get_diff.outputs.breaking + result: $steps.get_diff.outputs.result +``` diff --git a/src/_help/mcp-servers/use-mcp-server.md b/src/_help/mcp-servers/use-mcp-server.md new file mode 100644 index 00000000..4802014c --- /dev/null +++ b/src/_help/mcp-servers/use-mcp-server.md @@ -0,0 +1,44 @@ +--- +title: Use an MCP server +--- + +- TOC +{:toc} + +To use an MCP server, the most common way is to add it to your IDE or AI tool. Some offer "one-click" addition, while others require a bit of configuration. If your tool is not listed, have a look at their documentation: MCP server integration might be supported. + +>If your Bump.sh MCP server is private, don't forget to select OAuth as the authentication type while adding the server to your tool. +{: .info} + +## ChatGPT +To add an MCP server to ChatGPT, go to Settings -> Apps -> Advanced settings -> Create app, and fill the MCP server URL field. + +![Add an MCP server to ChatGPT](/docs/images/help/mcp-servers/mcp-servers-chatgpt.png) + +> For now, adding custom Apps is only available in ChatGPT paid plans. +{: .info} + +## Claude +To add an MCP server to Claude (Desktop or web), go to Settings -> Connectors -> Add custom connector, and fill the URL field. + +![Add an MCP server to Claude](/docs/images/help/mcp-servers/mcp-servers-claude.png) + +> For now, adding custom connectors is only available in Claude paid plans. +{: .info} + +## Cursor +To add an MCP server to Cursor, go to Cursor Settings -> Tools & MCP -> New MCP server. It will open the `mcp.json` file, that you need to fill as below: +```json +{ + "mcpServers": { + "My Bump.sh MCP server": { + "url": "https://run.bump.sh/my-org/my-mcp-server/mcp" + } + } +} +``` + +## MCPJam (debug tool) +[MCPJam](https://www.mcpjam.com/) is a great tool to debug your workflows. It allows you to interact with the MCP server and analyze the requests sent by the LLM to the MCP server. To add an MCP server to MCPJam, click on "Add Server", and fill the "Connection Type" URL field. + +![Add an MCP server to MCPJam](/docs/images/help/mcp-servers/mcp-servers-mcp-jam.png) \ No newline at end of file diff --git a/src/docs/images/help/mcp-servers/mcp-servers-access-management.png b/src/docs/images/help/mcp-servers/mcp-servers-access-management.png new file mode 100644 index 00000000..5e80f583 Binary files /dev/null and b/src/docs/images/help/mcp-servers/mcp-servers-access-management.png differ diff --git a/src/docs/images/help/mcp-servers/mcp-servers-authorization-page.png b/src/docs/images/help/mcp-servers/mcp-servers-authorization-page.png new file mode 100644 index 00000000..dd7599c2 Binary files /dev/null and b/src/docs/images/help/mcp-servers/mcp-servers-authorization-page.png differ diff --git a/src/docs/images/help/mcp-servers/mcp-servers-chatgpt.png b/src/docs/images/help/mcp-servers/mcp-servers-chatgpt.png new file mode 100644 index 00000000..5f170835 Binary files /dev/null and b/src/docs/images/help/mcp-servers/mcp-servers-chatgpt.png differ diff --git a/src/docs/images/help/mcp-servers/mcp-servers-claude.png b/src/docs/images/help/mcp-servers/mcp-servers-claude.png new file mode 100644 index 00000000..6359a9fb Binary files /dev/null and b/src/docs/images/help/mcp-servers/mcp-servers-claude.png differ diff --git a/src/docs/images/help/mcp-servers/mcp-servers-creation-flow.png b/src/docs/images/help/mcp-servers/mcp-servers-creation-flow.png new file mode 100644 index 00000000..01853698 Binary files /dev/null and b/src/docs/images/help/mcp-servers/mcp-servers-creation-flow.png differ diff --git a/src/docs/images/help/mcp-servers/mcp-servers-dashboard.png b/src/docs/images/help/mcp-servers/mcp-servers-dashboard.png new file mode 100644 index 00000000..d1fac172 Binary files /dev/null and b/src/docs/images/help/mcp-servers/mcp-servers-dashboard.png differ diff --git a/src/docs/images/help/mcp-servers/mcp-servers-debug-server-access.png b/src/docs/images/help/mcp-servers/mcp-servers-debug-server-access.png new file mode 100644 index 00000000..8ca56c5e Binary files /dev/null and b/src/docs/images/help/mcp-servers/mcp-servers-debug-server-access.png differ diff --git a/src/docs/images/help/mcp-servers/mcp-servers-debug-session.png b/src/docs/images/help/mcp-servers/mcp-servers-debug-session.png new file mode 100644 index 00000000..abd6707d Binary files /dev/null and b/src/docs/images/help/mcp-servers/mcp-servers-debug-session.png differ diff --git a/src/docs/images/help/mcp-servers/mcp-servers-debug-sessions.png b/src/docs/images/help/mcp-servers/mcp-servers-debug-sessions.png new file mode 100644 index 00000000..ecf7aeac Binary files /dev/null and b/src/docs/images/help/mcp-servers/mcp-servers-debug-sessions.png differ diff --git a/src/docs/images/help/mcp-servers/mcp-servers-delete-server.png b/src/docs/images/help/mcp-servers/mcp-servers-delete-server.png new file mode 100644 index 00000000..375da29e Binary files /dev/null and b/src/docs/images/help/mcp-servers/mcp-servers-delete-server.png differ diff --git a/src/docs/images/help/mcp-servers/mcp-servers-deploy-new-document-button.png b/src/docs/images/help/mcp-servers/mcp-servers-deploy-new-document-button.png new file mode 100644 index 00000000..ace9cb68 Binary files /dev/null and b/src/docs/images/help/mcp-servers/mcp-servers-deploy-new-document-button.png differ diff --git a/src/docs/images/help/mcp-servers/mcp-servers-deployments.png b/src/docs/images/help/mcp-servers/mcp-servers-deployments.png new file mode 100644 index 00000000..a164ab42 Binary files /dev/null and b/src/docs/images/help/mcp-servers/mcp-servers-deployments.png differ diff --git a/src/docs/images/help/mcp-servers/mcp-servers-management.png b/src/docs/images/help/mcp-servers/mcp-servers-management.png new file mode 100644 index 00000000..578ff8a4 Binary files /dev/null and b/src/docs/images/help/mcp-servers/mcp-servers-management.png differ diff --git a/src/docs/images/help/mcp-servers/mcp-servers-mcp-jam.png b/src/docs/images/help/mcp-servers/mcp-servers-mcp-jam.png new file mode 100644 index 00000000..28c476ea Binary files /dev/null and b/src/docs/images/help/mcp-servers/mcp-servers-mcp-jam.png differ diff --git a/src/docs/images/help/mcp-servers/mcp-servers-secrets.png b/src/docs/images/help/mcp-servers/mcp-servers-secrets.png new file mode 100644 index 00000000..9d39b527 Binary files /dev/null and b/src/docs/images/help/mcp-servers/mcp-servers-secrets.png differ diff --git a/src/docs/images/help/mcp-servers/mcp-servers-start-stop-server.png b/src/docs/images/help/mcp-servers/mcp-servers-start-stop-server.png new file mode 100644 index 00000000..81a11b9e Binary files /dev/null and b/src/docs/images/help/mcp-servers/mcp-servers-start-stop-server.png differ diff --git a/src/docs/images/help/mcp-servers/mcp-servers-state.png b/src/docs/images/help/mcp-servers/mcp-servers-state.png new file mode 100644 index 00000000..3a04ac03 Binary files /dev/null and b/src/docs/images/help/mcp-servers/mcp-servers-state.png differ diff --git a/src/docs/images/help/mcp-servers/mcp-servers-web-upload.png b/src/docs/images/help/mcp-servers/mcp-servers-web-upload.png new file mode 100644 index 00000000..c17fc16a Binary files /dev/null and b/src/docs/images/help/mcp-servers/mcp-servers-web-upload.png differ diff --git a/src/docs/images/help/org-creation.png b/src/docs/images/help/org-creation.png index ea18a744..c7c57c4e 100644 Binary files a/src/docs/images/help/org-creation.png and b/src/docs/images/help/org-creation.png differ diff --git a/src/docs/images/icons/mcp.svg b/src/docs/images/icons/mcp.svg new file mode 100644 index 00000000..f5ca2578 --- /dev/null +++ b/src/docs/images/icons/mcp.svg @@ -0,0 +1,3 @@ + + +