# reShapr > reShapr is a no-code AI translation layer that instantly converts existing APIs (REST, gRPC, GraphQL) into secure, production-ready MCP (Model Context Protocol) servers — without writing a line of code. This file contains all documentation content in a single document following the llmstxt.org standard. ## How It Works reShapr is a zero-code AI translation layer. Instead of building an MCP server from scratch, you can use reShapr to instantly translate your existing APIs (REST, gRPC, GraphQL) into AI-native endpoints. With reShapr, you can create secure MCP servers in seconds without coding by connecting the platform to your existing API artifacts. As of today, reShapr supports ingesting: - OpenAPI 3.x specifications - GraphQL schemas - gRPC/Protocol Buffer definitions Once reShapr discovers your services, you configure: - Security mechanisms - Exposition options (all operations, read-only operations, etc.) - Existing backend endpoint targets Then reShapr exposes your MCP server through gateways in a multi-tenant and secure way. :::info Core Architecture At the core of reShapr is a robust architecture built to support service-level objectives and location constraints. The platform has two major parts: - **Control plane**: centralizes exposition configuration and policies. - **Data plane**: gateways that expose MCP servers and route runtime traffic. ::: This architecture supports multiple deployment models: 1. **Cloud**: reShapr hosts both the control plane and the data plane. 2. **Hybrid**: you host some gateways in your own trust domain while reShapr manages control. 3. **On-premises**: both control and data planes in your own environment. This is what flexibility means for enterprise MCP adoption. See also: - **[Why reShapr?](./why-reshapr.md)** - **[Configuration Plan and Exposition](../explanations/configuration-and-exposition.md)** - **[Security Options and Secrets](../explanations/security-model.md)** - **[Hybrid Deployment](../how-to-guides/deploy-hybrid-gateway.md)** --- ## Why reShapr? Hey hey… wondering why we built reShapr? 🤔 :::info Check out our 👉 [**blog post**](/blog/why-reshapr) on that topic! ::: ***Building Your Own MCP Server Is a Trap!*** *At first glance, building an MCP Server may seem straightforward. But very quickly, most teams realize:* - **It’s more than OpenAPI**: You need translation layers, prompt guards, retries, rate limiting, and grounding logic. - **Security gets messy fast**: How do you avoid exposing credentials in LLM prompts? How do you enforce identity, scope, and input validation? - **Fragility creeps in**: Most DIY solutions end up as brittle pipelines of JSON transforms, hardcoded logic, and embedded hacks that fall apart under load or, worse, leak data. This approach often duplicates your API logic into a parallel, standalone MCP layer, creating unnecessary complexity, increased maintenance overhead, and misalignment between your API and its AI-facing interface. > **A smarter approach** is to **extend your existing API** infrastructure, not **reinvent it** ! **reShapr exists to solve this exact problem!** Rather than building an MCP server from scratch, you can use reShapr to **instantly translate your existing APIs (REST, gRPC, GraphQL) into AI-native endpoints.** - **Zero** code - **No** rewrites - **No** custom Agents - **No** vendor lock-in --- ## Getting started with CLI This page details the installation and the basic usage of the reShapr Command Line Interface utility. ## Installation The `reshapr` CLI is an NPM package available at **[https://www.npmjs.com/package/@reshapr/reshapr-cli](https://www.npmjs.com/package/@reshapr/reshapr-cli)**. You can install it globally in your Linux or MacOS system. In a terminal window, just issue the following command: ```bash npm install -g @reshapr/reshapr-cli ``` From there, you can check that everything is correctly installed with: ```bash reshapr --version ``` With this output: ```bash 0.0.10 ``` The current `version` of the CLI is `0.0.10`. :::warning We're iterating fast! Make sure you're on the latest version so you don't miss any of the new magic 🚀 ::: You can also check the embedded help with this command: ```bash reshapr help ``` With this output: ```bash Usage: reshapr [options] [command] Reshapr CLI - A command line interface for Reshapr Options: -V, --version output the version number -h, --help display help for command Commands: service Manage services in Reshapr secret Manage secrets in Reshapr expo Manage expositions in Reshapr config Manage configuration plans in Reshapr gateway-group Manage gateway groups in Reshapr api-token Manage API tokens in Reshapr login [options] Login to Reshapr info Display information about current context and the Reshapr Server logout Logout from Reshapr attach [options] Attach an artifact to a Reshapr Service quotas [options] List and check your Reshapr quotas run [options] Start Reshapr locally using Docker Compose status Show the status of locally running Reshapr stop Stop locally running Reshapr containers help [command] display help for command ``` ## Login to reShapr While we use the **[reShapr Online Try](/docs/tutorials/try-reshapr-online)** in this tutorial, you should point the server URL to your own environment if you have one set up. Common URLs include `http://localhost:5555` for Docker Compose or your cluster’s ingress URL for Kubernetes. Use the following `login` command with the `-s` option (or `--server`) to specify you’re joining the beta platform: ```bash reshapr login -s https://try.reshapr.io ``` Once this output appears, the system will wait for you to complete the authentication process: ```bash ❯ reshapr login -s https://try.reshapr.io ℹ️ Opening browser: https://try.reshapr.io/cli/login?redirect_uri=http://localhost:5556 ℹ️ Listening for authentication callback on http://localhost:5556 ✅ Login successful! ℹ️ Welcome, yada! ℹ️ Organization: yada ✅ Configuration saved to /Users/yacine/.reshapr/config ``` :::info If you're using your own setup, you can authenticate non-interactively with the `--username` and `--password` flags. ::: You’ll see that your connection information and ephemeral token are stored under your home folder. `reshapr logout` allows you to clean up everything. Once connected, you can check the platform information: ```bash reshapr info ``` With this output: ```bash ❯ reshapr info ℹ️ User Information User : yada Organization: yada Server : https://app.try.reshapr.io ℹ️ Server Information Version : 0.0.10 Build time : 2026-03-17T17:26:05Z Mode : on-premises Internal IDP: undefined ``` :::info **From this step, you have two choices**: exploring the detailed concepts step-by-step and executing detailed commands **OR** going directly to the **[All-in-one magic command 🪄](#all-in-one-magic-command-)** ::: ## Import Artifact & Service Importing an artifact is the first step to exposing MCP endpoints for your API. Artifacts enable the discovery of Services as explained in **[Services & Artifacts](../explanations/services-and-artifacts.md)**. Let’s do that using the public **[Open-Meteo OpenAPI specification](https://github.com/open-meteo/open-meteo/blob/main/openapi/forecast.yml)**. For that we’ll need the **[Raw URL of this document](https://raw.githubusercontent.com/open-meteo/open-meteo/refs/heads/main/openapi/forecast.yml)** and we’ll use the `import` command: ```bash reshapr import -u https://raw.githubusercontent.com/open-meteo/open-meteo/refs/heads/main/openapi/forecast.yml ``` With this output: ```bash ✅ Import successful! ℹ️ Discovered Service Open-Meteo APIs with ID: 0PXEW1ZDWFCZS ``` :::info You can also import local files into reShapr using the `-f` option. There’s one caveat, though: we’re not able to discover dependencies using this mode. ::: You can now list and check the discovered Service with the `service` command: ```bash ❯ reshapr service list ID NAME VERSION TYPE AGE 0PXEW1ZDWFCZS Open-Meteo APIs 1.0 REST 19h ❯ reshapr service get 0PXEW1ZDWFCZS ℹ️ Service details ID : 0PXEW1ZDWFCZS Name : Open-Meteo APIs Version : 1.0 Organization: yada Type : REST Created : 2026-03-28T19:06:26.029291 Operations : - Name: GET /v1/forecast ``` :::info In case of a mistake or unused Service, you can delete a service using the `reshapr service delete ` command. ::: ## Configuring consumption **[Configuration Plan](../explanations/configuration-and-exposition.md)** will allow you to define how your Service will be consumed by MCP Clients. You’ll define the **backend endpoint** the MCP Gateway will target as well as the **security options** for future expositions. Let’s create a simple configuration plan for the **[Open-Meteo Service](https://github.com/open-meteo/open-meteo/blob/main/openapi/forecast.yml)** we just imported. For that, we need the Service identifier we got just before (`0PXEW1ZDWFCZS`), and we need to know the public endpoint of this API (`https://api.open-meteo.com`). We’ll use the `config create` command and provide a basic name and description: ```bash reshapr config create 'open-meteo-manual' --description 'Manual Plan for Open-Meteo APIs' \ --serviceId 0PXEW1ZDWFCZS --backendEndpoint https://api.open-meteo.com ``` With this output: ```bash ✅ Configuration plan 'open-meteo-manual' created successfully with ID: 0PXPDMB4MFE6H ``` > Like the `service` command, you can also use sub-commands like `list`, `get` or `delete` to manage your configurations. ## Exposing an MCP Endpoint Exposing a Configuration Plan will allow you to define where your Service will be made available to MCP Clients. By creating an exposition, you’ll define the **group of gateways** that will receive all the configuration information and will be in charge of exposing the MCP Endpoints. To create an exposition, we need the Configuration Plan identifier we got earlier (`0PXPDMB4MFE6H`), and we identify the group of gateways we want to deploy on. The default gateway group has the id `1`. We can then use the `expo create` command for that: ```bash reshapr expo create --configuration 0PXPDMB4MFE6H --gateway-group 1 ``` With this output: ```bash ✅ Exposition created successfully with ID: 0PXPE6HPWFE4H ℹ️ Exposition details ID : 0PXPE6HPWFE4H Created on : 2026-03-29T12:44:22.327792751 Organization: yada Service: ID : 0PXEW1ZDWFCZS Name : Open-Meteo APIs Version: 1.0 Type : REST Configuration Plan ID : 0PXPDMB4MFE6H Name : open-meteo-manual BackendEndpoint: https://api.open-meteo.com Included Ops. : [] Excluded Ops. : [] Gateway Group ID : 1 Name : Default Gateway Group Labels: {"env":"dev","team":"reshapr"} Gateway Endpoints - ID : 0PX4AF0BM0H7Z Name : prod-mcp-try-reshapr-proxy-7f8d7f6d89-c5jln Endpoints: mcp.try.reshapr.io/mcp/yada/Open-Meteo+APIs/1.0 - ID : 0PX4AF4200HQG Name : prod-mcp-try-reshapr-proxy-7f8d7f6d89-jhvtd Endpoints: mcp.try.reshapr.io/mcp/yada/Open-Meteo+APIs/1.0 ``` > Like the `service` command, you can also use sub-commands like `list`, `get` or `delete` to manage your configurations. 🎉 Hooray! You deployed an MCP Endpoint! Check the `Endpoints` information just above (`mcp.try.reshapr.io/mcp//Open-Meteo+APIs/1.0`): you can use this endpoint with `https://` prefix in your favorite MCP Client to access your new MCP Server! ## All-in-one Magic command 🪄 In case you didn’t take the shortcut, here’s the all-in-one command that does the same as above: ```bash reshapr import -u https://raw.githubusercontent.com/open-meteo/open-meteo/refs/heads/main/openapi/forecast.yml --backendEndpoint https://api.open-meteo.com ``` With this output: ```bash ✅ Import successful! ℹ️ Discovered Service Open-Meteo APIs with ID: 0PXEW1ZDWFCZS ✅ Exposition done! ✅ Exposition is now active! Exposition ID : 0PXPF1JQWFEF0 Organization : yada Created on : 2026-03-29T12:48:03.775297 Service ID : 0PXEW1ZDWFCZS Service Name : Open-Meteo APIs Service Version: 1.0 Service Type : REST -> https://api.open-meteo.com Endpoints : mcp.try.reshapr.io/mcp/yada/Open-Meteo+APIs/1.0 ``` Easy, No! 🎉 Congrats! You deployed an MCP Endpoint with just one CLI command! Check the `Endpoints` information just above (`mcp.try.reshapr.io/mcp//Open-Meteo+APIs/1.0`): you can use this endpoint with `https://` prefix in your favorite MCP Client to access your new MCP Server! --- ## Try reShapr online The fastest way to experience reShapr is through our hosted online environment: no installation required 🙌 Head over to **[try.reshapr.io](https://try.reshapr.io/)** to get started instantly. ## Login workflow ### Step 0 - Use your preferred web browser And go to: ```shell https://try.reshapr.io ``` ![Step 0 — Use your preferred web browser and go to the reShapr Try](/img/docs/try-reshapr-online-0.png) ### Step 1 — Choose an authentication provider Select **GitHub** or **Google** to authenticate with the reShapr online try. ![Step 1 — Select GitHub or Google to authenticate with reShapr Try](/img/docs/try-reshapr-online-1.png) ### Step 2 — Sign in with your provider Enter your credentials. In this example, we are using GitHub. ![Step 2 — GitHub sign-in form for reShapr Try authentication](/img/docs/try-reshapr-online-2.png) ### Step 3 — Two-factor authentication If you have two-factor authentication enabled, complete the verification step. ![Step 3 — Two-factor authentication prompt during GitHub login](/img/docs/try-reshapr-online-3.png) ### Step 4 — Setup your try org name You can customize your trial organization (change its default name if you’d like). ![Step 4 — Customize your trial organization and follow the instructions](/img/docs/try-reshapr-online-4.png) Then install the CLI: ```shell npm install -g @reshapr/reshapr-cli ``` and log in to Reshapr online: ```shell reshapr login -s https://try.reshapr.io ``` ### Step 5 — Authenticate with the CLI When the browser opens, authorize the CLI — the token is valid for **2 hours**. ![Step 5 — Authorize the reShapr CLI in the browser](/img/docs/try-reshapr-online-5.png) ### Step 6 — You're all set! Login is successful. You can now use the CLI to import APIs, create expositions, and manage MCP servers. Follow the instructions in the **[Getting Started](/docs/tutorials/getting-started)** tutorial to continue. ![Step 6 — CLI login successful, ready to use reShapr](/img/docs/try-reshapr-online-6.png) ### Step 7 — Access the online dashboard Once authenticated, you can go back to `https://try.reshapr.io` and you'll land on the reShapr Try dashboard. ![Step 7 — reShapr Try online dashboard after successful login](/img/docs/try-reshapr-online-7.png) --- ## Hybrid deployment As introduced in **[Why reShapr?](../overview/why-reshapr.md)**, the reShapr architecture allows deployment on several types and locations of Gateways, depending on your subscription plan. Thanks to this flexible architecture, the reShapr solution can be used in a **hybrid deployment** mode where you, as the *Acme Company*, can choose to host some reShapr Gateways within your own trust domain, close to your AI workloads and API backend endpoints. This gives you **full control over the data plane,** ensuring that your data never leaves your trusted environment! This page explains how a reShapr hybrid deployment works and how to implement it. ## Overview The **[Gateway Group & Gateway](../explanations/gateway-groups-and-gateways.md)** page introduces the core concepts of this deployment architecture: - The *Gateway Groups* represent the abstract target of your MCP Server exposition - it is owned by an organization and defines labels for matching *Gateways*, - The *Gateways* are the concrete elements that expose your MCP Servers; they receive deployment directives and configuration plans from the reShapr control plane. When it’s running, a reShapr Gateway discovers the MCP Servers it has to expose from the control plane. This discovery is made according to the **[Exposition](../explanations/configuration-and-exposition.md)** you previously created and the Gateway Groups you chose. To do so, the Gateway presents **a set of label selectors** that will be used during the discovery and throughout its lifetime to synchronize its **[Service](../explanations/services-and-artifacts.md)** definitions and **[Configuration Plans](../explanations/configuration-and-exposition.md)**. While it is alive, an ephemeral Gateway representation is tied to the Gateway Group in the control plane. A Gateway is not necessarily attached to a single Gateway Group; it can be attached to many groups as long as its selectors match the group's labels! You could have a set of Gateways with a unique selector `org=acme` matching all Acme’s Gateway Groups. ### Lifecycle A *Gateway* starts, lives, and terminates according to a certain lifecycle. Below are the different elements covering this lifecycle: 1. The first stage of a Gateway life is the **Registration phase**. A Gateway is configured to be connected to a control plane instance (a hostname and a port). During startup, the Gateway advertises itself to the control plane, providing an API Token for authentication, its unique identifier, its label selectors, and the information of the URLs which can be used for reaching this Gateway. 1. If authentication is successful, then the Gateway is registered into the control plane, and it fetches its **[Service](../explanations/services-and-artifacts.md)** definitions and **[Configuration Plans](../explanations/configuration-and-exposition.md)** for exposing the MCP Servers, 2. If authentication fails, then the Gateway stops with an error message. 2. After successful registration, the Gateway starts a **Health check** process. This health check will be done every 2 minutes and is acknowledged by the control plane. 1. If a health check cannot happen because of the control plane being unavailable, the Gateway is considered *unsynchronized* - a **Registration** phase will be done upon reconnection, 2. If the control plane doesn’t receive a health check from the Gateway in 5 minutes, it removes this Gateway from its internal list and marks it as *unsynchronized*. It will force a new **Registration**. 3. MCP Servers execution is not interrupted during health check issues. 3. After successful registration, the Gateway also starts a **Changes Streaming** process: the control plane can push the relevant notification changes based on its label selectors. 1. Upon changes reception, the MCP Servers are immediately updated or removed without interruption. 2. If a new **Registration** happens (due to a connectivity issue), this streaming process is updated accordingly. 4. On process shutdown, the Gateway starts the **Termination** phase: 1. Health checks are stopped, and a termination notification is sent to the control plane for the removal of its internal Gateway representation. 2. The changes streaming process is stopped, and communication is cleaned. 3. MCP Servers stop handling incoming requests. ### Security It’s worth noting the following security characteristics of this architecture: - Communication between the control plane and Gateways is always at the initiative of the gateways through an upstream network channel. The Gateway must be able to reach out to the control plane, and then bi-directional streaming is set up on the same communication channel. Network admin doesn’t have to set up any ingress access for the control plane to reach out to the Gateway - only the egress route to the control plane is necessary. - Communication is done over **[gRPC](https://en.wikipedia.org/wiki/GRPC)** protocol, that used **[HTTP/2](https://en.wikipedia.org/wiki/HTTP/2)** with **[TLS](https://en.wikipedia.org/wiki/Transport_Layer_Security)**. On top of that, reShapr implements token-based authorization with an API Token that is generated, renewed, and revoked by the control plane. You can decide to share the API Token among different gateways or have an API Token per gateway. - When running in this hybrid mode, the control plane only holds the configuration of your MCP Servers: the **[Services & Artifacts](../explanations/services-and-artifacts.md)** definition as well as the **[Configuration Plan & Exposition](../explanations/configuration-and-exposition.md)**. All the application data: the exchanges between your Agents, LLM, MCP Clients, and your backend API (including the reShapr MCP Servers) stay in your datacenter! - Since reShapr `0.0.14`, backend **[secret references](../explanations/security-model.md#secret-references)** can keep actual backend credentials local to the Gateway runtime while the control plane only stores references such as `${env:GITHUB_TOKEN}`. - Because the Gateway runs in the location of your choice, it can now access any private Authorization Server or IDP you may want to use via the **[Security options & Secrets](../explanations/security-model.md)**! ## Installation ### Retrieve an API Token for your Gateway(s) To retrieve an API token for your gateway(s), follow these steps from the reShapr CLI. 1. Log in to the Control Plane using the following command: ```bash reshapr login ``` 2. Once logged in, use the following command to generate a new API token with a validity period of 90 days (which is the maximum allowed): ```bash reshapr api-token create -v 90 ``` This command will display the value of the newly created API token in the terminal. Typically, something like: > The API Token to register the Gateway is: acme-oXYvTI8f8BeuJ5-HlNuon6vs2wSao8qS7WRNIYwoFW4 :::warning Make sure to store it securely, as it will not be shown again. ::: 3. Copy the displayed API token and store it securely, as it will not be shown again. You will need this token to register your gateway(s) with the Control Plane. ### Define or identify a Gateway Group for your Gateway(s) Before registering your gateway(s), you need to define or identify a Gateway Group in the Control Plane. A Gateway Group is a logical grouping of gateways that share common configurations and policies. 1. You can list your gateway groups using the following CLI command. If you already have a Gateway Group that you want to use, make a note of its ID and labels. ```bash reshapr gateway-group list ``` This is the default output you'll get the first time: ```bash ID ORG NAME LABELS 1 reshapr Default Gateway Group {"env":"dev","team":"reshapr"} ``` 2. If you do not have an existing Gateway Group that suits your needs, you can create a new one using the following command. You can use labels that will help you identify and manage your gateways effectively and are appropriate for your use case: ```bash reshapr gateway-group create 'QA Gateway Group for XYY' --labels '{"env":"qa", "project":"xyz"}' ``` This command will create a new Gateway Group and display its details, similar to the following: ```bash ✅ Gateway group 'QA Gateway Group for XYY' created successfully with ID: 0P58T3XKK1MEQ ``` 3. Make a note of the *Gateway Group* ID and labels, as you will need them when registering your gateway(s). ### Start/Register your Gateway(s) with the Control Plane To start and register your gateway(s) with the control plane, you will need to provide the API token and *Gateway Group* information you obtained in the previous steps. When starting the reShapr Gateway container, you need to set the following environment variables: - `RESHAPR_CTRL_HOST`: The hostname of the reShapr Control Plane (e.g., `app.beta.reshapr.io`). - `RESHAPR_CTRL_PORT`: The port number of the reShapr Control Plane (e.g., `443`). - `RESHAPR_CTRL_TLS_PLAINTEXT`: A flag to disable plain-text communication over TLS. Set it to `false`. - `RESHAPR_CTRL_TOKEN`: The API token you retrieved to authorize your gateway. - `RESHAPR_GATEWAY_ID`: A unique identifier for your gateway (e.g., `acme-gateway-01`). - `RESHAPR_GATEWAY_FQDNS`: A comma-separated list of *Fully Qualified Domain Names* that represent the hosts that can be used to reach out to your gateway. If none are provided, it defaults to `localhost`. - `RESHAPR_GATEWAY_LABELS`: The labels associated with your gateway, in the format `key1=value1,key2=value2`. These labels must match the ones from the *Gateway Group* you're targeting (e.g., `env=qa,region=eu-west-3`). :::warning **Important:** The Gateway ID must be unique across all gateways registered in the Control Plane! We recommend using a naming convention that includes your organization to ensure uniqueness. ::: The port `7777` is the default port used by the reShapr Gateway for incoming traffic. You can adjust this port mapping as needed. Here is an example `docker run` command to start the reShapr Gateway container with the necessary environment variables: ```bash docker run -it --rm -p 7777:7777 \ -e RESHAPR_CTRL_HOST=app.beta.reshapr.io \ -e RESHAPR_CTRL_PORT=443 \ -e RESHAPR_CTRL_TLS_PLAINTEXT=false \ -e RESHAPR_CTRL_TOKEN=acme-oXYvTI8f8BeuJ5-HlNuon6vs2wSao8qS7WRNIYwoFW4 \ -e RESHAPR_GATEWAY_ID=acme-gateway-01 \ -e RESHAPR_GATEWAY_FQDNS=mcp-1.qa.acme.com,mcp-2.qa.acme.com \ -e RESHAPR_GATEWAY_LABELS=env=qa \ ttl.sh/reshapr-gateway-276ee61b-1378-470c-9651-72cdb094c6e4:12h ``` ### Deploy your MCP Endpoint on the Gateway Once your reShapr Gateway is up and running and registered with the Control Plane, you can deploy your MCP Endpoint on it. Actually, you don't directly deploy the MCP Endpoint on the Gateway, but you rather specify a Gateway Group that should be used when exposing your MCP Endpoint. If your Gateway belongs to that Gateway Group and is started, the MCP Endpoint will be automatically deployed on that Gateway. Using the reShapr CLI, you can specify the `--gateway-group` parameter to indicate which Gateway Group should be used for that endpoint. Reusing the Gateway Group created in the previous steps, here is an example command to create an MCP Endpoint associated with that Gateway Group: ```bash reshapr expo create --configuration 0P5GDHQHB1MZS --gateway-group 0P58T3XKK1MEQ ``` You should then see some logs on the Gateway side that receive information about your MCP Server to expose. --- ## Docker Compose Learn how to run reShapr locally using Docker Compose for development and testing purposes. ## Prerequisites Before you begin, make sure you have the following installed on your machine: - **[Docker](https://docs.docker.com/get-docker/)** (with Docker Compose v2) - **[Node.js](https://nodejs.org/)** (v18 or later) needed for the reShapr CLI - The **reShapr CLI** installed globally: ```bash npm install -g @reshapr/reshapr-cli ``` ## Quick start with the CLI The simplest way to run reShapr locally is through the `reshapr run` command. It automatically downloads the correct Docker Compose file from GitHub, configures the container images for the requested release, and starts everything in the background. ```bash reshapr run ``` ```bash ℹ️ Resolved 'latest' to release '0.0.10'. ℹ️ Downloading compose file from https://raw.githubusercontent.com/reshaprio/reshapr/refs/tags/0.0.10/install/docker-compose-all-in-one.yml... ✅ Compose file saved to /Users/you/.reshapr/docker-compose-0.0.10.yml ℹ️ Starting Reshapr containers (release: 0.0.10)... ✅ Reshapr containers started successfully. ``` By default, this pulls the **latest** stable release. You can also target a specific release or use the **nightly** build: Run a specific release: ```bash reshapr run --release 0.0.10 ``` Run the nightly build (latest from main branch): ```bash reshapr run --release nightly ``` The compose file is cached at `~/.reshapr/docker-compose-.yml`, so subsequent runs reuse it without re-downloading. ## Check status Once the containers are running, verify their status: ```bash reshapr status ``` ```bash ℹ️ Reshapr containers (release: 0.0.10, started at: 2026-04-01T10:30:00.000Z) NAME IMAGE ... STATUS reshapr-ctrl-1 registry.reshapr.io/reshapr/reshapr-ctrl:0.0.10 ... Up 2 minutes reshapr-proxy-1 registry.reshapr.io/reshapr/reshapr-proxy:0.0.10 ... Up 2 minutes reshapr-db-1 postgres:17 ... Up 2 minutes ``` The control plane is available at **`http://localhost:5555`** and the MCP gateway at **`http://localhost:7777`**. ## Log in with the CLI With your user created, authenticate the CLI against your local control plane: ```bash reshapr login --server http://localhost:5555 ``` You'll be prompted for your username and password. Once authenticated: :::info The default username is `admin`, and the default password is `password`. ::: ```bash reshapr login --server http://localhost:5555 ``` ```bash ℹ️ Enter your credentials ✅ Login successful! ℹ️ Welcome, admin! ℹ️ Organization: reshapr ✅ Configuration saved to /Users/you/.reshapr/config ``` > From here, you can follow the **[Getting Started tutorial](../tutorials/getting-started.md)** to import services, create configuration plans, and expose MCP endpoints; just point everything at your local instance. ## Stop the containers When you're done, shut everything down: ```bash reshapr stop ``` ```bash ℹ️ Stopping Reshapr containers (release: 0.0.10)... ✅ Reshapr containers stopped successfully. ``` This runs `docker compose down` on the saved compose file and cleans up the run state. ## Manual setup (without the CLI) If you prefer to manage Docker Compose directly, clone the reShapr repository and use the provided scripts: ```bash git clone https://github.com/reshaprio/reshapr.git ``` ```bash cd reshapr/install ``` Start all services (control plane, gateway, and database) at once: ```bash docker compose -f docker-compose-all-in-one.yml up ``` The `install/` folder also includes helper scripts: - `start-all.sh`- a simple script to run the `docker compose` command above Or start components separately, the control plane first: ```bash docker compose up ``` Then, the gateway proxy in a separate terminal: ```bash docker run -it --rm -p 7777:7777 \ -e RESHAPR_CTRL_HOST=host.docker.internal \ --add-host=host.docker.internal:host-gateway \ registry.reshapr.io/reshapr/reshapr-proxy:nightly ``` The `install/` folder also includes helper scripts: - `start-control-plane.sh` - a simple script to run the `docker compose` command above - `start-proxy.sh` - a simple script to run the `docker run` command above :::info The `host.docker.internal` mapping lets the proxy container reach the control plane running on your host machine. ::: ## Next steps - **[Getting Started with CLI](../tutorials/getting-started.md)** — import services and expose MCP endpoints - **[Install on Kubernetes](./kubernetes.md)** — deploy reShapr using Helm charts - **[How it works](../overview/how-it-works.md)** — understand the reShapr architecture --- ## Helm Charts Learn how to deploy reShapr on Kubernetes using Helm charts for production-grade environments. ## Prerequisites - Kubernetes 1.25+ - Helm 3.8+ - A PostgreSQL database (or use the embedded one for development) ## Overview reShapr provides two Helm charts, distributed as **OCI artifacts**: | Chart | Purpose | OCI artifacts | |-------|---------|---------------| | `reshapr-control-plane` | Control plane API server + database | `https://quay.io/repository/reshapr/reshapr-helm-charts/reshapr-control-plane` | | `reshapr-proxy` | MCP gateway (data plane) | `https://quay.io/repository/reshapr/reshapr-helm-charts/reshapr-proxy` | ## All instructions are on GitHub :::note Please read 👉 [https://github.com/reshaprio/reshapr-helm-charts](https://github.com/reshaprio/reshapr-helm-charts) ::: ## Next steps - **[Getting Started with CLI](../tutorials/getting-started.md)** — import services and expose MCP endpoints - **[Run using Docker Compose](./docker-compose.md)** — run reShapr locally for development - **[How it works](../overview/how-it-works.md)** — understand the reShapr architecture - **[Security Model](../explanations/security-model.md)** — learn about reShapr security --- ## Configuration Plan & Exposition Before being turned into an MCP Server endpoint, a reShapr **[Service](services-and-artifacts.md)** must have a *Configuration Plan* defined. A Configuration Plan will allow you to define how your Service will be consumed by MCP Clients. You’ll define the **backend endpoint** the reShapr Gateway will target as well as the **security options** you want to apply to future expositions. In a nutshell, a Configuration Plan will allow you to define: - The backend endpoint URL of the existing service or API implementation you’re targeting, - The list of the Service operations you’d like to expose - you can choose, for example, to restrict access to read-only operations only, or to hide non-relevant operations, - The **[security options](security-model.md)** you’d like to enable for securing the access of the MCP endpoints - you can choose to secure access with an API key or using an OAuth Authorization Server, - The required permissions needed to access the MCP Server tools, resources, or prompts - you can specify additional scopes for the write operations, for example. - The **[credentials Secret](services-and-artifacts.md)** the MCP Server will present to authorize access to the backend endpoint. A reShapr Service can have multiple Configuration Plans that match different environments or lifecycle stages. A Configuration Plan is always associated with a specific version of a Service and has to be replicated for other versions. Creating a Configuration Plan is not enough for your MCP Server to be ready and usable by your MCP Client. To do so, you must expose - ie **create an Exposition** - of your Configuration Plan. This last step before consuming a reShapr MCP Server endpoint is a simple declaration that allows you to target a reShapr Gateway. As introduced in **[Why reShapr?](../overview/why-reshapr.md)**, reShapr allows deployment on different types and locations of Gateways depending on your subscription plan. Creating an exposition is a simple operation that associates a Configuration Plan to a Gateway Group - a logical representation of gateways actually running MCP Servers. Check our next **[Gateway Group & Gateway](gateway-groups-and-gateways.md)** section if you want to learn more. --- ## Gateway Group & Gateway Gateway Groups & Gateways are the last pieces to fully understand the reShapr possibilities from end-to-end! As it has been introduced in **[Why reShapr?](../overview/why-reshapr.md)**, the reShapr architecture allows deployment on different types and locations of Gateways depending on your subscription plan. In the reShapr architecture, the Gateways are not typically known from the start and are presented in a static list. Gateways are made to be started and stopped in a highly dynamic way and advertise themselves to the control plane at startup. However, to define the exposition and deployment targets of your MCP server, the control plane can define its policies using abstract representations called *Gateway Groups*. A Gateway Group is a named resource owned and dedicated to an organization. The `reshapr` organization is a special one that shares its gateway groups with the reShapr users. A Gateway Group also defines a set of labels that represent **exposition policies and criteria**. Labels can represent a geographical region, a certain SLO and performance level, a lifecycle environment, or a combination of all of these. Depending on your subscription plan, you will have access to one or more Gateway Groups. During its bootstrap phase, a reShapr Gateway will advertise itself to the control plane and discover the MCP Servers it has to expose. This discovery is made according to the **[Exposition](configuration-and-exposition.md)** you previously created and the policies or Gateway Groups you choose. To do so, the Gateway presents **a set of selectors** that will be used during the discovery and throughout its lifetime to synchronize its **[Service](services-and-artifacts.md)** definitions and **[Configuration Plans](configuration-and-exposition.md)**. While it is alive, an ephemeral Gateway representation is tied to the Gateway Group in the control plane. A Gateway is not necessarily attached to a single Gateway Group; it can be attached to many of them as long as its selectors match the labels (exposition criteria) of the group! You could have a set of Gateways with a unique selector `org=acme` matching all Acme’s Gateway Groups. --- ## Security options & Secrets Security of MCP endpoints is a hot topic and let’s face it: a fast-moving one! For that, reShapr has been designed to be flexible and allow many different security options. It has been implemented to allow evolution following the emerging best practices. In a nutshell, the security options we’ll expose just after will encompass two different concerns: - Access to the MCP Endpoint exposed by a reShapr gateway itself, - Access to the backend API used by the reShapr gateway once MCP endpoint access is safe. ## MCP Endpoint access Three different options are available to secure the MCP Server or Endpoint exposed by a reShapr gateway: - **None** - which is the *default* and probably not a good idea! This means that the gateway endpoint is unsecured. In this situation, all headers are propagated to the backend API. So this is a scenario that you would use just for a quick test OR if you decide - with great generosity - to provide a free MCP Server to the world! - **API Key** - means that the gateway will validate the value of the specific `x-reshapr-key` header in the incoming MCP requests. The API Key is generated and transmitted just once at configuration time. It represents a token that you must store securely and must only share with trusted users. reShapr allows renewing an API Key and propagates the change to the gateways exposing the corresponding service. - **OAuth2 Bearer** - means that the gateway will validate the OAuth2 token provided as a `Bearer` in the `Authorization` header in the incoming requests. During the configuration time, you choose your OAuth2 Authorization Servers and the list of required scopes to access the MCP Server. This information is propagated to the gateways that will be in charge of trusting the incoming tokens. reShapr gateways implements the different specifications mentioned in the **[Model Context Protocol Version 2025-06-18 Authorization](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization)** recommendations such as: - OAuth 2.0 Protected Resource Metadata ([**RFC9728**](https://datatracker.ietf.org/doc/html/rfc9728)) - OAuth 2.0 Authorization Server Metadata ([**RFC8414**](https://datatracker.ietf.org/doc/html/rfc8414)) - OAuth 2.0 Resource Indicators ([**RFC 8707**](https://www.rfc-editor.org/rfc/rfc8707.html)) ## Backend Secrets In addition to protecting the MCP Endpoint or Server, access to the backend API must also be protected. This backend must have a means to validate authentication and authorization proofs coming from the reShapr gateway. For this purpose, reShapr supports the concept of `Secret`, which enables the secure storage of information on how to authenticate the backend API call. In reShapr, a Secret can contain different information: - **A username/password pair** - in case the backend API only supports HTTP Basic authentication mechanisms. An `Authorization: Basic ` header will be automatically issued and transmitted to the backend API. - **A token (with an optional associated header)** - in case the backend supports API Key or token-based authentication mechanisms. If no token header is provided, then the default `Authorization: Bearer ` is assumed and transmitted to the backend API, but the token header can hold any value. - **A X509 certificate** - that will be used to secure the transport, in case the backend API is enforcing TLS communication with a client-side certificate. reShapr also supports **Elicitation-based backend secret**. **[Elicitations](https://modelcontextprotocol.io/specification/2025-11-25/client/elicitation)** are a recent addition to the MCP Protocol, coming in version `2025-11-25` of the protocol. Unlike a standard backend Secret, an Elicitation-based one does not require proactive provisioning: when needed, the reShapr MCP Server will return to the user to request backend credentials or initiate an OAuth authorization flow. Two different flows are supported: - The [**URL Mode Elicitation for Sensitive Data**](https://modelcontextprotocol.io/specification/2025-11-25/client/elicitation#url-mode-elicitation-for-sensitive-data) - in case your User has its own token/API key/authorization code to access the backend API. - The [**URL Mode Elicitation for OAuth Flows**](https://modelcontextprotocol.io/specification/2025-11-25/client/elicitation#url-mode-elicitation-for-oauth-flows) - in case your User has to complete an OAuth / OIDC authorization flow to enable the MCP Server to get an authorization code to access the backend API. ### Secret references Available since reShapr `0.0.14`, backend Secrets can also use **secret references**. This is especially useful in hybrid deployments where the control plane is managed by reShapr, but the Gateway runs in your own premises. In this situation, you may want the control plane to know that a backend credential exists without storing or distributing the actual credential value. A secret reference uses the `${scheme:reference}` convention. When a sensitive value follows this pattern, the Gateway resolves it locally when it needs to call the backend endpoint. The value stored in the control plane is only the reference. Today, the supported scheme is `env`, which resolves a value from the Gateway environment: ```bash ${env:GITHUB_TOKEN} ``` When the Gateway needs to authenticate a backend call, it reads `GITHUB_TOKEN` from the Gateway process environment, falling back to the Gateway configuration sources such as system properties or a `.env` file. If the value cannot be resolved, the backend call fails explicitly instead of silently sending an empty credential. References can be used on their own or interpolated within a larger value: ```bash Bearer ${env:API_TOKEN} ${env:DB_USER}:${env:DB_PASSWORD} ``` Values that do not match the `${scheme:reference}` convention keep being used as literal Secret values, so existing Secrets remain compatible. Secret references are resolved **just in time**, on every backend call. Resolved values are not cached as control plane data, and they do not need to be synchronized from the control plane to the Gateway. This also makes secret rotation straightforward: update the value in the Gateway environment, and the next backend call uses the new value. Secret references are honored for sensitive credentials used by the Gateway to reach backend endpoints: - Token authentication for REST, GraphQL, and gRPC backends, - Basic authentication username and password, - PEM-encoded TLS trust material for gRPC backends, - OAuth2 client secrets used during authorization-code exchanges. Public identifiers, such as an OAuth2 `client_id`, are intentionally kept as literal values because they are exposed in the browser redirect by design. Using secret references moves the responsibility for protecting the real credential to the Gateway environment. You should scope environment variables to the Gateway process, prefer mounted secrets where your platform supports them, and make sure resolved values are never written to logs or audit trails. ## All together! MCP Endpoint security options and backend secret are not exclusive, and they’d rather be combined to secure the transmission chain from end to end. To achieve fully secure and authorized usage of your MCP Endpoint provided by reShapr, we recommend considering OAuth2 + Elicitation-based backend Secret when you configure your **[Service](services-and-artifacts.md)** for exposure on a reShapr gateway. In hybrid deployments, secret references can be added to this model when the actual backend credential must remain local to your Gateway runtime. --- ## Services & Artifacts As explained in **[Why reShapr?](../overview/why-reshapr.md)**, reShapr ingests your API’s existing artifacts such as **[OpenAPI 3.x](https://www.openapis.org/)** specs, **[GraphQL](https://graphql.org/)** schemas and **[gRPC/Protobuffer](https://grpc.io/)** definitions to discover Services and create MCP Servers. A Service in reShapr represents a functional service promise - for example, a *User Management Service* with a specific version - for example, `1.0` - made of several operations (`searchUsers`, `getUserById,`, etc.). Services are versioned so you’ll be able to handle the different versions of the *User Management Service*, which can be `1.0`, `1.1`, `2.0` and so on… Your first steps with reShapr will certainly be to import new artifacts into the system so that reShapr can discover and propose Services to expose. As of today, this task is realized using the **[reShapr CLI](../tutorials/getting-started.md)** that holds the `reshapr import` tool. But before diving into the Getting Started guide, let’s review the information and conventions reShapr is using from these specifications. - When importing an **[OpenAPI 3.x](https://www.openapis.org/)** artifact, reShapr will naturally use the `info.name` and `info.version` that are mandatory elements in the specification. The discovered Service will then naturally have this name and version, - When importing a **[gRPC/Protobuffer](https://grpc.io/)** definition, reShapr will look for a Protocol Buffer `service` definition and will return the first it finds. reShapr will also look at the `package` directive. This package information will be used for two purposes: to provide a full name for the reShapr service that will be `.` and to extract the version information. As it’s a best practice to put the version as the last element of a package name in gRPC, reShapr will use the last element as the version. - When importing a **[GraphQL](https://graphql.org/)** schema, things are a bit different because Graph Schema doesn’t have a way to provide information on the service name or version. So when importing a GraphQL schema in reShapr, you will have to explicitly provide the `serviceName` and the `serviceVersion` you want this service to be registered as. As Services are versioned in reShapr, the direct consequence is that reShapr will be able to keep many different versions of the same Service in parallel. It will then be up to you to manage the expositions of version `1.0`, then version `2.0` etc. When a version of a service is no longer of importance to you, you can delete it - but it will automatically remove existing expositions. Updating a Service in reShapr is a trivial process; it simply means re-importing its reference artifacts. If its service name and version are already present in reShapr, the definition will be updated. If not, a new Service entry will be created and attached to your account. ## Managing Artifacts A Service in reShapr is backed by one or more artifacts. The first artifact you import (using `reshapr import`) becomes the **main artifact** — it defines the Service identity, operations, and type. You can then attach additional artifacts (using `reshapr attach`) to enrich the Service with **[Prompts](../references/prompts-specification.md)** or **[Custom Tools](../references/custom-tools-specification.md)** definitions. ### Listing artifacts You can list all artifacts associated with a Service using the `reshapr artifact list` command. This is useful to see what has been imported or attached previously: ```bash reshapr artifact list -s 0N2G4YZFDD3ZF ``` ```bash ID NAME TYPE MAIN 0NKVYHWSR9VPT github-api.graphql GRAPHQL_SCHEMA Yes 0NKVZAB12X3YZ github-api-prompts RESHAPR_PROMPTS No ``` The `MAIN` column indicates which artifact is the primary definition for the Service. Only one artifact can be the main artifact per Service. ### Inspecting an artifact To retrieve details of a specific artifact, use `reshapr artifact get`: ```bash reshapr artifact get 0NKVYHWSR9VPT ``` ```bash ℹ️ Artifact details ID : 0NKVYHWSR9VPT Name : github-api.graphql Organization : my-org Service ID : 0N2G4YZFDD3ZF Type : GRAPHQL_SCHEMA Main Artifact: Yes Source : github-api.graphql Path : N/A ``` You can also display the full artifact content (syntax-highlighted) by adding the `-d, --display` flag: ```bash reshapr artifact get 0NKVYHWSR9VPT -d ``` Both commands support the `-o, --output ` option for structured output in `json` or `yaml` format, which is convenient for automation. See the **[CLI Commands Reference](../references/cli-commands.md)** for the full details on all available options. --- ## reShapr CLI Reference ## Authentication commands ### `reshapr login` command The login command authenticates you against a reShapr control plane. Depending on the server configuration (SaaS, on-premises with OIDC, or on-premises with local credentials), the CLI will automatically select the appropriate authentication flow. ```bash reshapr login [options] ``` Available options: - `-u, --username ` : Your reShapr username (for password-based login) - `-p, --password ` : Your reShapr password (for password-based login) - `-o, --org ` : Your reShapr organization name - `-s, --server ` : Your reShapr Control Plane URL (defaults to `https://try.reshapr.io`) - `-k, --insecure` : Skip SSL certificate validation - `--password-stdin` : Read password from stdin (mutually exclusive with `-p`) :::info For SaaS or OIDC-enabled on-premises servers, the CLI will automatically open your browser for the authorization flow. A temporary local server is started to receive the authentication callback. ::: Here's an example of logging in to a local on-premises server: ```bash reshapr login --server http://localhost:5555 ``` For non-interactive environments (CI/CD), you can pipe the password from stdin: ```bash echo "$RESHAPR_PASSWORD" | reshapr login -u admin --password-stdin --server http://localhost:5555 ``` ### `reshapr logout` command The logout command clears your local authentication session. ```bash reshapr logout ``` ### `reshapr info` command The info command displays information about your current authentication context and the connected reShapr server. ```bash reshapr info ``` ```bash ℹ️ User Information User : admin Organization: my-org Server : https://try.reshapr.io ℹ️ Server Information Version : 0.0.11 Build time : 2025-05-10T08:30:00Z Mode : saas Internal IDP: https://idp.reshapr.io ``` ## Artifact commands ### `reshapr import` command The import command allows you to push (or have reShapr pull) a new artifact into reShapr. This will allow it to discover a new Service as explained in **[Services & Artifacts](../explanations/services-and-artifacts.md)**. First, you have to tell reShapr how to proceed with retrieving this artifact. You can use: - `-f, --file ` to reference a local file you want to upload, - `-u, --url ` to ask the reShapr control plane to download a remote file. :::info When specifying a remote URL with the `-u` option, it can also be useful to specify a Secret with the `-s, --secret ` option to authorize access to the remote endpoint. Check the **[Secret commands](cli-commands.md)** just below to learn how to create them. ::: The discovery of the artifact Service is automatic for **[OpenAPI 3.x](https://www.openapis.org/)** specs and **[gRPC/Protobuf](https://grpc.io/)** definitions. By default, reShapr will use the identification elements (`name` and `version`) found in the artifact. You can, however, decide to override this information by using the additional `--sn, --serviceName ` and `--sv, --serviceVersion ` options. :::warning The discovery of services from **[GraphQL](https://graphql.org/)** schemas needs some more help. Here, the additional `--sn, --serviceName ` and `--sv, --serviceVersion ` options are mandatory. If not specified, the import will fail. ::: When importing an artifact Service, you may also choose not to consider all the different operations that will be discovered. Perhaps you want to restrict it to read-only access, or maybe your existing API is too coarse-grained, and you want to filter on a single domain. Whatever the reason, you can configure this with the following options: - `--io, --includedOperations [, ]` : Allow specifying a list of operations to consider. Example: `--io '["createLabel", "createIssue"]'` , - `--eo, --excludedOperations [, ]` : Allow specifying a list of operations to ignore. Example: `--eo '["POST /order"]'` . This exclusion list will only be considered if no inclusion list is specified. The import command also allows you to quickly configure and expose the discovered Service using additional flags! If you add the `--be, --backendEndpoint ` flag to your command, this will create a *default* **[Configuration Plan & Exposition](../explanations/configuration-and-exposition.md)** for you, using the *default* gateways. This exposition can be further configured with the most common options: - `--apiKey` : Allow the generation of an API key to secure access to an MCP endpoint exposed by gateways. See the **[`reshapr config create` command details](cli-commands.md)** below - `--internalOAuth2` : Allows secure access to an MCP endpoint using OAuth 2 authorization backed by the reShapr Internal OAuth Identity Provider. See the **[`reshapr config create` command details](cli-commands.md)** below - `--bs, --backendSecret ` : Allow the specification of a Backend Secret to use when exposing an MCP Endpoint on gateways. See **[Backend Secrets](../explanations/security-model.md)**. Below is an example of an all-in-one command that imports a local GraphQL schema, sets its name and version, and exposes it with an API key so that it targets the GitHub GraphQL endpoint: ```bash reshapr import -f ../dev/github-api.graphql --sn 'GitHub GraphQL' --sv '20250917' --be https://api.github.com/graphql --apiKey ``` ```bash ✅ Import successful! ℹ️ Discovered Service GitHub GraphQL with ID: 0N2G4YZFDD3ZF ⚠️ The API Key to access future expositions is: c8d90391-xxxx-xxxx-xxxx-xxxxb004dfdb ⚠️ Make sure to store it securely, as it will not be shown again. ✅ Exposition done! ✅ Exposition is now active! Exposition ID : 0N2G4Z0ASD034 Organization : Created on : 2025-09-26T14:43:37.686+00:00 Service ID : 0N2G4YZFDD3ZF Service Name : GitHub GraphQL Service Version: 20250917 Service Type : GRAPHQL -> https://api.github.com/graphql Endpoints : mcp.beta.reshapr.io/mcp//GitHub+GraphQL/20250917 ``` ### `reshapr attach` command Available since version `0.0.8` of the CLI, the attach command allows you to provide and attach complementary artifacts to an already discovered **[Service](../explanations/services-and-artifacts.md)**. This command will typically be used immediately after the `import` command to provide additional information about **[Prompts](prompts-specification.md)** or **[Custom Tools](custom-tools-specification.md)**. Similar to the `import` command, you need to instruct reShapr on how to retrieve this artifact. You can use: - `-f, --file ` to reference a local file you want to upload, - `-u, --url ` to ask the reShapr control plane to download a remote file. :::info When specifying a remote URL with the `-u` option, it can also be useful to specify a Secret with the `-s, --secret ` to authorize access to the remote endpoint. Check the **[Secret commands](cli-commands.md)** just below to learn how to create them. ::: Here's an example of an artifact attachment: ```bash reshapr attach -f ../dev/github-api-prompts.yaml ``` ```bash ✅ Attachment successful! ℹ️ Discovered Artifact file with ID: 0NKVYHWSR9VPT ``` ### `reshapr artifact list` command Available since version `0.0.11` of the CLI, the artifact list command lets you list all artifacts associated with a given Service. ```bash reshapr artifact list -s ``` Available options: - `-s, --serviceId ` (required) : Filter artifacts by service ID - `-o, --output ` : Output format (`json`, `yaml`) ```bash reshapr artifact list -s 0N2G4YZFDD3ZF ``` ```bash ID NAME TYPE MAIN 0NKVYHWSR9VPT github-api.graphql GRAPHQL_SCHEMA Yes 0NKVZAB12X3YZ github-api-prompts RESHAPR_PROMPTS No ``` ### `reshapr artifact get` command Available since version `0.0.11` of the CLI, this command retrieves details of a specific artifact by its ID. ```bash reshapr artifact get [options] ``` Available options: - `-d, --display` : Display the artifact content (syntax-highlighted) - `-o, --output ` : Output format (`json`, `yaml`) ```bash reshapr artifact get 0NKVYHWSR9VPT ``` ```bash ℹ️ Artifact details ID : 0NKVYHWSR9VPT Name : github-api.graphql Organization : my-org Service ID : 0N2G4YZFDD3ZF Type : GRAPHQL_SCHEMA Main Artifact: Yes Source : github-api.graphql Path : N/A ``` ## Service commands ### `reshapr service list` command Lists all services registered in your organization. ```bash reshapr service list [options] ``` Available options: - `-o, --output ` : Output format (`json`, `yaml`) ```bash reshapr service list ``` ```bash ID NAME VERSION TYPE AGE 0N0802V07SZEH Open-Meteo APIs 1.0 REST 3d 0N2G4YZFDD3ZF GitHub GraphQL 20250917 GRAPHQL 1d ``` ### `reshapr service get` command Retrieves detailed information about a specific service, including all discovered operations. ```bash reshapr service get [options] ``` Available options: - `-o, --output ` : Output format (`json`, `yaml`) ```bash reshapr service get 0N0802V07SZEH ``` ```bash ℹ️ Service details ID : 0N0802V07SZEH Name : Open-Meteo APIs Version : 1.0 Organization: my-org Type : REST Created : 2025-09-19T14:35:58.591+00:00 Operations : - Name: GET /v1/forecast - Name: GET /v1/historical ``` ### `reshapr service delete` command Deletes a service by its ID. This will also remove all associated artifacts, configuration plans, and expositions. ```bash reshapr service delete [options] ``` Available options: - `-f, --force` : Skip confirmation prompt :::warning Deleting a service is a destructive operation. All associated artifacts, configuration plans, and expositions will also be removed. ::: ```bash reshapr service delete 0N0802V07SZEH ``` ```bash ? Deleting this service will also remove associated artifacts, config plans & expositions. Are you sure you want to proceed? Yes ✅ Service 0N0802V07SZEH deleted successfully. ``` ## Secret commands ### `reshapr secret create` command Creating a **[Secret](../explanations/security-model.md)** just requires an argument that will be its ``. You will also be able to provide a description using the `--description ` option. Moreover, the command proposes several options for providing the different elements of your **[Secrets](../explanations/security-model.md)**. First, you can tag your Secret so that you'll later know the target usage: - `-A, --artifact` : Tags the Secret as being used for artifact retrieval on secured remote repositories, - `-B, --backend` : Tags the Secret as being used for accessing a secure Backend Endpoint. Then, depending on your Secret's nature, you will have to use one or more of the following options: - `-u, --username ` : When your remote endpoint is secured using the HTTP Basic mechanism, you have to provide a username, - `-p, --password ` : The password is the companion of the username when using HTTP Basic for authenticating to the resource. - `-t, --token ` : When using token or API key-based authentication, you'd usually provide a token. If no additional `tokenHeader` is provided, it will be used as the value in an `Authorization: Bearer ` HTTP header. - `-h, --tokenHeader ` : When using token or API key-based authentication, the token header will allow you to customize the HTTP header used to send the token value. - `-c, --certificate ` : When accessing a TLS-secured endpoint, you may want to provide your specific X509 certificate using the PEM format. Since reShapr `0.0.14`, sensitive backend Secret values can be literal values or **[secret references](../explanations/security-model.md#secret-references)** such as `${env:GITHUB_TOKEN}`. In that case, the control plane stores the reference, and the Gateway resolves the actual value locally when calling the backend endpoint. Below is an example of a secret creation: ```bash reshapr secret create my-secret --description 'A secret to access a super secured endpoint' -B \ -t acme_wXl53oz5gFeSmBt8awTUJI72yQSrtbMP -h x-acme-api-key --certificate ../certs/my-secret.pem ``` ```bash ✅ Secret my-secret created successfully with ID: 0N084D4H90937 ``` ### `reshapr secret create-elicitation` command This command is actually an alias of the `secret create` command, which allows the creation of an **[Elicitation](https://modelcontextprotocol.io/specification/2025-11-25/client/elicitation)**-based backend secret. Unlike a standard backend Secret, an Elicitation-based one does not require proactive provisioning: when needed, the reShapr MCP Server will return to the user to request backend credentials or initiate an OAuth authorization flow. Like the `secret create` command, you have to assign your secret a `name` and an optional `description`. Two URL Elicitation flows are available: the [**URL Mode Elicitation for Sensitive Data**](https://modelcontextprotocol.io/specification/2025-11-25/client/elicitation#url-mode-elicitation-for-sensitive-data) and the [**URL Mode Elicitation for OAuth Flows**](https://modelcontextprotocol.io/specification/2025-11-25/client/elicitation#url-mode-elicitation-for-oauth-flows). Depending on the one you want to configure, you'll have to use different options flags. - For [**URL Mode Elicitation for Sensitive Data**](https://modelcontextprotocol.io/specification/2025-11-25/client/elicitation#url-mode-elicitation-for-sensitive-data), use the `-t, --token ` option flag to provide the name of the token collected from the user and set as a header to the backend remote endpoint, - For [**URL Mode Elicitation for OAuth Flows**](https://modelcontextprotocol.io/specification/2025-11-25/client/elicitation#url-mode-elicitation-for-oauth-flows), you have to provide **three mandatory options** (plus one optional): - `--oc, --oauth2ClientID ` : Allows configuring the client ID used for the third-party authorization server, - `--ocs, --oauth2ClientSecret ` : Allow to specify the client secret for the backend authorization service (if required by the authorization server), - `--oae, --oauth2AuthorizationEndpoint ` : Allow the specification of the Authorization endpoint for the backend authentication (including query parameters but without `clientID` and `redirect_uri` that will be added dynamically), - `--ote, --oauth2TokenEndpoint ` : Allow the configuration of the token exchange endpoint for the backend authentication. Below is an example of how to create such an Elicitation-based Secret: ```bash reshapr secret create-elicitation 3rd-party-oauth --oc reshapr-saas \ --oae https://idp.example.com/realms/3rdparty/protocol/openid-connect/auth\?scope\=openid\%20profile\&response_type\=code\&prompt\=login \ --ote https://idp.example.com/realms/3rdparty/protocol/openid-connect/token ``` ```bash ✅ Elicitation secret 3rd-party-oauth created successfully with ID: 0NWN2WHGEA2JP ``` You will then be able to use and reference this Secret when creating your Configuration Plan to enable Elicitation-based security. ### `reshapr secret list` command Lists all secrets in your organization. ```bash reshapr secret list [options] ``` Available options: - `-o, --output ` : Output format (`json`, `yaml`) ```bash reshapr secret list ``` ```bash ID NAME TYPE DESCRIPTION 0N084D4H90937 my-secret ENDPOINT A secret to access a super secured endpoint 0NWN2WHGEA2JP 3rd-party-oauth ENDPOINT ``` ### `reshapr secret get` command Retrieves details of a specific secret by its ID. ```bash reshapr secret get [options] ``` Available options: - `-o, --output ` : Output format (`json`, `yaml`) ```bash reshapr secret get 0N084D4H90937 ``` ```bash ℹ️ Secret details ID : 0N084D4H90937 Name : my-secret Organization: my-org Type : ENDPOINT Token : acme_wXl53oz5gFeSmBt8awTUJI72yQSrtbMP Token Header: x-acme-api-key Description : A secret to access a super secured endpoint ``` ### `reshapr secret update` command Opens an interactive editor to update a secret's properties. Immutable fields (ID, organization) are preserved automatically. ```bash reshapr secret update ``` ### `reshapr secret delete` command Deletes a secret by its ID. ```bash reshapr secret delete ``` ```bash ✅ Secret deleted successfully: 0N084D4H90937 ``` ## Configuration Plan commands ### `reshapr config list` command Lists all configuration plans in your organization. ```bash reshapr config list [options] ``` Available options: - `-s, --serviceId ` : Filter by service ID - `-o, --output ` : Output format (`json`, `yaml`) ```bash reshapr config list ``` ```bash ID NAME SERVICE BACKEND API_KEY OAUTH2_CONFIG 0N4B3WS9Z6KBV github-issues-config 0N2G4YZFDD3ZF https://api.github.com/graphql Yes No ``` ### `reshapr config get` command Retrieves detailed information about a specific configuration plan. ```bash reshapr config get [options] ``` Available options: - `-o, --output ` : Output format (`json`, `yaml`) ```bash reshapr config get 0N4B3WS9Z6KBV ``` ```bash ℹ️ Configuration plan details ID : 0N4B3WS9Z6KBV Name : github-issues-config Organization : my-org Description : GH issue-related operations config plan Service ID : 0N2G4YZFDD3ZF Backend Endpoint: https://api.github.com/graphql Backend Timeout : 30000 ms Included Ops. : ["pinIssue","createIssue"] Excluded Ops. : [] Backend Secret : No API Key : Yes OAuth2 : No ``` ### `reshapr config create` command This command proposes advanced options for configuring how your Service is to be consumed and enabling different **[Security options](../explanations/security-model.md)**. A Configuration Plan has a mandatory `name`, so this is the first argument of the command: `reshapr config create `. You can provide a more detailed description of your configuration plan goal using the `-d, --description` option in your command. The primary goal of a Configuration Plan is to integrate a Service with a backend endpoint URL, where this existing Service or API will be utilized. For that, this command has **two mandatory options**: - `-s, --serviceId ` : Allow the specification of the Service using its unique identifier - `--be, --backendEndpoint ` : Allow the specification of this Service implementation endpoint URL You can also configure a timeout for requests to the backend endpoint: - `--bt, --backendTimeout ` : Timeout in milliseconds for requests to the backend endpoint. Must be a positive number. A Configuration plan allows you to restrict the Service operations your consumer will be able to list and use. You can choose the operations you want to include or exclude in the MCP server endpoint by using the `--filter` option. Below is an illustration of the flow: ```bash reshapr config create github-issues-config -d 'GH issue-related operations config plan' -s 0N4B3WS9Z6KBV --be https://api.github.com/graphql --filter ``` The CLI will ask you if you want to proceed by choosing the operations you want to include or the operations you want to exclude: ```bash The service GitHub GraphQL has 283 operation(s) available. You can filter them to include or exclude specific operations. ? Do you want to include or exclude operations? (Use arrow keys) No ❯ Include operations Exclude operations ``` And then let you select the operations in a list: ```bash ? Select operations to include: (Press to select, to toggle all, to invert selection, and to proceed) ◯ updateProjectColumn ◯ createCheckSuite ◯ createDiscussion ❯◉ pinIssue ◯ deleteRef ❯◉ createIssue ◯ createEnvironment ◯ updateEnterpriseMembersCanMakePurchasesSetting ◯ deletePullRequestReviewComment ◯ closePullRequest ``` Instead of doing things in an interactive way using the `--filter` option, you can also use the exclusive `--includedOperations` and `--excludedOperations` as detailed below: - `--io, --includedOperations [, ]` : Allow the configuration of included operations; only the ones listed here will be actually exposed on the MCP Server endpoint. The operations must be specified within an array like this: `--io '["operation1", "operation2"]'` - `--eo, --excludedOperations [, ]` : Allow the specification of excluded operations; none of the ones listed here will be actually exposed on the MCP Server endpoint Finally, you can use the Configuration plan to enable security options. Below are explanations of the options you may find: - `--bs, --backendSecret ` : Allow the specification of a Backend Secret to use when exposing an MCP Endpoint on gateways - `--apiKey` : Allow the generation of an API key to secure access to an MCP endpoint exposed by gateways. The MCP client should then provide this API key to the server using an `x-reshapr-key` HTTP header. The API key will be provided just once during the creation of the Configuration Plan. You must store it in a safe place. You can later use the `renew-api-key` command to revoke the existing API key and generate a new one - `--internalOAuth2` : Allows secure access to an MCP endpoint using OAuth 2 authorization backed by the *reShapr Internal OAuth Identity Provider*. This command registers an OAuth 2 Client ID dedicated to accessing future MCP endpoints for this Service. The Client ID will be provided just once during the creation of the Configuration Plan. You must store it in a safe place. You can later authenticate yourself with social providers using the `oauth2 auth-client ` command ### `reshapr config create-oauth` command This command is actually an alias of the `config create` command, but with options focused on securing access to an MCP endpoint using third-party OAuth 2 authorization servers. As such, `create-oauth` provides the same set of options for referring to a Service, the implementation backend endpoint, as well as the filtering options. It provides additional **mandatory flags** to configure the trust of access: - `--oas, --oauth2AuthorizationServers [, ]` : Allow the specification of one or many authorization server URLs that represent valid issuers for Bearer tokens, - `--oju, --oauth2jwksUri ` : Allow the configuration of the URI used for retrieving JSON Web Key Set for verifying the Bearer token signatures, - `--osc, --oauth2Scopes [, ]` : Allow the configuration of scopes that should be present in the Bearer token to allow access to the MCP endpoint. Like `config create`, it also supports the `--bt, --backendTimeout ` option to configure the backend endpoint timeout in milliseconds. Below is an example of how to create a Configuration Plan with these security options: ```bash reshapr config create-oauth 'oauth2-plan for Open-Meteo APIs' -s 0NTK2N8P7GMQR --be https://api.open-meteo.com \ --oas '["https://idp.example.com/realms/3rdparty"]' --oju https://idp.example.com/realms/3rdparty/protocol/openid-connect/certs \ --osc '["openid", "custom"]' ``` ### `reshapr config update` command Opens an interactive editor to update an existing configuration plan. Immutable fields (ID, organization) are preserved automatically. ```bash reshapr config update ``` ### `reshapr config renew-api-key` command Given a Configuration Plan that was previously created with the `--apiKey` option, this command allows you to revoke the existing API key and have reShapr generate a new one. The new API key is immediately propagated to the gateway, exposing the associated MCP Endpoint configuration. `reshapr config renew-api-key ` will remove the existing API key and output a fresh API key that replaces it. The new API key is provided only once; you must store it in a secure location and share it only with trusted individuals. ### `reshapr config delete` command Deletes a configuration plan by its ID. This may also remove associated expositions. ```bash reshapr config delete [options] ``` Available options: - `-f, --force` : Skip confirmation prompt :::warning Deleting a configuration plan may also remove associated expositions. ::: ```bash reshapr config delete 0N4B3WS9Z6KBV ``` ```bash ? Deleting this config plan may also remove associated expositions. Are you sure you want to proceed? Yes ✅ Configuration plan 0N4B3WS9Z6KBV deleted successfully. ``` ## Exposition commands ### `reshapr expo list` command Lists all expositions in your organization. By default, only active expositions are shown. ```bash reshapr expo list [options] ``` Available options: - `-a, --all` : Display also inactive expositions - `-o, --output ` : Output format (`json`, `yaml`) ```bash reshapr expo list ``` ```bash ID SERVICE BACKEND ENDPOINTS AGE 0N2G4Z0ASD034 GitHub GraphQL:20250917 https://api.github.com/graphql mcp.beta.reshapr.io 1d ``` ### `reshapr expo get` command Retrieves detailed information about a specific exposition, including its active gateway endpoints. ```bash reshapr expo get [options] ``` Available options: - `-o, --output ` : Output format (`json`, `yaml`) ```bash reshapr expo get 0N2G4Z0ASD034 ``` ```bash ℹ️ Exposition details ID : 0N2G4Z0ASD034 Created on : 2025-09-26T14:43:37.686+00:00 Organization: my-org Service: ID : 0N2G4YZFDD3ZF Name : GitHub GraphQL Version: 20250917 Type : GRAPHQL Configuration Plan ID : 0N4B3WS9Z6KBV Name : default-plan for GitHub GraphQL BackendEndpoint: https://api.github.com/graphql Included Ops. : [] Excluded Ops. : [] Gateway Group ID : 1 Name : default Labels: {} Gateway Endpoints - ID : gw-001 Name : mcp-gateway Endpoints: mcp.beta.reshapr.io/mcp/my-org/GitHub+GraphQL/20250917 ``` ### `reshapr expo create` command Creates a new exposition by associating a Configuration Plan with a Gateway Group. ```bash reshapr expo create [options] ``` Available options: - `-c, --configuration ` (required) : Configuration Plan ID to use - `-g, --gateway-group ` (required) : Gateway Group ID to use - `-o, --output ` : Output format (`json`, `yaml`) ```bash reshapr expo create -c 0N4B3WS9Z6KBV -g 1 ``` ```bash ✅ Exposition created successfully with ID: 0N2G4Z0ASD034 ``` ### `reshapr expo delete` command Deletes an exposition by its ID. ```bash reshapr expo delete ``` ```bash ✅ Exposition 0N2G4Z0ASD034 deleted successfully. ``` ## Gateway Group commands ### `reshapr gateway-group list` command Lists all gateway groups in your organization. ```bash reshapr gateway-group list [options] ``` Available options: - `-o, --output ` : Output format (`json`, `yaml`) ```bash reshapr gateway-group list ``` ```bash ID ORG NAME LABELS 1 my-org default {} 0N5X2AB9CD3EF my-org staging {"env":"staging"} ``` ### `reshapr gateway-group create` command Creates a new gateway group with an optional set of labels for gateway matching. ```bash reshapr gateway-group create [options] ``` Available options: - `-l, --labels ` : JSON map of key-value labels for the gateway group - `-o, --output ` : Output format (`json`, `yaml`) ```bash reshapr gateway-group create production -l '{"env":"production","region":"eu-west-1"}' ``` ```bash ✅ Gateway group 'production' created successfully with ID: 0N7Y3CD8EF4GH ``` ### `reshapr gateway-group delete` command Deletes a gateway group by its ID. ```bash reshapr gateway-group delete ``` ```bash ✅ Gateway group with ID '0N7Y3CD8EF4GH' deleted successfully. ``` ## API Token commands ### `reshapr api-token list` command Lists all API tokens in your organization. API tokens are used by gateways to register and authenticate with the control plane. ```bash reshapr api-token list ``` ```bash ID NAME VALID UNTIL 0N9A4EF0GH5IJ gateway-token-1 Mon, 15 Dec 2025 00:00:00 GMT ``` ### `reshapr api-token create` command Creates a new API token for gateway registration. ```bash reshapr api-token create [options] ``` Available options: - `-v, --validity-days ` : Number of days the token is valid for (choices: `1`, `7`, `30`, `90`; defaults to `30`) ```bash reshapr api-token create my-gateway-token -v 90 ``` ```bash ⚠️ The API Token to register Gateway is: my-org-a1b2c3d4-xxxx-xxxx-xxxx-xxxxxxxxxxxx ⚠️ Make sure to store it securely, as it will not be shown again. ``` ### `reshapr api-token delete` command Deletes an API token by its ID. ```bash reshapr api-token delete [options] ``` Available options: - `-f, --force` : Skip confirmation prompt :::warning Deleting an API token will prevent gateways that use it from connecting to reShapr. ::: ```bash reshapr api-token delete 0N9A4EF0GH5IJ ``` ```bash ? Deleting this API token will prevent Gateways that use it to connect to Reshapr. Are you sure you want to proceed? Yes ℹ️ API token with ID 0N9A4EF0GH5IJ deleted successfully. ``` ## Quota commands ### `reshapr quotas` command Lists and checks your reShapr quotas, showing limits and remaining capacity for each metered resource. ```bash reshapr quotas [options] ``` Available options: - `-o, --output ` : Output format (`json`, `yaml`) ```bash reshapr quotas ``` ```bash ORG METRIC ENABLED LIMIT REMAINING my-org services Y 5 3 my-org expositions Y 10 8 my-org gateway-groups Y 3 2 ``` ## Local execution commands ### `reshapr run` command Starts reShapr locally using Docker Compose (or Podman Compose). The CLI downloads the appropriate compose file from the GitHub repository for the specified release, caches it locally, and starts the containers. ```bash reshapr run [options] ``` Available options: - `-r, --release ` : Release of the containers to run (defaults to `latest`; use `nightly` for the latest development build) - `-e, --engine ` : Container engine to use (`docker` or `podman`) ```bash reshapr run ``` ```bash ℹ️ Resolved 'latest' to release '0.0.11'. ℹ️ Downloading compose file from https://raw.githubusercontent.com/reshaprio/reshapr/refs/tags/0.0.11/install/docker-compose-all-in-one.yml... ✅ Compose file saved to ~/.reshapr/docker-compose-0.0.11.yml ℹ️ Starting Reshapr containers (release: 0.0.11, engine: docker)... ✅ Reshapr containers started successfully. ``` To use a specific release with Podman: ```bash reshapr run -r 0.0.10 -e podman ``` ### `reshapr status` command Shows the status of locally running reShapr containers. ```bash reshapr status ``` ```bash ℹ️ Reshapr containers (release: 0.0.11, engine: docker, started at: 2025-05-18T10:30:00.000Z) NAME IMAGE STATUS reshapr-control-plane registry.reshapr.io/reshapr/control-plane:0.0.11 Up 2 hours reshapr-proxy registry.reshapr.io/reshapr/proxy:0.0.11 Up 2 hours ``` ### `reshapr stop` command Stops locally running reShapr containers and removes the run state. ```bash reshapr stop ``` ```bash ℹ️ Stopping Reshapr containers (release: 0.0.11, engine: docker)... ✅ Reshapr containers stopped successfully. ``` ## Structured output Most of the CLI commands allow a `--output ` option (or just `-o` for the short alternative) that allows you to format the output in either `json` or `yaml`. Using this flag option is extremely convenient, combined with utilities such as `jq` or `yq`, for automating publication or configuration changes on reShapr. Below is an example: ```bash reshapr service list -o json ``` ```bash [ { "id": "0N0802V07SZEH", "organizationId": "reshapr", "name": "Open-Meteo APIs", "version": "1.0", "createdOn": "2025-09-19T14:35:58.591+00:00", "type": "REST" } ] ``` ```bash reshapr service get 0N0802V07SZEH -o json | jq .name ``` ```bash "Open-Meteo APIs" ``` --- ## Custom Tools The use of MCP Server raises important concerns regarding the control of the context - see our dedicated blog post **[From Context Overload to Context Control!](/blog/from-context-overload-to-context-control)** on this topic. There are different facets of this need of control: the search for efficiency (economical & technical performance), the reduction of security threats, and the adaptation to a business context or process. Even official MCP Servers can be questioned regarding these concerns: - The official GitHub MCP server exposes over 90 tools consuming 46k+ tokens, including high-risk operations like `delete_file` and `delete_workflow_run_logs` alongside benign tools like `get_pull_requests`. - The Snowflake official MCP server, for example, exposes an `execute_sql` tool accepting arbitrary SQL queries. Agents have to generate different SQL queries each time for the same request, making results non-deterministic and potentially wrong. Instead, organizations need tools that map to specific use cases. For example, `get_revenue_for_month(month, year)` that maps to approved, parameterized queries reviewed by data teams. As a consequence, MCP Servers - whether provided by an official third-party or built on your own existing API - **should be used very rarely as is without polishing the context usage.** They should be designed to provide LLMs and Agents with clearly designed and parameterized actions that fit a specific use case. reShapr provides **an easy way to design and specify your Custom Tools using a simple YAML description,** called the `CustomTools` specification. If you want to provide such custom tools to your reShapr-powered MCP endpoint, you’ll need to write this simple file and `attach` it to your existing Service. Let’s explain this concept via a simple example: we want to provide an MCP Tool that fetches details on a GitHub user. The official MCP Server is a no-brainer as it provides too many high-risk operations, so we decided to produce our own reShapr-powered one, reusing the GitHub GraphQL API and reducing the surface to only the existing `user` operation. You can do this in reshapr using this command: ```bash reshapr import -f ../dev/github-api.graphql --sn 'GitHub GraphQL' --sv '20250917' --be https://api.github.com/graphql --io '["user"]' ``` That allows us to have an MCP endpoint with just the `user` operation, but here we’re facing the complexity of the GraphQL API with too many parameters and relation navigation options! This tool will consume 2.5k tokens, and we’re not certain it will fetch all the required user information. Let’s say we want default information on the user, but also its avatar and details on its latest followers… We can define a new `get_user_with_latest_followers(login)` tool for a specific use case, and we just have to create and attach this simple YAML file: ```yaml apiVersion: reshapr.io/v1alpha1 kind: CustomTools service: name: GitHub GraphQL version: '20250917' customTools: get_user_with_latest_followers: tool: user description: Get a user details with the latest followers details input: type: object properties: user: type: string description: The GitHub login of the user to fetch required: - user arguments: login: ${user} __relation_avatarUrl: size: 32 __relation_followers: last: 10 ``` A `CustomTools` artifact follows some simple rules: - It always contains an identification section made of `apiVersion` and `kind` properties that **must** have the **`reshapr.io/v1alpha1`** and `CustomTools` values respectively, - It **must** be bound to a specific reShapr **[Service](../explanations/services-and-artifacts.md)** using the **`service.name`** and `service.version` properties whose values **must** match an already discovered Service, - The `customTools` section then defines the tools: - We have a single tool here: `get_user_with_latest_followers` - A declarative custom tool **must** have a `tool` that defines the original tool it overrides and replaces: here we’re using the GitHub `user` tool, - A custom tool **may** provide optional `title` and `description` to provide more context to the LLM or Agent when choosing an appropriate tool, - A custom tool **must** also provide an `input` schema description that describes its parameters. Input schema reuses the same structure as the regular MCP Tools Input Schema. - A declarative custom tool **may** also specify `arguments` that represent the arguments that will be used with the original tool that is overridden. Here we’re fixing the arguments as well as the relation navigation options for fetching exactly what we need. In the case of custom tools using `arguments`, the value **can** be expressed using `${}` expressions that will be replaced by input values. Typically in our example, the MCP client will send a `user` value as input, and this value will be used in the place of the `${user}` placeholder when invoking the original tool. ## Scripted Custom Tools Available since reShapr `0.0.14`, a Custom Tool can also define its behavior with a JavaScript `script`. This is useful when a single business action needs to orchestrate several existing tools, possibly from different Services of the same organization, and return a compact result that is easier for an Agent to use. A custom tool item is now **either** declarative **or** scripted: | Form | Main fields | Purpose | | --- | --- | --- | | Declarative | `tool`, `arguments` | Map the custom tool to one backend tool, with templated arguments. | | Scripted | `script`, `tools` | Run JavaScript logic that may call several tools and reshape their results. | Both forms still require `description` and `input`. The `input` JSON Schema defines the parameters exposed to the MCP client and becomes available inside the script as the `input` constant. A scripted custom tool never talks directly to backend endpoints. It calls other reShapr tools through the `rs` host API. This means the usual reShapr behavior still applies to every underlying call: security, backend secrets, elicitation handling, output filtering, audit, and distributed tracing. ### Scripted tool fields | Field | Type | Required | Description | | --- | --- | --- | --- | | `description` | string | yes | Human-readable description of the custom tool. | | `input` | object | yes | JSON Schema object describing the tool parameters. | | `script` | string | yes | JavaScript body to execute. It must `return` a JSON-serializable value. | | `tools` | array | yes | Allow-list of tools the script may call. | The `tools` array is both a security allow-list and the input used by reShapr to prepare elicitation flows before the script runs. Each item contains a `tool` name and, when calling another Service, an optional `service` value using the readable `` form. ```yaml tools: - tool: user - service: "Issues API:1.0.0" tool: listIssues ``` When `service` is omitted, the script calls a tool from the same Service as the Custom Tool. Cross-Service calls are restricted to Services belonging to the same organization. ### The `rs` host API Inside the script, reShapr exposes a global `rs` object: | Function | Description | | --- | --- | | `rs.callTool(tool, params)` | Synchronously call a tool on the same Service. | | `rs.callTool(service, tool, params)` | Synchronously call a tool on another Service. | | `rs.callToolAsync(tool, params)` | Start a same-Service call without blocking. | | `rs.callToolAsync(service, tool, params)` | Start a cross-Service call without blocking. | | `rs.awaitPromises([p1, p2])` | Wait for async calls and return the results in the same order. | | `rs.fail(message, data)` | Fail the whole Custom Tool with a structured MCP error. | Every call returns a result object: ```js { ok: true, content: {}, error: null } ``` If a call fails, `ok` is `false`, `content` is `null`, and `error` contains the failure details. A script should check `result.ok` before reading `result.content`. ### Returning results and failures A script can return any JSON-serializable value: ```js const result = rs.callTool('user', { login: input.user }); if (!result.ok) { throw new Error('Could not fetch user ' + input.user); } return { login: result.content.login }; ``` Returning a value makes the Custom Tool call succeed. Throwing an error makes the Custom Tool call fail with an MCP tool error. For machine-readable failures, use `rs.fail(message, data)`: ```js rs.fail('GitHub rate limit exceeded', { retryAfter: 60, scope: 'graphql' }); ``` This returns an MCP error whose content is a structured JSON object containing the `message` and `data` fields. ### Asynchronous orchestration Use `rs.callToolAsync(...)` when several tool calls can run in parallel. The calls start immediately, and `rs.awaitPromises(...)` waits for them: ```js const first = rs.callToolAsync('user', { login: input.firstUser }); const second = rs.callToolAsync('user', { login: input.secondUser }); const results = rs.awaitPromises([first, second]); return { users: results.map(function (result) { return result.ok ? result.content : { error: result.error }; }) }; ``` Partial failures of asynchronous calls are not thrown automatically. They are returned as `ok: false` result objects, so the script can decide whether to ignore, recover, or fail the whole Custom Tool. ### Backend secrets and elicitation Before a scripted Custom Tool runs, reShapr checks every tool declared in `tools`. If one of these target tools requires an elicitation-based backend secret that is not yet available for the current MCP session, the MCP Server returns the elicitation request instead of starting the script. Once all required secrets are resolved, the script runs normally. This is why the `tools` list must be exhaustive: it lets reShapr know which backend credentials may be required before any JavaScript code is executed. ### Guardrails Script execution is bounded by gateway settings: | Setting | Default | Description | | --- | --- | --- | | `reshapr.gateway.scripting.timeout` | `10000` ms | Maximum script execution time. `0` disables the timeout. | | `reshapr.gateway.scripting.max-tool-calls` | `50` | Maximum number of tool calls per script execution. | | `reshapr.gateway.scripting.max-depth` | `5` | Maximum nesting depth when a scripted tool calls another scripted tool. | The timeout cancels interruptible work such as backend calls and waits. Keep scripts simple and avoid unbounded CPU loops. ### Example Here is a scripted Custom Tool that fetches two GitHub users in parallel and returns a small side-by-side comparison: ```yaml apiVersion: reshapr.io/v1alpha1 kind: CustomTools service: name: GitHub GraphQL version: '20250917' customTools: compare_two_users: description: Fetch two GitHub users in parallel and compare their profiles. input: type: object properties: firstUser: type: string secondUser: type: string required: - firstUser - secondUser tools: - tool: user script: | function summarize(result, login) { if (!result.ok) { return { login: login, error: result.error }; } const user = result.content.data && result.content.data.user ? result.content.data.user : result.content.user || result.content; return { login: user.login || login, name: user.name, company: user.company }; } const first = rs.callToolAsync('user', { login: input.firstUser }); const second = rs.callToolAsync('user', { login: input.secondUser }); const results = rs.awaitPromises([first, second]); return { users: [ summarize(results[0], input.firstUser), summarize(results[1], input.secondUser) ] }; ``` --- ## reShapr Features Want to get all the features in a nutshell? This is where you can find all of them with pointers to the documentation and demos! ## API Translation - OpenAPI 2.x & 3.x (**[🎬](https://www.youtube.com/watch?v=W1xfiBpGzI0)**), GraphQL Schema (**[🎬](https://www.youtube.com/watch?v=5dLpRzFJkqU)**), gRPC Protobuffer 3 to MCP Server no-code translation - Full API re-shaping capabilities: - Rename existing API (**[🎬](https://www.youtube.com/watch?v=5dLpRzFJkqU)**) - Split an existing API by including or excluding chosen API operations - Adapt to your Agentic context, defining `CustomTools` by renaming, condensing, and translating default operations (**[🎬](https://www.youtube.com/watch?v=OjsSAt0JdOY)**) - Script `CustomTools` to orchestrate several tools and return a slim result, available since reShapr `0.0.14` (**[📄](custom-tools-specification.md#scripted-custom-tools)**) ## MCP support - Support of **[2025-11-25](https://modelcontextprotocol.io/specification/2025-11-25)** and **[2025-06-18](https://modelcontextprotocol.io/specification/2025-06-18)** versions - MCP **[Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#streamable-http)** - `Tools`, `Prompts` and `Resources` (**[📄](prompts-specification.md)**) - **[URL Mode with Elicitation Required Error](https://modelcontextprotocol.io/specification/2025-11-25/client/elicitation#url-mode-with-elicitation-required-error-flow)** (**[📄](../explanations/security-model.md)**) - **[OAuth Authorization](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization)** for endpoint security (**[📄](../explanations/security-model.md)**) ## Security - **MCP Endpoint security:** - HTTP with TLS Transport - API key management (**[📄](cli-commands.md)**) - OAuth Authorization with support of OAuth 2.0 Dynamic Client Registration Protocol (**[RFC7591](https://datatracker.ietf.org/doc/html/rfc7591)**), OAuth 2.0 Protected Resource Metadata (**[RFC9728](https://datatracker.ietf.org/doc/html/rfc9728)**), OAuth 2.0 Authorization Server Metadata (**[RFC8414](https://datatracker.ietf.org/doc/html/rfc8414)**), OAuth 2.0 Resource Indicators (**[RFC 8707](https://www.rfc-editor.org/rfc/rfc8707.html)**) (**[📄](../explanations/security-model.md)**) - Secure Production Identity Framework for Everyone (**[SPIFFE](https://spiffe.io/)**) support - Custom Authorization Server integration - Configurable scopes or claims per tool - **End-user / backend endpoint security:** - Header transmission and header translation - **[URL Mode Elicitation for Sensitive Data](https://modelcontextprotocol.io/specification/2025-11-25/client/elicitation#url-mode-elicitation-for-sensitive-data)** retrieval (**[🎬](https://www.youtube.com/watch?v=0f2cdKAV730)**) - **[URL Mode Elicitation for OAuth flows](https://modelcontextprotocol.io/specification/2025-11-25/client/elicitation#url-mode-elicitation-for-oauth-flows)** authorization - Static backend secrets for basic, token-based or certificate-based authentication - Local backend secret references resolved by hybrid Gateways, available since reShapr `0.0.14` (**[📄](../explanations/security-model.md#secret-references)**) ## Operations - MCP Server endpoints rate limiting - **[User-friendly CLI](https://www.npmjs.com/package/@reshapr/reshapr-cli)** for importing API definitions, declaring secrets, and configuring deployment (**[📄](cli-commands.md)**) - Full-stack observability with **[Open Telemetry](https://opentelemetry.io/)** support - Flexible deployment: SaaS, hybrid, or on-premises - Scalable model with auto-discovery of new Gateways - Fully multi-tenant, with strict segregation between domains and customers. - Zero downtime deployments with auto-propagation on configuration changes - GitOps-friendly with YAML-based configuration :::info For more details, check out the reShapr **[blog](/blog)** posts and **[demos](https://www.youtube.com/@reshaprio)**. ::: --- ## Prompts As explained in **[Why reShapr?](../overview/why-reshapr.md)**, reShapr can create secure MCP servers in seconds without coding, just by importing your API’s existing artifacts - like **[OpenAPI 3.x](https://www.openapis.org/)** specs, **[GraphQL](https://graphql.org/)** schemas and **[gRPC/Protobuf](https://grpc.io/)** definitions. These artifacts are directly used to produce **[MCP Tools](https://modelcontextprotocol.io/specification/2025-06-18/server/tools)** that are at the core of the Model Context Protocol. Another interesting aspect of MCP is that it may be composed of **[MCP Resources](https://modelcontextprotocol.io/specification/2025-06-18/server/resources)** and **[MCP Prompts](https://modelcontextprotocol.io/specification/2025-06-18/server/prompts)**. While MCP Tools are often enough for practical use of MCP, all these capabilities are likely to be part of a complete and production-ready MCP Server. Contrary to tools, **prompts can’t - and shouldn’t - be directly inferred from an API contract**. They should be designed to provide users with accelerators on how to interact with the model, offer additional instructions and guardrails on how to use tools for a specific use case, or provide additional details on how to orchestrate tool calls. reShapr provides **an easy way to design and specify your Prompts using a simple YAML description,** called the `Prompts` specification. If you want to provide such prompts to your reShapr-powered MCP endpoint, you’ll need to write this simple file and `attach` it to your existing Service. Let’s see a simple example of such a file: ```yaml apiVersion: reshapr.io/v1alpha1 kind: Prompts service: name: Petstore version: 1.0.0 prompts: list_pets: title: List the pets description: Browse the catalog to get all the pets result: Get all the pets from the catalog get_pet: title: Get details of a pet with its name description: Get details for a specific pet from the catalog arguments: - name: name description: The name of the pet to retrieve required: true result: |- Get the detailed information on the pet named '${name}'. The MCP tool to call is 'get_pet_by_name', using '${name}' as the tool argument called 'name'. ``` A `Prompts` artifact follows some simple rules: - It always contains an identification section made of `apiVersion` and `kind` properties that **must** have the **`reshapr.io/v1alpha1`** and `Prompts` values respectively, - It **must** be bound to a specific reShapr **[Service](../explanations/services-and-artifacts.md)** using the **`service.name`)** and `service.version` properties which values **must** match an already discovered Service, - The `prompts` section then defines the prompts: - We have 2 prompts here: `list_pets` and `get_pet` - A prompt **must** always have a `result` which will be returned to the model when called, - A prompt **may** provide optional `title` and `description` to provide more context to the user when choosing an appropriate prompt, - A prompt **may** also provide `arguments` that allow the production of a customized result prompt message, where the user provides their contextual values for each argument. In the case of a prompt using `arguments`, the `result` value **can** be expressed using `${}` expressions that will be replaced by user-provided values. Typically in our example, if the user is looking for a pet named **Rusty**, the prompt will be generated with `Rusty` in the place of the `${name}` placeholder. --- ## Resources As explained in **[Why reShapr?](../overview/why-reshapr.md)**, reShapr can create secure MCP servers in seconds without coding, just by importing your API’s existing artifacts - like **[OpenAPI 3.x](https://www.openapis.org/)** specs, **[GraphQL](https://graphql.org/)** schemas, and **[gRPC/Protobuf](https://grpc.io/)** definitions. These artifacts are directly used to produce **[MCP Tools](https://modelcontextprotocol.io/specification/2025-06-18/server/tools)** that are at the core of the Model Context Protocol. Another interesting aspect of MCP is that it may be composed of **[Resources](https://modelcontextprotocol.io/specification/2025-06-18/server/resources)**. Resources allow servers to share data that provides context to LLM, such as files, database schemas, or application-specific information. The key difference with tools is intent and usage pattern: - **Resources** are for when **you want to give the model access to existing data to read and reference**. Resources are designed to be **application-driven**, with host applications determining how to incorporate context based on their needs. - **Tools** are for when **you want the model to perform actions** or computations. Tools are designed to be **model-controlled**, meaning that the LLM can discover and invoke tools automatically based on its understanding and the user’s prompts. reShapr provides **an easy way to design and specify your Resources using a simple YAML description,** called the `Resources` specification. If you want to provide such resources to your reShapr-powered MCP endpoint, you’ll need to write this simple file and `attach` it to your existing Service. Let’s see a simple example of such a file: ```yaml apiVersion: reshapr.io/v1alpha1 kind: Resources service: name: Open-Meteo APIs version: '1.0' resources: 'file:///project/readme.md': name: README.MD title: Open-Meteo APIs readme description: Documentation on how to use the Open-Meteo APIs mimeType: text/plain icons: - src: file:///assets/icons/md-file-icon.png mimeType: image/png sizes: - "48x48" text: | ## Hello World Welcome to Open-Meteo API! Bla, bla, bla annotations: audience: - user priority: 0.8 ``` A `Resources` artifact follows some simple rules: - It always contains an identification section made of `apiVersion` and `kind` properties that **must** have the **`reshapr.io/v1alpha1`** and `Resources` values respectively, - It **must** be bound to a specific reShapr **[Service](../explanations/services-and-artifacts.md)** using the **`service.name`** and `service.version` properties whose values **must** match an already discovered Service, - The `resources` section then defines the resources: - We have a single resource here: **`file:///project/readme.md`**. Resource identifiers **must** always start with some protocol-specific notation like `file://.` - A resource **must** always have a `name` that defines its short name, - A resource **may** provide optional `title`, `description`, `mimeType` and `icons` to provide more context to the Agent when choosing an appropriate resource, - A resource **may** also specify its content by using either a `text` or a `blob` property. `text` specifies its content as plain text, `blob` value must be encoded using Base64 - A resource **may** also specify `annotations` that provide hints to clients about how to use or display the resource. More on this in the **[official MCP documentation](https://modelcontextprotocol.io/specification/2025-11-25/server/resources#annotations)**. You can specify as many resources as you want in the same `Resources` artifact file. ## Resource templates As the above form represents the simplest way of doing things, reShapr also supports a more elaborate way of doing things via the concept of `resourceTemplates`. Resource templates represent parametrized resources using URI templates. Imagine you have a list of resources at a specific location (a URL), instead of describing each of them, you can use a template to parameterize the access. Resource Templates can be added to your `Resources` artifact using a `resourceTemplates` element like illustrated below: ```yaml resourceTemplates: 'file:///project/src/{path}?mode=raw': name: Project Source File title: 📁 Project Files description: Access files in the project directory mimeType: application/octet-stream icons: - src: file:///assets/icons/folder-icon.png mimeType: image/png sizes: - "48x48" ``` A `resourceTemplate` follows these rules: - The template identifier **must** contain a parameter delimited with curly braces, here `{path}` - It has the same basic properties as a `resource` except for the `mimeType` property that doesn’t make sense here, as we represent many resources - A template **must not** have `text` or `blob` to define its content. Because it represents a collection of resources, the discovery and fetching of content will be dynamic! To fetch its resource content, a `resourceTemplate` **will reuse [the backend endpoint URL](../explanations/configuration-and-exposition.md) coming from the MCP Server Configuration Plan!** As an example, imagine that you have configured your backend endpoint URL to be **`https://api.acme.com`**. When asking for a resource with `path=resources/doc.md` , then your reShapr MCP Server will actually try to fetch the **`https://api.acme.com/project/src/resources/doc.md?mode=raw`)** URL to get its content. Depending on the received content (text or binary), the reShapr endpoint will use the correct encoding to allow your agent or host application to correctly interpret this content. --- ## Tools Output Filtering As explained in **[Why reShapr?](../overview/why-reshapr.md)**, reShapr can create secure MCP servers in seconds without coding, just by importing your API's existing artifacts such as **[OpenAPI 3.x](https://www.openapis.org/)** specs, **[GraphQL](https://graphql.org/)** schemas, and **[gRPC/Protobuf](https://grpc.io/)** definitions. Once these artifacts are imported, the **[Custom Tools](./custom-tools-specification.md)** specification lets you redefine the *input* of a tool to fit a specific use case. `ToolsOutputFilters` is the symmetrical capability on the *output* side: it lets you declaratively control what a tool returns to the model, before the response is wrapped into the JSON-RPC MCP envelope and sent back to the client. This matters for two reasons: - **Context economics.** A GraphQL node with many scalar properties, or a REST endpoint returning a deeply nested JSON tree, can easily consume thousands of tokens, most of which are irrelevant to the task at hand. Filtering at the gateway keeps the context window focused on what the model actually needs. - **Security and determinism.** Reusing a broad existing API often surfaces fields you'd rather not expose to an agent (PII, internal identifiers, expensive sub-trees). Filtering at the gateway gives you a single, declarative point of control, independent of the underlying API. reShapr applies filtering universally, regardless of the source protocol (REST, GraphQL, gRPC), because filters operate on the canonical JSON response produced by reShapr's protocol converters. ## A first example Here is a simple `ToolsOutputFilters` artifact that trims the response of a custom GitHub tool down to a few key fields, removes a sensitive field, and adds a value: ```yaml apiVersion: reshapr.io/v1alpha1 kind: ToolsOutputFilters service: name: GitHub GraphQL version: '20250917' filters: get_user_with_latest_followers: jsonRetain: - /data/user/name - /data/user/login - /data/user/bio - /data/user/avatarUrl - /data/user/followers jsonPatches: - op: add path: /data/user/location value: "Worldwide" - op: remove path: /data/user/followers/nodes ``` A `ToolsOutputFilters` artifact follows some simple rules: - It always contains an identification section made of `apiVersion` and `kind` properties that **must** have the **`reshapr.io/v1alpha1`** and `ToolsOutputFilters` values respectively, - It **must** be bound to a specific reShapr **[Service](../explanations/services-and-artifacts.md)** using the **`service.name`** and `service.version` properties whose values **must** match an already discovered Service, - The `filters` section then defines the filters, keyed by tool name: - The key (here `get_user_with_latest_followers`) **must** match an existing tool on the Service, either an imported tool or a **[Custom Tool](./custom-tools-specification.md)** previously attached to that Service, - A filter entry **must** specify at least one of `jsonRetain`, `jsonPatches`, or `convertToToon`, - When both `jsonRetain` and `jsonPatches` are present, `jsonRetain` **is always applied first**, as a pre-processing step that narrows the response, before `jsonPatches` are applied in order, - `convertToToon` is applied last, after `jsonRetain` and `jsonPatches`. You can specify as many tool filters as you want in the same `ToolsOutputFilters` artifact, as long as each key targets a distinct tool of the bound Service. ## The `jsonRetain` operation `jsonRetain` is reShapr's addition to the JSON Patch vocabulary. Standard JSON Patch (see below) only lets you describe what to *remove*, which is impractical when the response is a large object and you only care about a small subset of it. With `jsonRetain`, you declare the branches you want to *keep*, and everything else is dropped before patches run. - The value of `jsonRetain` **must** be a non-empty list of **[JSON Pointer](https://datatracker.ietf.org/doc/html/rfc6901)** paths, - Each listed path **must** resolve against the original tool response. Paths that don't resolve are silently ignored (a missing branch isn't an error, it's simply nothing to keep), - The order of paths in `jsonRetain` is not significant: `jsonRetain` describes a *set* of branches to keep, - If `jsonRetain` is omitted, the whole response is passed through to the `jsonPatches` step unchanged. ## The `jsonPatches` operation `jsonPatches` is an ordered sequence of **[JSON Patch](https://jsonpatch.com/)** operations, applied in the listed order to whatever the `jsonRetain` step produced (or to the full response, when `jsonRetain` is omitted). reShapr supports the six standard JSON Patch operations: | Operation | Effect | | ---------- | ----------------------------------------------------------------------------------------------- | | `add` | Adds a value at the given path. Creates the field if it doesn't exist; inserts into arrays. | | `replace` | Replaces the value at the given path. The path **must** already exist. | | `remove` | Removes the value at the given path. | | `copy` | Copies the value from `from` to `path`. | | `move` | Moves the value from `from` to `path` (equivalent to `copy` + `remove` on the source). | | `test` | Asserts that the value at `path` equals `value`. If the test fails, the patch sequence stops. | - The value of `jsonPatches` **must** be a non-empty list of objects, each carrying an `op` property whose value **must** be one of the six operations above, - `path` **must** be a JSON Pointer that resolves against the working document (the response after `jsonRetain` has been applied), - `op: copy` and `op: move` **must** additionally specify a `from` JSON Pointer, - `op: add`, `replace`, and `test` **must** specify a `value`, - The order of the list is significant: each operation sees the document as modified by the operations that came before it. For the precise semantics of each operation, refer to **[RFC 6902: JavaScript Object Notation (JSON) Patch](https://datatracker.ietf.org/doc/html/rfc6902)**. ## The `convertToToon` operation `convertToToon` converts the final filtered JSON output into **[Toon format](https://toonformat.dev/)**, a compact LLM-friendly representation that significantly reduces token usage. - The value of `convertToToon` **must** be `true`, - It is applied **last**, after `jsonRetain` and `jsonPatches` have run, - It can be used **alone** — without any `jsonRetain` or `jsonPatches` — and it will compact the full raw tool response as-is, - It works **regardless of the backend protocol**: REST, GraphQL, and gRPC tool responses are all converted to canonical JSON before filters run, so `convertToToon` applies uniformly across all three. This makes `convertToToon: true` the simplest possible `ToolsOutputFilters` entry — a single key that immediately cuts token usage on any tool, without requiring you to know the response shape upfront: ```yaml apiVersion: reshapr.io/v1alpha1 kind: ToolsOutputFilters service: name: GitHub GraphQL version: '20250917' filters: get_user_with_latest_followers: convertToToon: true ``` You can also combine it with `jsonRetain` and `jsonPatches` to both shape and compact the response: ```yaml apiVersion: reshapr.io/v1alpha1 kind: ToolsOutputFilters service: name: GitHub GraphQL version: '20250917' filters: get_user_with_latest_followers: jsonRetain: - /data/user/name - /data/user/login - /data/user/bio - /data/user/avatarUrl - /data/user/followers jsonPatches: - op: add path: /data/user/location value: "Worldwide" - op: remove path: /data/user/followers/nodes convertToToon: true ``` ## Naming and configuration scope Unlike `Prompts`, `Resources`, and `CustomTools`, which directly transform a Service, `ToolsOutputFilters` is often driven by *deployment-time* concerns (security posture, audience, token budget) rather than by the Service itself. The same Service and the same Custom Tools can legitimately be exposed multiple times on different gateways, each with its own filter set: a public partner-facing Exposition might strip more fields than an internal one. For this reason, a future revision of the spec is expected to introduce a top-level `name` attribute on a `ToolsOutputFilters` artifact, so that a **[Configuration Plan](../explanations/configuration-and-exposition.md)** can explicitly reference which filter set to apply at exposition time. Until that lands, a `ToolsOutputFilters` artifact is bound to a Service and applies whenever that Service is exposed. ## Where filters fit in the request lifecycle For a given MCP tool call, reShapr applies transformations in this order: 1. The incoming MCP tool call is validated against the tool's input schema (the imported one, or the one defined by a **[Custom Tool](./custom-tools-specification.md)**). 2. The call is converted to a protocol-specific request (REST, GraphQL, gRPC) and dispatched to the backend. 3. The backend response is converted back into a canonical JSON response by reShapr's converters. 4. **If a `ToolsOutputFilters` artifact is attached to the Service and declares a filter for this tool, the filter is applied here: `jsonRetain` first, then `jsonPatches`, then `convertToToon` if set.** 5. The filtered response is wrapped into the JSON-RPC MCP envelope and returned to the client. Because filtering happens after the converter step and before the MCP envelope, the same `ToolsOutputFilters` artifact applies uniformly whether the underlying tool is backed by REST, GraphQL, or gRPC. --- ## Demos # Demos Watch on YouTube ## Demo Videos Demo #0: Installing the reShapr CLI Demo #1: Running reShapr with Docker Demo #2: Import Open-Meteo & Expose as MCP :::note Open the full channel via the **button above** to see all our demos. ::: --- ## Docs Home # Welcome to reShapr docs reShapr turns your existing APIs into **secure MCP endpoints** without rebuilding backends. Use these pages to install the CLI, learn the model, and ship faster. ## Start here ## Explore --- ## From API Sprawl to Agent Actions
### How reShapr Turns Existing APIs Into Agent-Ready Actions {/* truncate */} Most organizations already have the APIs they need. They have **REST endpoints**, **GraphQL schemas**, **gRPC services**, OpenAPI definitions, internal authentication flows, audit trails, rate limits, and operational habits that took years to mature. The problem is not that these APIs are missing. The problem is that **most APIs were not shaped for agents**. They were designed for developers who understand product boundaries, endpoint naming, error semantics, authentication details, pagination, identifiers, and the right order of calls. An AI agent does not enter the system with that same background. It receives a list of tools, reads their descriptions, chooses one, sends arguments, observes a result, and tries to continue. If we expose every operation from a large API directly as MCP tools, we push **too much responsibility into the model**: - **Too many tools** to choose from. - **Too many parameters** to interpret. - **Too many raw fields** returned to the context window. - **Too many multi-step workflows** left to probabilistic planning. - **Too much sensitive or irrelevant data** crossing the model boundary. At **reShapr**, our position is simple: > The future of API-to-MCP is not bigger tool catalogs. It is **smaller, clearer, governed agent actions**. ### Custom exposure beats raw exposure MCP gives AI clients a common way to call tools, but it does not decide **which tools should exist**. That design decision matters. A backend API operation is often too low-level for an agent. It may expose transport-oriented names, nested request structures, broad schemas, optional relation navigation, or fields that are useful to developers but distracting to a model. reShapr lets you start from existing API artifacts, including **OpenAPI**, **GraphQL**, and **gRPC/Protobuf**, then **reshape the exposed MCP surface** without rewriting the backend service. That is the role of [**Custom Tools**](/docs/references/custom-tools-specification). With a `CustomTools` artifact, you can define a tool that is **smaller, more intentional, and closer to the task** the agent must perform: - Rename a backend operation into a business-friendly tool. - Replace a complex input schema with a focused one. - Fix arguments that should not be chosen by the model. - Bind agent input values into backend arguments. - Expose only the actions that make sense for a given audience or workflow. Instead of asking the agent to understand an entire service, reShapr lets you publish **a curated interface**. > The model should **not need to reverse-engineer your API architecture** to complete a business task. ### From endpoints to business verbs Consider a commerce platform with separate APIs for orders, customers, inventory, shipping, and refunds. A raw exposure might give the agent dozens or hundreds of operations: - `GET /orders/{id}` - `GET /customers/{id}` - `GET /inventory/{sku}` - `POST /refunds` - `GET /shipments/{id}` - `PATCH /orders/{id}/status` Each endpoint may be valid. Each may be well documented. Each may be useful to an application developer. But an agent trying to answer "Can we safely refund this delayed order?" should not have to assemble that workflow from scratch every time. With reShapr, the MCP surface can become: - `get_order_summary(orderId)` - `check_refund_eligibility(orderId)` - `prepare_customer_response(orderId)` - `create_approved_refund(orderId, reason)` Those tools **express intent**. They **narrow the parameter space**. They **reduce ambiguity**. They also give platform teams a stable place to enforce policy. A declarative Custom Tool can map a simple input to a more complex backend request: ```yaml apiVersion: reshapr.io/v1alpha1 kind: CustomTools service: name: Orders API version: '20260707' customTools: get_order_summary: tool: getOrder description: Fetch the fields needed to summarize an order for a support agent. input: type: object properties: orderId: type: string description: The public order identifier. required: - orderId arguments: id: ${orderId} includeCustomer: true includeShipment: true includeLineItems: true ``` The MCP client sees **one focused tool**. The backend still receives the request shape it expects. That is the important distinction: **reShapr adapts the exposure, not the system of record**. ### When one action needs several API calls Some agent tasks are **not a single backend operation**. They require a sequence: 1. Fetch the order. 2. Check shipment status. 3. Verify refund policy. 4. Inspect item inventory or replacement availability. 5. Return a compact decision. Leaving that chain entirely to the model has practical costs. **Intermediate payloads enter the context window**. The model must decide call order. It may retry inconsistently. It may miss a required policy check. It may pass the wrong identifier from one system into another. This is where [**Scripted Custom Tools**](/docs/references/custom-tools-specification#scripted-custom-tools) become especially useful. A scripted Custom Tool lets reShapr expose **one MCP tool** while running a small JavaScript orchestration behind it. The script does not call arbitrary network endpoints. It calls other reShapr tools through the `rs` host API, using **an explicit allow-list**. That matters because the usual reShapr controls still apply to **every underlying call**: - **Tool authorization.** - **Backend secrets and elicitation.** - **Output filtering.** - **Audit and tracing.** - **Gateway execution limits.** - **Cross-service boundaries** inside the same organization. The agent gets **one task-specific tool**. reShapr handles the **controlled API chaining**. ```yaml apiVersion: reshapr.io/v1alpha1 kind: CustomTools service: name: Orders API version: '20260707' customTools: check_refund_eligibility: description: Check whether an order can be refunded and return the reason. input: type: object properties: orderId: type: string required: - orderId tools: - tool: getOrder - service: "Shipping API:20260707" tool: getShipment - service: "Policy API:20260707" tool: evaluateRefundPolicy script: | const order = rs.callTool('getOrder', { id: input.orderId }); if (!order.ok) { rs.fail('Unable to fetch order', { orderId: input.orderId, cause: order.error }); } const shipmentId = order.content.shipmentId; const shipment = rs.callTool('Shipping API:20260707', 'getShipment', { id: shipmentId }); if (!shipment.ok) { rs.fail('Unable to fetch shipment', { shipmentId: shipmentId, cause: shipment.error }); } const policy = rs.callTool('Policy API:20260707', 'evaluateRefundPolicy', { orderStatus: order.content.status, shipmentStatus: shipment.content.status, totalAmount: order.content.totalAmount }); if (!policy.ok) { rs.fail('Unable to evaluate refund policy', { orderId: input.orderId, cause: policy.error }); } return { orderId: input.orderId, eligible: policy.content.eligible, reason: policy.content.reason, nextAction: policy.content.eligible ? 'create_refund' : 'escalate' }; ``` This is not an agent improvising a workflow in the context window. It is an operator-approved tool with a predictable contract. > **Scripted Custom Tools let agents ask for outcomes**, while reShapr keeps the workflow inside governed infrastructure. ### Optional chaining without losing control API chaining is powerful, but it should be **optional and explicit**. Some tools should stay declarative. A focused wrapper around one backend operation is often the cleanest solution. Other tools need orchestration, parallel calls, conditional checks, or cross-service lookups. reShapr supports **both forms** in the same `CustomTools` specification: - Use **`tool` and `arguments`** when one backend operation is enough. - Use **`script` and `tools`** when the business action needs controlled composition. That gives teams a practical migration path. You can begin with **selective exposure**, then introduce scripted tools only where the workflow deserves it. You do not have to choose between raw endpoint exposure and a fully custom MCP server project. reShapr gives you a middle path: **configuration first, scripting where it pays off**. Scripted tools also support asynchronous calls when independent backend calls can run in parallel: ```js const order = rs.callToolAsync('getOrder', { id: input.orderId }); const risk = rs.callToolAsync('Risk API:20260707', 'scoreOrder', { orderId: input.orderId }); const results = rs.awaitPromises([order, risk]); return { order: results[0].ok ? results[0].content : { error: results[0].error }, risk: results[1].ok ? results[1].content : { error: results[1].error } }; ``` The model does not need to juggle those intermediate calls. It receives **the final result** the tool was designed to return. ### Output control is as important as input control **Custom Tools shape what the model can ask for.** [**Tools Output Filtering**](/docs/references/spec-outtools-filtering) shapes what the model receives back. That second half is critical. Even a well-designed tool can return a backend payload with **too many fields**. A customer object may include internal IDs, addresses, risk flags, metadata, nested arrays, pagination cursors, or fields that have no value for the current agent. A GraphQL response can be especially dense. A REST payload can be deeply nested. A gRPC response can still become large once converted to JSON. reShapr applies `ToolsOutputFilters` **after** the backend response has been converted into canonical JSON and **before** the MCP response is returned to the client. For example, the earlier `get_order_summary` tool may receive a rich backend order payload, but the agent only needs the fields required to answer support questions clearly. ```yaml apiVersion: reshapr.io/v1alpha1 kind: ToolsOutputFilters service: name: Orders API version: '20260707' filters: get_order_summary: jsonRetain: - /id - /status - /totalAmount - /customer/name - /shipment/status - /lineItems convertToToon: true ``` This keeps the context window focused on **the order summary**, not on the backend's full data model. ### A governed BFF, or BFA, for agents Traditional applications often use a Backend for Frontend pattern. The frontend should not be forced to understand every internal service, so teams create an API layer shaped for that user experience. A similar idea is emerging for agents. In [**The Back-end for Agents Pattern (BFA)**](https://medium.com/@mdbaraujo/the-back-end-for-agents-pattern-bfa-32e69baf8da3), Michael Douglas Barbosa Araujo describes a mediating layer where agents call stable, task-oriented operations instead of coupling directly to domain APIs, internal schemas, and backend workflows. reShapr makes this pattern concrete for MCP. **Custom Tools** define the agent-facing contract, **Scripted Custom Tools** compose approved backend calls, and **Tools Output Filtering** controls what returns to the model. Agents need the same separation, optimized for **tool choice**, **token budget**, **determinism**, **policy enforcement**, **traceability**, **data minimization**, and **safe cross-service workflows**. reShapr provides that layer for MCP. It lets platform teams translate existing systems into **task-specific tools** while preserving the governance already built around those systems. Agents do not receive raw operational sprawl. They receive **an approved action surface**. That surface can be different for each use case: - A support agent can see refund, shipment, and customer-summary tools. - A finance agent can see reconciliation and invoice tools. - A developer agent can see build, deploy, rollback, and incident tools. - A partner-facing agent can see a stricter filtered subset of the same backend capabilities. **Same services. Different exposures. Different contracts. Different output policies.** > reShapr does **not ask enterprises to replace their APIs**. It lets them expose the right version of those APIs to agents. ### Why this matters in production Prototype MCP servers can tolerate rough edges. Production systems cannot. In production, **every exposed tool becomes part of an operational contract** covering access, credentials, data boundaries, deterministic behavior, observability, and failure handling. reShapr's advantage is that these questions are addressed **at the integration layer**, not left to every agent prompt. **Custom Tools reduce the visible action surface.** **Scripted Custom Tools make multi-call workflows explicit.** **Tools Output Filtering keeps responses small and controlled.** Gateway guard-rails bound script execution with configurable limits such as timeout, maximum tool calls, and maximum scripted nesting depth. Together, these capabilities turn MCP exposure from a raw protocol bridge into an agent-ready integration fabric. ### In summary: expose actions, not sprawl The easiest way to connect an API to MCP is to **expose everything**. It is also the least disciplined. The better path is to **design the MCP surface** with the same care we already apply to public APIs, internal platforms, and production automation. With reShapr: - **Custom Tools** turn backend operations into clear agent actions. - **Scripted Custom Tools** compose approved tools into deterministic workflows. - **Tools Output Filtering** removes irrelevant or sensitive response data before it reaches the model. - **Protocol conversion** lets the same approach work across REST, GraphQL, and gRPC. - **Gateway controls** keep security, secrets, elicitation, audit, and tracing in the infrastructure layer. The result is not just **API-to-MCP conversion**. It is **API-to-agent design**. > Agents work best when they are **given fewer, better tools**. reShapr is how existing APIs become those tools. --- ## From Context Overload to Context Control!
![From context overload to context control — how reShapr makes MCP production-ready at enterprise scale](/img/blog/context-control-hero.jpeg)
Credit: Yacine Kheddache (KubeCon NA Atlanta)
### How reShapr Makes the Model Context Protocol Production-Ready? {/* truncate */} When Anthropic introduced the _Model Context Protocol (MCP)_, it provided developers with something they had been missing: a common language for connecting Large Language Model (LLM) and AI agents to existing systems and services. **But as the MCP ecosystem exploded, so did the** [**_context windows_**](https://medium.com/@pekastel/mcp-and-context-windows-lessons-learned-during-development-590e0b047916)**_!_** Anthropic’s own engineers recently wrote in “[Code execution with MCP: Building more efficient agents](https://www.anthropic.com/engineering/code-execution-with-mcp)” that agents now juggle _hundreds or thousands of tools_, and that every tool definition and intermediate result _consumes tokens,_ slowing agents, inflating costs, and sometimes even breaking workflows. At **reShapr**, we took that exact problem, token consumption and context-window explosion as the _starting point_ of our product design. Before Anthropic formalized the MCP “code-execution” pattern, we asked a more straightforward question: > _What if the protocol wasn’t the issue? What if the_ **_problem was how we expose APIs to it_**_?_ ### We built reShapr on “tokens first” thinking Anthropic’s post illustrates two pain points: 1. Loading all MCP tool definitions upfront floods the model’s context. 2. Intermediate results, even megabytes of JSON or text, must pass back through the model. Both are symptoms of what we call **context coupling**: treating the model’s memory as a data bus instead of an intent space. When we designed the **reShapr’s No-Code MCP Server**, we flipped that pattern. Instead of dumping every API operation and description into the model, _reShapr acts as a programmable filter between your existing API services and the MCP interface._ That design allows you to: - **Selectively translate** only the operations you need into MCP tools. - **Restrict** which tools are visible to which clients, agents, or LLM personas. - **Partition** your exposure by business domain, use case, or security zone. In other words, while the Anthropic team optimized the _client-side execution loop_, reShapr optimized the _server-side surface area_. > We shrink the tool universe **before the model ever sees** it. ### One backend, many MCP faces Here’s where reShapr becomes powerful. From a single backend API service, your CRM, payment gateway, or internal microservice, you can create _multiple MCP servers_, each with: - Its own **name**, **tool set**, and **access policy**. - Its own **domain focus** (e.g., “finance”, “support”, “analytics”). - Optional **context filtering rules** for sensitive data or operations. Need to give a marketing AI access to campaign metrics but not customer PII? Spin up an **mcp-marketing** server exposing only `/metrics` and `/reports`. Need a developer agent to deploy builds? Create **mcp-devops** with `deploy`, `rollback`, and `status` tools. > Same backend, different MCP surface, but **zero code**. This _domain specialization_ not only mirrors real business boundaries; it also **keeps the model’s working set lean**. Why make Claude, ChatGPT, or any other LLM “see” thousands of endpoints if it only needs a few to do what is expected? ### Filtering at both ends Docker’s recent post, “[The Model Context Protocol: Simplifying Building AI apps with Anthropic Claude Desktop and Docker](https://www.docker.com/blog/the-model-context-protocol-simplifying-building-ai-apps-with-anthropic-claude-desktop-and-docker/)_”_, praised Anthropic’s idea of filtering tool exposure for efficiency and safety. We couldn’t agree more, and we’ve implemented that concept from day one. Where Docker focuses on **local developer control** and discovery, a marketplace or container registry of MCP servers, reShapr **operates as an AI integration layer** in all environments (_dev_, _QA_, _prod_). Our filters exist not just for discovery, but for **policy enforcement**. Think of it as _defense in depth for context_: - reShapr filters **which APIs become MCP tools**. - It also filters **which tools each client or agent may call**. - It even filters **which API operations flow**, preventing oversharing. While Docker helps you _run_ MCP servers locally, **reShapr enables you to _govern_ them globally by enabling existing API services for the AI Era**. The two approaches are complementary, not competing, layers of the same emerging ecosystem. ### The context window isn’t infinite, and that’s okay! Anthropic’s own metrics show that replacing direct tool calls with “code execution” reduced token usage by _98.7 %_ in their benchmark scenario. That’s impressive, but it’s also proof of the underlying issue: **agents today overconsume context** because they’re given too much surface to reason about. At reShapr, we believe, that **context discipline beats context expansion**. Instead of asking “how can the model handle more?”, we ask “how can we give it less, but more meaningful input?” Our filtering architecture, domain-specific MCP servers, and selective exposure make it possible to: - Keep **token** budgets **predictable**. - Maintain **shorter prompt-response** cycles. - **Scale** agent ecosystems **horizontally** without blowing up **latency** or **cost**. > You can call it _context-aware architecture_ or, simply, good software engineering. ### Bringing legacy APIs into the AI era One of the most exciting side effects of reShapr’s design is how easily it **modernizes existing APIs**. Take [Stripe’s REST API](https://github.com/stripe/openapi) as an example. Its [OpenAPI](https://raw.githubusercontent.com/stripe/openapi/refs/heads/master/openapi/spec3.yaml) spec is comprehensive and **enormous**. Exposing it directly to an LLM would create a vast array of endpoints, parameters, and schemas, **none of which are optimized for conversational use**. With reShapr, you can wrap Stripe’s API once and expose tailored MCP views: - **mcp-payments** exposing only `create charge`, `refund`, and `list customers`. - **mcp-finops** exposing `reconcile payouts`and `generate statement`. - **mcp-analytics** exposing `top-10 customers`with simplified schemas. Each of these servers can live side-by-side, derived from the same Stripe backend, yet independently optimized for distinct AI personas or business functions. > That’s what we mean when we say **“AI-native by translation, not reinvention.”** ### No-Code setup, enterprise-grade results reShapr’s configuration model is intentionally simple: 1. Connect to your existing [**Rest API**](https://swagger.io/specification/), [**GraphQL**](https://graphql.org/), or [**gRPC**](https://grpc.io/) service. 2. Use our interface to select the operations you want to expose. 3. Add optional field-level filters, renames, or descriptions. 4. Publish, and you instantly have a fully compliant MCP server or workflow of MCP servers. Behind the scenes, reShapr automatically: - **Generates** the MCP schema and metadata. - **Handles** auth propagation and error mapping. - **Enforces** your security and throttling policies. - **Provides** live observability dashboards for every tool call. What Anthropic’s engineers call “progressive disclosure”, which allows models to discover only the tools they need, occurs _naturally_ in reShapr through **configuration**, rather than **custom code**. ### Scaling AI with less friction, not more code Anthropic’s “code execution” pattern is brilliant for power users and developer-friendly agents that can write their own scripts. But in enterprise environments, most teams don’t want every agent writing arbitrary code in a sandbox. They want **predictability**, **governance**, and **measurable efficiency**. reShapr delivers that by externalizing code execution into _controlled MCP endpoints_ rather than letting each agent spin its custom code. You receive all the benefits, including reduced token usage, efficient data handling, and composable workflows, without the operational risk associated with distributed sandboxes. And when you do want to give agents controlled compute, reShapr integrates **seamlessly** with your **existing infrastructure**: Kubernetes jobs, serverless functions, or dedicated compute pools all behind the same **No-Code MCP Server** powered by reShapr. ### Complementing, not competing, with the ecosystem Let’s be clear: the work from Anthropic, Docker, and MCP / API Gateway vendors is moving the entire industry forward. Each focuses on a different layer: > We stand on their shoulders and **build the bridge between** prototype and **production**. reShapr is what **makes the MCP ecosystem _deployable at scale_**. ### Toward a governed, efficient AI integration fabric As MCP adoption accelerates, organizations face the same maturity curve APIs did a decade ago: 1. **Experimentation** — local prototypes and SDKs. 2. **Expansion** — hundreds of endpoints and tools. 3. **Governance** — access control, observability, cost management. 4. **Optimization** — token efficiency, domain specialization, and security. reShapr sits squarely at stages _2_, _3_ and _4_. We help teams operationalize MCP servers safely, efficiently, and at scale, **without requiring them to rewrite their systems or manually code integrations**. ### In summary: Control the context, don’t expand it Anthropic’s _Code Execution with MCP_ article is an important milestone. It demonstrates how agents can be more intelligent about tool usage by converting direct calls into code. reShapr builds on that same insight, but applies it to the _entire lifecycle_ of MCP deployment. - We **anticipated** the token and context explosion problem. - We **engineered** a system that filters, segments, and secures MCP exposure. - We **deliver** remote-first, production-ready servers, not non-realistic experiments. - We **complement** Anthropic and others, including Docker, API, and MCP Gateway vendors, by bringing enterprise rigor to the protocol. In AI integrations, as in good software design, **less context is often more powerful**. > Ultimately, the goal isn’t to make **LLMs** see more; it’s to **make them see _better_**. --- ## reShapr vs Official GitHub MCP 🥊
### 31 Tool Calls Become 1 Predictable Agent Action {/* truncate */} This benchmark answers a practical agent question and turns the concepts introduced in our previous posts, [From Context Overload to Context Control](https://reshapr.io/blog/from-context-overload-to-context-control) and [From API Sprawl to Agent Actions](https://reshapr.io/blog/from-api-sprawl-to-agent-actions), into a **real-world measurement**. By providing a **fair comparison** between the **official GitHub MCP tools** and **reShapr**, it shows how task-shaped MCP actions translate into **measurable performance gains**. > If an AI agent needs **recent pull request velocity** for `microsoft/vscode`, the public GitHub repository for Visual Studio Code, should it drive the official GitHub MCP pull-request tools directly, or should it call **one purpose-built reShapr MCP action**? ## The Use Case The test is **intentionally narrow and reproducible**. The agent starts with a simple goal: understand recent pull request velocity in `microsoft/vscode`. To answer it properly, it needs the **10 most recently updated pull requests**, the details for each pull request, **up to 5 review touchpoints**, and **up to 10 changed file paths** per pull request. That is a realistic workflow for **release tracking**, **engineering management**, **review triage**, and **agentic codebase analysis**. It is also exactly the kind of workflow where **generic tools create agent overhead**: list the pull requests, then loop over each pull request to fetch details, reviews, and files. The official GitHub MCP path exposes useful **primitive tools**. reShapr turns the same API surface into **one higher-level MCP action**. This matters beyond speed. reShapr makes repeated agent workflows **predictable, reliable, and reproducible**. The model can still reason and decide, but the workflow boundary becomes stable: **one named action, one input schema, one output shape, one measurable execution path**. ## The Result This is the latest **measured live run** against `microsoft/vscode`, using the **same 10 pull requests** for the official MCP and reShapr custom-action comparison:
Then reShapr applies a **second, independent optimization** at the **output boundary**. The same custom action was called through two `ToolsOutputFilters` artifacts on a matched reShapr run: first with **JSON retain/patch rules**, then with the same filter plus **`convertToToon: true`**. The official GitHub MCP baseline does not expose an equivalent output-filter artifact in this test, so the comparison stays explicit: **official primitive workflow versus reShapr custom action**, then **reShapr custom action versus reShapr custom action with output filtering**.
That second optimization is smaller than the **31-to-1 action design**, but it still matters: another **12.4% response-byte reduction** from the custom action to filtered TOON output, on top of the main **97.2% reduction** versus the official GitHub MCP loop. The key point is **fairness**: reShapr does not pretend GitHub has less data. The reShapr action still performs the **source GitHub operations** needed to produce the answer. The win is that the agent sees **one semantic tool call, one compact response, and one stable task-shaped contract**. ## Methodology The most natural way to run this use case is through **ChatGPT or another MCP-capable conversational agent**. A user would normally ask for the **outcome**, not for the individual API calls: ```text Using the available GitHub MCP tools, analyze recent pull request velocity for the public repository microsoft/vscode. Use the 10 most recently updated pull requests. For each pull request, collect the pull request details, up to 5 review touchpoints, and up to 10 changed file paths. Return a compact summary with pull request id, title, creator, state, creation and merge timestamps, review touchpoints, and changed paths. ``` That is the typical agent experience: **one natural-language request becomes a multi-step MCP tool plan**. The model has to decide how to list pull requests, fan out over the selected pull requests, and gather the details, reviews, and changed files before it can synthesize an answer. With reShapr, the conversational agent can call **one task-shaped action**: ```json { "name": "get_repo_velocity_metrics", "arguments": { "owner": "microsoft", "name": "vscode", "prCount": 10, "reviewCount": 5, "fileCount": 10 } } ``` For the benchmark, we did not want the measurement to depend on **model behavior**. Different models, prompts, retry policies, or agent runtimes can make slightly different planning choices. One run may call tools in a different order. Another may inspect extra fields, retry a tool call, or stop early after a transient error. So the benchmark separates the **user experience** from the **measurement method**. The LLM prompt describes the real agent task. The **curl-based benchmark** measures the underlying MCP workflow directly. It sends the **same MCP requests over Streamable HTTP**, records each HTTP roundtrip, captures each `tools/call` response body, and calculates **latency, bytes, and estimated token load** from the collected responses. This gives us a **technical, predictable, and reproducible** way to measure the benchmark without letting **model behavior distort the numbers**. The expected LLM-agent result should be directionally the same: the official GitHub MCP path needs a **multi-call loop**, while the reShapr path exposes **one task-shaped action**. The curl benchmark makes that difference **explicit and auditable**. ## Why This Benchmark Agents are bad at **unnecessary loops**. Every extra tool call adds protocol overhead, latency, logs, error states, retry decisions, and context the model may need to read. Pull request velocity is a clean benchmark because the naive workflow naturally becomes **`1 + 3N` tool calls**: one call to list pull requests, then three follow-up calls for every pull request to fetch details, reviews, and changed files. For 10 pull requests, this is: ```text 1 list call + (10 PRs * 3 follow-up calls) = 31 agent-facing MCP tool calls ``` With reShapr, the agent calls: ```text get_repo_velocity_metrics(owner: "microsoft", name: "vscode", prCount: 10, reviewCount: 5, fileCount: 10) ``` The action returns **only what the use case needs**: pull request id, title, creator, state, creation and merge timestamps, review touchpoints, and changed paths. That is the demonstration: not "can MCP call GitHub?", but **"can we shape an API into the tool the agent actually needed?"** ## The Bigger Issue: Predictable Agents LLM-driven agents are powerful because they can adapt, but that flexibility becomes a liability when the **same business workflow is rediscovered on every run**. One run may call tools in a different order. Another may skip a follow-up call. Another may over-fetch data, hit a transient error, or spend context on fields the task never needed. reShapr does not make the model deterministic. It makes the **agent workflow boundary predictable**. With the primitive-tool path, the agent is responsible for planning and executing the full loop: ```text list pull requests -> for each pull request -> get details -> get reviews -> get files -> shape the result ``` With reShapr, that loop becomes a reusable MCP action: ```text get_repo_velocity_metrics ``` The operational benefits are concrete. The **tool-call count** becomes predictable, **latency and payload size** become measurable, the **output shape** stays stable, and **failures** are localized to one action. Most importantly, **the same workflow** can be reproduced by humans, tests, and agents. This is a big deal for agent adoption. Teams do not only need agents that can improvise. They need agent capabilities that can be **audited, benchmarked, documented, and run again with confidence**. ## What Is Being Compared Both paths use **Streamable HTTP MCP**, not stdio. The **official GitHub MCP path** uses the remote endpoint `https://api.githubcopilot.com/mcp/x/pull_requests/readonly` with the `X-MCP-Toolsets: pull_requests` header. The agent receives useful primitive tools, mainly `list_pull_requests` and `pull_request_read`, but it must still run the **full loop itself**: list pull requests, then fetch details, reviews, and files for each pull request. The **reShapr path** starts from the same **GitHub source of truth**. It imports the **full official GitHub REST OpenAPI YAML file** by URL, exposes GitHub REST operations through reShapr MCP, attaches **one custom tool** that orchestrates the pull request workflow, and can attach `ToolsOutputFilters` artifacts to **trim or TOON-encode** the custom action output. The result is a **compact task-specific payload** rather than a pile of primitive tool responses. Official GitHub OpenAPI URL used by reShapr: ```text https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.yaml ``` The OpenAPI file is **not copied into this article**. reShapr imports it directly from that URL. ## How reShapr Shapes the Workflow The key reShapr artifact is a small `CustomTools` definition. It tells reShapr which GitHub REST operations belong to the task and exposes the workflow as **one agent-facing action**: ```yaml apiVersion: reshapr.io/v1alpha1 kind: CustomTools service: name: GitHub v3 REST API version: "1.1.4" customTools: get_repo_velocity_metrics: description: Fetch recent pull requests, review touchpoints, and changed file paths as one compact repository velocity action. tools: - tool: get_repos_owner_repo_pulls - tool: get_repos_owner_repo_pulls_pull_number - tool: get_repos_owner_repo_pulls_pull_number_reviews - tool: get_repos_owner_repo_pulls_pull_number_files ``` Those **four primitive operations** are the calls a generic agent has to **discover, sequence, and repeat** when it drives GitHub MCP directly. reShapr keeps the source API operations **visible and measurable**, but moves the orchestration behind **one predictable action**: `get_repo_velocity_metrics`. That is the practical difference between exposing an **API** to an agent and exposing a **capability** to an agent. ## Reproduce It Yourself The **full benchmark package** is available in the reShapr demos repository: ```text https://github.com/reshaprio/reshapr-demos/tree/main/benchs/github-mcp-vs-reshapr ``` It includes the **README**, **scripts**, **reShapr artifacts**, **output filters**, **payload examples**, and **curl-only benchmark runner** used to collect the numbers in this article. Use it to run the benchmark against `microsoft/vscode`, inspect **every MCP request and response body**, and adapt the workflow to another repository or MCP server. The package keeps the setup **reproducible** while keeping this post focused on the story: **31 primitive tool calls become one predictable action**, then **output filtering and TOON** reduce the payload further. We welcome **feedback, comments, and contributions**. If you reproduce the benchmark on another repository, improve the harness, or want to compare another MCP server, contributions are welcome. ## How to Read the Numbers The benchmark separates **two things**: 1. MCP protocol roundtrips: every Streamable HTTP exchange, including initialization and `tools/list`. 2. Agent tool calls: only `tools/call` requests, because those are the calls an agent has to plan, issue, observe, and recover from. (*) For bytes and token estimate, the figures count **only tool-call response bodies**. That is the content the agent must consume to continue its work. The token estimate is intentionally simple: **response bytes divided by four**. The script uses `(bytes + 3) / 4` to round that byte-based estimate up to the nearest whole token. It is **not a tokenizer-specific claim**, but it is a useful size proxy. For the output-filter comparison, make sure the three reShapr variants inspect the **same pull request IDs**. `microsoft/vscode` is active enough that the "recently updated" set can change between runs. The published output-filter chart uses **one matched run** where all reShapr variants inspected the same 10 pull requests: ```text 325138,325045,325180,325168,325173,325170,325175,322952,325163,325165 ``` The reShapr payload includes this field: ```json { "source_backend_calls": 31 } ``` That field is important because it proves reShapr is **not hiding the source work**. It is consolidating the workflow at the **MCP boundary** and shaping the result **before the agent sees it**. ## Why reShapr Wins Here The official GitHub MCP path gives the agent general-purpose pull-request tools. That is useful, but the agent still has to plan and drive the workflow step by step. reShapr lets an API owner or platform team expose a use-case-level action: ```text get_repo_velocity_metrics ``` That action is better for agents because it has **one clear intent**, **one compact input schema**, **one response shape**, and **one failure surface**. It also gives the API owner one place to encode pagination, fan-out, filtering, and field selection, instead of asking every agent to rediscover that orchestration pattern at runtime. For platform teams, this is the practical reShapr advantage: it turns **existing APIs into agent-native tools** without asking every agent to rediscover the same orchestration loop. For this use case, the difference is not subtle. **31 agent tool calls become 1**. **34 MCP HTTP roundtrips become 4**. **267.8 KB** of official MCP tool responses becomes **7.4 KB**, and roughly **67.0K estimated tokens** becomes **1.9K**. When the use case can safely drop fields, **output filters and TOON** can reduce the already compact custom output further. That is the kind of improvement that changes **how reliable an agent workflow feels in practice**. ## What This Demonstrates This benchmark does not argue that primitive MCP tools are bad. They are necessary. It shows that primitive tools are often **not the right final interface for agents**. The best agent-facing interface is usually **not the raw API**. It is a **domain action shaped around the task**: ```text Repository velocity, not pull request plumbing. ``` reShapr provides the **missing layer**. It can import the **official API description**, expose it as **MCP over Streamable HTTP**, compose existing operations into a **custom tool**, reduce the payload to the **fields the task needs**, and keep the full flow **reproducible**. In this benchmark, that is why the reShapr approach wins: it keeps the **GitHub source of truth**, removes **avoidable agent overhead**, and turns a fragile multi-step agent loop into a **predictable workflow that can be reproduced, measured, and trusted**. --- ## Six Use Cases for Accelerating AI with reShapr 🚀 {/* markdownlint-disable MD001 MD026 MD030 MD045 */} If you’re aiming to build AI‑native applications faster without sacrificing security or overhauling existing infrastructure, [**reShapr**](https://reshapr.io/) offers a transformative edge. Here are six compelling use cases showcasing how organizations leverage reShapr to streamline API enablement, accelerate prototyping, and securely integrate AI into production.
![Six use cases for accelerating AI with reShapr — from API enablement to secure hybrid deployment](/img/blog/six-use-cases-hero.jpg)
Credit: [Osarugue Igbinoba](https://unsplash.com/fr/photos/couloir-en-arc-eclaire-xfbn4nNiS3s)
{/* truncate */} ### 1\. 🛠️ Convert Internal APIs into MCPs — AI Enablement in Minutes **Challenge:** Developers want internal APIs to be AI‑accessible without rewriting backends. **How reShapr helps:** - With reShapr, you can instantly expose existing REST, gRPC, or GraphQL APIs as Model Context Protocol (MCP) endpoints, requiring no code. - That means teams can prototype AI assistants or agents in minutes, rather than waiting for a backend redesign to occur. - Built on a No‑Code MCP Server with broad protocol compatibility, reShapr supports OpenAPI and gRPC out of the box. ### 2\. 🧪 Build Fast, Safe AI POCs — MVPs Using Live Data **Challenge:** How can you safely build an AI proof‑of‑concept using production data? **Solution with reShapr:** - Enables developers to connect AI prototypes directly to live APIs while enforcing policies and safeguards. - Data access remains secure and auditable, reducing risk and accelerating feedback loops. - Ideal for organizations testing use cases early before scaling to production. ### 3\. 🔁 Sync API and MCP Lifecycles — Prevent Contract Drift **Challenge:** API changes cause agent behavior to break. **reShapr’s approach:** - Integrates into CI/CD pipelines to automatically regenerate MCP schemas when APIs evolve. - Enforces version checks and alignment, minimizing manual maintenance and eliminating drift between endpoints and AI agents. ### 4\. 🌍 Multi‑Protocol Support — REST, gRPC, GraphQL? All Covered **Challenge:** Modern stacks often span multiple API protocols. **reShapr’s capability:** - Natively supports REST, gRPC, and GraphQL, turning any service into MCP tools for LLM consumption. - No extra translation layers or adapters required, ensuring performance and consistency across services. ### 5\. 🧱 Secure Cloud, Hybrid, or On‑Prem **Challenge:** Sensitive systems must remain inside secure perimeters. **reShapr’s flexibility:** - Supports fully on‑premises deployments or hybrid models where compute can reside in your private cloud. - Keeps data and logic inside firewalls while still enabling AI connectivity, making it a suitable fit for regulated sectors and enterprises. ### 6\. 📡 Gate External AI Agents — Safely Expose APIs Without Re‑architecting **Challenge:** Expose internal services to AI agents without rebuilding everything. **reShapr’s solution:** - Acts as a controlled MCP Server, enabling selective exposure of internal APIs. - Provides runtime controls, logging, and schema enforcement, so backends remain untouched but safely accessible. ### 🔍 Real World Example: Open Meteo REST → MCP with reShapr reShapr has been demonstrated to instantly translate the [Open-Meteo](https://open-meteo.com/) REST weather API into an MCP endpoint without requiring any code. This highlights how quickly external data sources can become AI‑ready tools using reShapr’s solution. First, authenticate with the reShapr online try: ```shell ❯ reshapr login -s https://try.reshapr.io ℹ️ Opening browser: https://try.reshapr.io/cli/login?redirect_uri=http://localhost:5556 ℹ️ Listening for authentication callback on http://localhost:5556 ✅ Login successful! ℹ️ Welcome, yada! ℹ️ Organization: yada ✅ Configuration saved to /Users/yacine/.reshapr/config ``` Then, import and expose the API as an MCP server using in a single command: ```shell ❯ reshapr import -u https://raw.githubusercontent.com/open-meteo/open-meteo/refs/heads/main/openapi/forecast.yml --backendEndpoint https://api.open-meteo.com ✅ Import successful! ℹ️ Discovered Service Open-Meteo APIs with ID: 0PXEW1ZDWFCZS ✅ Exposition done! ✅ Exposition is now active! Exposition ID : 0PXEW2272H0PB Organization : yada Created on : 2026-03-28T19:06:26.743899 Service ID : 0PXEW1ZDWFCZS Service Name : Open-Meteo APIs Service Version: 1.0 Service Type : REST -> https://api.open-meteo.com Endpoints : mcp.try.reshapr.io/mcp/yada/Open-Meteo+APIs/1.0 ``` That's it. Your MCP server is live at `https://mcp.try.reshapr.io/mcp/yada/Open-Meteo+APIs/1.0`, use `https` for reShapr Try, or `http` depending on your deployment. Connect it to any MCP client, LLM conversational agent, or agentic workflow as a remote HTTP Streamable MCP server and enjoy 😎 More demos available on our [YouTube channel](https://www.youtube.com/@reShapr) 🙌 ### ✅ Why reShapr Matters Whether you’re embedding AI assistants, building RAG workflows, or enabling LLM-driven agents, reShapr lets you move forward quickly **without compromising control**: - Instant MCP Server for internal or external APIs, securely exposed. - Safe AI experimentation on real data for faster iteration. - Seamless version control and lifecycle sync. - Protocol-agnostic support with no vendor lock-in. - Flexible deployment to match enterprise security policies. ### 🎯 Business Benefits Summarized #### Speed - Prototype AI integrations in minutes using production APIs with no backend overhaul #### Security & Compliance - Enforce governance, logging, and access controls even in sensitive environments #### Flexibility - Works across REST/GraphQL/gRPC, deploys Cloud, hybrid, or on-prem #### Cost Efficiency - Avoid rewriting backend services, minimize development overhead ### 🔗 Looking Ahead Integration into a modern AI ecosystem is as straightforward as flipping a switch, and your existing APIs become first-class AI-ready tools. > reShapr empowers businesses to **accelerate AI use cases**, **reduce integration friction**, and **deliver secure production-ready experiences while effectively leveraging existing infrastructure**. To explore reShapr’s vision and strategic context, see _"_[_Why reShapr_](/blog/why-reshapr)_"_ for deeper insight into the MCP framework and its architecture. --- ## Welcome to reShapr ⭐️ {/* markdownlint-disable MD001 MD026 MD030 MD045 */}
![Welcome to reShapr — Turn your API AI-Native](/img/blog/welcome-to-reshapr.jpg)
A few months ago, we started experimenting with a new idea through a project called **[Micepe](https://www.youtube.com/@Micepe)**. The idea was simple but powerful: What if existing APIs could instantly become MCP tools usable by AI agents without writing glue code? {/* truncate */} ## Collect feedback and validate our ideas We launched a private beta program with a handful of enterprises, and the response was beyond what we expected. The teams involved consistently told us the same thing: > This solves a **real problem for AI-native** architectures. ### The feedback we received
The first results from our reShapr evaluation at AXA are very promising. It addresses complex enterprise challenges with rare clarity and a true open source heart. As a maintainer in the CNCF space, I’m excited to support this community effort and see how it transforms how we expose services to agents.
Sebastien Degodez Software Engineer | TechLead
When organizations have hundreds or even thousands of APIs to maintain, speed and security become non-negotiable. reShapr transforms how existing services are exposed to agents, delivering an unmatched FinOps ratio and the fastest path to production. It’s a definitive solution for scaling agentic context within highly regulated environments.
Ludovic Pourrat API Architect | Platform Architect
I’m excited by reShapr’s clear purpose and the co-founders’ vision, which directly address the real-world challenges I see across the organizations I work with. Open-sourcing such a critical component to advance MCP democratization is a meaningful step forward for the ecosystem, and I’m genuinely looking forward to being part of this journey and helping build a strong, open community around reShapr.
Sébastien Blanc Java Champion | Developer Relations The discussions with platform teams and developers, and the **concrete use cases** we saw convinced us of one thing: - This should **not remain** a proprietary experiment. **It deserves to become an open project that the community can shape and build together.** ## Micepe is **evolving** into → reShapr So today, we are taking the next step, **reShapr** is a new open source project created by the co-founders and maintainers of **[Microcks](https://microcks.io/)**, the **[CNCF](https://landscape.cncf.io/?selected=microcks&item=app-definition-and-development--application-definition-image-build--microcks)** open source project used by organizations such as **BNP Paribas**, **J.B. Hunt**, **Amadeus**, **Michelin**, **GSMA** and **[many more](https://github.com/microcks/.github/blob/main/ADOPTERS.md)** to improve API and cloud native application development. With reShapr, our goal is to help organizations: - **Turn existing APIs** into AI-native tools **instantly** - **Expose services** as MCP servers for **AI agents** - **Accelerate** the adoption of **AI + cloud native** architectures The success of our private beta and the **amazing feedback from the enterprises involved** reinforced our conviction that the project should grow within an **open** ecosystem. We intend to donate the project to the **[AAIF](https://aaif.io/)** open source **foundation**, so it can evolve with community open governance, transparency, and long-term sustainability. ## This is just the beginning of the journey. If you followed Micepe, the story continues with **reShapr**. And if you are interested in **AI-native APIs**, **MCP** tools, and **developer platforms** for **AI agents**, we would love to have you involved in the project, the **open source** way. > **reShapr** is now **live** and **open** for the **community**. Join the **AI-Agent Revolution**. We are **building the future** of developer platforms for AI agents, the **open source** way. Whether it’s a **[GitHub ⭐️](https://github.com/reshaprio/reshapr)**, a bug report, or a pull request, we’d love to have you involved. ### Here’s how you can get involved: 🚀 **Check** it out: **[Try reShapr online](/docs/tutorials/try-reshapr-online)** 🤝 **Join** the project: On **[Discord](https://discord.gg/KyDUdam34h)**. **Help us** shape the future of AI-native APIs on **[GitHub](https://github.com/reshaprio/reshapr)** 📱 **Follow** us: Stay connected on **[LinkedIn](https://www.linkedin.com/company/reshapr/)**, **[Bluesky](https://bsky.app/profile/reshapr.io)**, **[X](https://x.com/reshaprio)** and **[YouTube](https://www.youtube.com/@reShaprio)** for the latest updates. --- ## Why reShapr?(Blog) {/* markdownlint-disable MD001 MD026 MD030 MD045 */} ## **Why Enterprises Shouldn’t Build MCP Servers from Scratch, and What to Do Instead** The AI-native era is here. Whether you’re integrating copilots into internal workflows, building LLM-powered agents for customer service, or exposing organizational knowledge to a retrieval-augmented generation (RAG) stack, the foundation is the same: (your) APIs. > But there’s a **major roadblock** that nearly every **enterprise** hits. {/* truncate */} ## The Problem: (Your) Services Weren’t Designed for LLMs Enterprises are under growing pressure to make internal and business services accessible to Large Language Models ([LLMs](https://www.ibm.com/think/topics/large-language-models)). But those services were not built for generative agents that parse documentation, generate prompts, or request human-like reasoning. Suddenly, platform teams are being asked: - “**How can** we let our AI assistant fetch data from our CRM, ERP, or ticketing systems?” - “**Can we** integrate our knowledge base into our chatbot by giving it access to our API?” - “**Is it safe** to let external copilots interact with internal endpoints?” The typical answer is to build a Model Context Protocol ([MCP](https://modelcontextprotocol.io/introduction)) server, a new service and development interface layer that AI models can use. > That’s where the **real** trouble begins. ## Why Building Your Own MCP Server Is a Trap A Model Context Protocol (MCP) server acts as the bridge between Large Language Models (LLMs) and your services. At first glance, building one may seem straightforward. But very quickly, most teams realize: - **It’s more than OpenAPI**: You need translation layers, prompt guards, retries, rate limiting, and grounding logic. - **Security gets messy fast**: How do you avoid exposing credentials in LLM prompts? How do you enforce identity, scope, and input validation? - **Fragility creeps in**: Most DIY solutions end up as brittle pipelines of JSON transforms, hardcoded logic, and embedded hacks that fall apart under load or worse, leak data. This approach often duplicates your API logic into a parallel, standalone MCP layer, creating unnecessary complexity, increased maintenance overhead, and misalignment between your API and its AI-facing interface. > A smarter approach is to extend your **existing API infrastructure** rather than reinventing it. ## Introducing reShapr: Your Zero-Code AI Translation Layer reShapr exists to solve this exact problem. Rather than building an MCP server from scratch, you can use reShapr to **instantly translate your existing APIs (REST, gRPC, GraphQL) into AI-native endpoints.** - **Zero** code - **No** rewrites - **No** custom Agents - **No** vendor lock-in > Think of it as a **plug-and-play** interface between your infrastructure and the AI-native world. ## Time-to-Market Matters: How reShapr Accelerates AI Deployment ### Let’s compare two paths to AI-native readiness With reShapr, your team can: - Deploy an AI-native interface **in minutes, not** weeks/months. - Avoid rewriting APIs or **duplicating business logic**. - Launch pilots **quickly** and iterate **without platform bottlenecks**. - Get to **proof of value before your competitors** even clear their architecture review.
![Comparison of DIY MCP server development taking weeks versus reShapr zero-code deployment in minutes](/img/blog/why-reshapr-inline.png)
Allocation icons created by kmg design — [Flaticon](https://www.flaticon.com/free-icons/allocation).
> Speed isn’t just convenience; it’s a **competitive** advantage. ### Secure by Design: Leverage What You Already Trust When it comes to security, we don’t believe in reinventing the wheel. reShapr’s philosophy is simple: **build on top of the infrastructure, controls, and credentials you already trust.** ### Here’s how: - **Reuse Existing Policies**: Identity, rate limiting, scopes, and audit logging are inherited from your infrastructure (API gateway). There is no need to rebuild backend authentication or create shadow permission systems. - **OAuth2 support**: Optionally leverage the latest MCP protocol enhancements to enable secure additional authentication at the reShapr layer. - **Multi-Protocol Support**: Whether your backend speaks REST, gRPC, or GraphQL, reShapr understands it, without flattening security models or introducing fragile transforms. - **Leverage trusted infrastructure**: reShapr translates your existing API operations into MCP tools, making all your current security layers and validations automatically apply to LLM-generated requests transparently and without modification. You simply reuse the same production-hardened controls you already trust. > Security isn’t an afterthought; it’s a **prerequisite for exposing APIs** to any AI agent. reShapr gives you the controls **without** the complexity. 👉 **Read** "[Security options & Secrets](/docs/explanations/security-model)" ### Developer Experience That Doesn’t Fight You We know what it’s like to be asked to ship an AI feature “by the end of the quarter.” That’s why reShapr was built with a developer-first mindset: - **One command to deploy**: Configure your MCP interface with a simple Rest API, CLI or UI. - **Declarative Config**: Specify how each API should be exposed, if at all and define which operations are permitted or excluded. - **Infrastructure Agnostic**: Works with any cloud, on-premise deployment, or hybrid environment. - **Portable and Auditable**: No hidden agents. No black boxes. You stay in control. > It’s not magic; it’s just good engineering, abstracted for real-world use. ### Built by People Who’ve Been There The reShapr team has designed API gateways, built security systems, and operated large-scale cloud infrastructure. We’ve seen the fragile SDK generators, the spaghetti YAML, and the LLM prompt hell, and we knew there had to be a better way. > So we built one! ## Why This Matters Now Enterprises are racing to make their data and systems usable with AI-native tools. But each delay in integration leads to lost market share, stalled innovation, and missed opportunities. The organizations that win will not be the ones that spend months writing custom LLM plugins. They will be the ones that expose their APIs **safely, scalably, and instantly.** > reShapr makes that possible with **zero code** and **full** control. ## TL;DR: Why Choose reShapr 🤔 - ✅ **Fastest path to AI-native APIs**, from concept to production in a day. - ✅ **No rewrites**, works with your existing REST, gRPC, or GraphQL APIs. - ✅ **Security-first**, leverages your existing infrastructure and shields against prompt ingestion risks. - ✅ **Highly portable**, no vendor lock-in: deploy anywhere. - ✅ **Enterprise-ready**, built for scale, extensibility, and real-world complexity. ## Ready to Try reShapr? If you’re exploring how to safely expose your APIs to LLMs, whether for internal copilots, customer-facing agents, or RAG backends, **reShapr is the fastest and most secure way to do it.** > 1. Use the [**Try it Online**](https://try.reshapr.io) option to explore the platform. Follow our detailed ["Try reShapr online"](https://reshapr.io/docs/tutorials/try-reshapr-online). > 2. Or Run the platform locally using containers, check out the [“Run using Docker Compose”](https://reshapr.io/docs/how-to-guides/docker-compose/). **Make your APIs usable by AI without rewriting a single line of code.**