> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.fabricgateway.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.fabricgateway.ai/_mcp/server.

# MCP HTTP Bridge plugin

> Reference and setup steps for the MCP HTTP Bridge plugin, which serves a REST API on an MCP route as MCP tools generated from its OpenAPI spec.

The MCP HTTP Bridge plugin lets an agent use a plain REST API through an MCP route. The agent sees MCP tools. When the agent calls one, the gateway turns the call into a real HTTP request to the REST API and returns the response as the tool result.

The control plane builds the tools from the OpenAPI spec that you imported when you created the REST connection. You choose which operations become tools, and you can rename them. The data plane applies the result and never reads the spec. Authentication, tool prefixing, filtering, redaction, and billing on the MCP route work as for any other MCP connection.

## Where it runs

|             |                                                                                                                 |
| ----------- | --------------------------------------------------------------------------------------------------------------- |
| Protocols   | MCP                                                                                                             |
| Scope kinds | `route` only. Each instance fronts one REST service on that route.                                              |
| Phase       | Request. The plugin stages its configuration, and the MCP adapter serves `tools/list` and `tools/call` from it. |

## Set up the plugin

The console has no form for this plugin. You compile the tools and save the instance with the admin API.

### Prerequisites

Before you begin, make sure you have the following:

* A REST connection that you created by importing an OpenAPI spec. For the steps, see [Import an OpenAPI spec](/configure/connections/rest-apis#import-an-openapi-spec). A connection that you added by hand has no stored spec, so compiling it fails with `404`.
* An MCP route that uses that connection.
* An admin API key and your tenant ID. For the steps, see [Configure the gateway with the admin API](/configure/automation/admin-api).
* A list of the operations to expose, as `METHOD /path` keys such as `GET /pets`. The plugin exposes nothing that you don't list.

### Steps

1. Preview the configuration. Send the name of the REST connection and the operations to expose to the compile endpoint:

   ```bash
   curl -X POST "$FABRIC_API/plugin-instances/mcp-http-bridge/compile" \
     -H "fg-tenant-api-key: $FABRIC_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "service": "petstore",
       "curation": { "include": { "GET /pets": {}, "GET /pets/{petId}": { "name": "get_pet" } } }
     }'
   ```

   Nothing is saved. The response has the `config` to save, the list of `operations` with `included` flags, `warnings`, operations the compiler `skipped`, and a `diff` against the earlier compile. An empty `include` returns a warning and no tools.
2. Review the `operations`, `warnings`, and `skipped` fields. To rename a tool or change its description, set `name` or `description` for the operation in `include`, and compile again. Tool names use letters, digits, `_`, and `-`, up to 64 characters.
3. Save the instance. Send the `config` object from the compile response unchanged:

   ```bash
   curl -X POST "$FABRIC_API/plugin-instances" \
     -H "fg-tenant-api-key: $FABRIC_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "petstore-bridge",
       "plugin_id": "mcp-http-bridge",
       "scope": { "kind": "route", "name": "petstore-mcp" },
       "config": COMPILED_CONFIG
     }'
   ```

   The control plane checks the configuration when you save it, and returns `400` with the reason if it's invalid. Data planes pick up the change a moment later.
4. To pick up changes to the REST API, import the updated spec again, and then repeat the compile and save. Operations that you add to the spec later appear in the `diff` as new and stay off until you include them. To update the saved instance, send the new configuration with `PUT`.

### Verify it works

To check that the route serves the tools, do the following:

1. Send `tools/list` to the MCP route with your usual MCP credentials. The result lists exactly the tools that you included.
2. Send a `tools/call` for one tool, with arguments that match its input schema. The result holds the REST API's response body as text.
3. Send a `tools/call` with an argument that breaks the schema. The result has `isError` set to `true`, and the REST API isn't called.

For a command-line client, use the MCP Inspector:

```bash
npx @modelcontextprotocol/inspector --cli https://<gateway-host>/<route-path> --transport http --method tools/list
```

### Fix common problems

| Problem                                                                           | Cause                                                                                         | Fix                                                                                        |
| --------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| Compile returns `404` and says the service wasn't created from an OpenAPI import. | The connection has no stored spec.                                                            | Import the spec to create or update the connection, and then compile again.                |
| Compile returns `501`.                                                            | The control plane runs on the standalone bbolt backend, which doesn't support OpenAPI import. | Use the MySQL-backed control plane.                                                        |
| Compile returns a warning and no tools.                                           | `curation.include` is empty.                                                                  | List the operations to expose.                                                             |
| Saving returns `400` and says the curation and the tools differ.                  | The configuration doesn't match what compile returned.                                        | Compile again, and send the returned `config` unchanged.                                   |
| `tools/list` is empty or lacks a tool.                                            | The operation isn't in `include`, the instance is disabled, or it's on a different route.     | Check the instance's scope and `enabled` setting, and compile with the operation included. |
| A tool call returns "this route's tool configuration is invalid".                 | The data plane can't parse the saved configuration.                                           | Compile and save the instance again.                                                       |
| A tool call returns `isError` with `HTTP 4xx` or `HTTP 5xx` and a body.           | The REST API answered with that status.                                                       | Fix the request or the API. The bridge returns the status and body as the tool result.     |

## Configuration

Don't write this configuration by hand. The compile endpoint builds it from the spec, and the control plane rejects a saved configuration that doesn't match its curation.

**`service`** `string` — required

The name of the REST connection on the route that the tools front.

---

**`tools`** `array of objects`

The tools to expose, at most 200. Names must be unique.

---

**`tools[].name`** `string` — required

The tool name that the agent sees.

---

**`tools[].description`** `string`

The tool description that the agent sees.

---

**`tools[].input_schema`** `object` — required

The JSON Schema for the tool's arguments. The gateway validates every call against it. References to files or URLs outside the schema are rejected.

---

**`tools[].method`** `string` — required

The HTTP method: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, or `HEAD`.

---

**`tools[].path`** `string` — required

The request path template, such as `/pets/{petId}`. It must start with `/`, and every placeholder needs a path argument.

---

**`tools[].args`** `object`

Maps each input property to where its value goes in the request. `in` is `path`, `query`, or `body`. Header arguments aren't supported. A query argument can use the `form` or `deepObject` style. Body arguments nest into one JSON object, and an argument with an empty `name` is the whole body.

---

**`curation`** `object`

Your choice of operations, which the control plane keeps so that it survives spec updates. `include` maps an operation key to optional `name` and `description` overrides. `seen` records the operations from the last compile. The data plane ignores it.

---

An instance can be at most 1 MiB, curation included, because every data plane receives it. For each call, the gateway rotates through the connection's upstreams, skips any that are pin-only, sends the request with the connection's credential and timeout, and doesn't follow redirects. It returns a `2xx` body as text, and a `4xx` or `5xx` response as an error result with the status and body. A response over 4 MiB returns "upstream response too large". If no upstream is left, the call fails with `service "<name>" has no routable upstream`.

## Example

```json
{
  "name": "petstore-bridge",
  "plugin_id": "mcp-http-bridge",
  "scope": { "kind": "route", "name": "petstore-mcp" },
  "config": {
    "service": "petstore",
    "tools": [
      {
        "name": "get_pet",
        "description": "Get a pet by ID.",
        "input_schema": {
          "type": "object",
          "properties": { "petId": { "type": "string" } },
          "required": ["petId"]
        },
        "method": "GET",
        "path": "/pets/{petId}",
        "args": { "petId": { "in": "path", "name": "petId" } }
      }
    ],
    "curation": { "include": { "GET /pets/{petId}": { "name": "get_pet" } } }
  }
}
```

## Related guides

* [Connect a REST API](/configure/connections/rest-apis)
* [Configure the gateway with the admin API](/configure/automation/admin-api)
* [Control traffic with plugins](/configure/plugins)