Skip to main content
The bridge.mcp/v1 manifest is the artifact that Bridge generates with bridge generate mcp and serves with bridge mcp serve or bridge mcp serve-http. It describes the MCP server name, the data source it reads from, the runtime transport it uses, and the tools it exposes. Manifests are plain YAML. You can commit them to version control. They contain no secrets — connection strings and tokens are referenced by environment variable name, not stored inline.
Bridge generates manifests automatically. You generally do not need to write one by hand. This page documents the format for cases where you want to understand or edit a generated manifest.

​
Top-level structure

# Generated by bridge. Do not edit by hand unless you know what you are doing.
# Manifest kind: bridge.mcp/v1
kind: bridge.mcp/v1
name: my-api
source:
  type: openapi
  path: ./openapi.yaml
runtime:
  transport: stdio
  base_url_env: API_BASE_URL
  auth:
    type: bearer
    token_env: API_TOKEN
tools:
  - name: get_users
    ...
FieldRequiredDescription
kindyesMust be bridge.mcp/v1. Bridge rejects manifests with any other value.
nameyesName of the MCP server. Shown to MCP clients and used in client config snippets.
sourceyesWhere the manifest was generated from. See Source.
runtimeyesHow the server connects to the backend at runtime. See Runtime.
toolsyesList of MCP tools the server exposes. See Tools.

​
Source

The source block records where the manifest came from. Bridge uses it at generation time; at serve time, the tool execute plans are authoritative.

​
OpenAPI source

source:
  type: openapi
  path: ./openapi.yaml
FieldDescription
typeopenapi
pathPath to the OpenAPI spec file at generation time. Informational only at serve time.

​
Database source

source:
  type: db
  connection: db
  dialect: postgres
  schema: public
FieldDescription
typedb
connectionName of a Bridge provider in bridge.yaml. Bridge resolves this at serve time to get the actual connection string.
dialectSQL dialect. postgres and sqlite are supported.
schemaSchema the manifest was generated from. Informational only — each tool’s execute plan carries its own schema field.

​
Runtime

The runtime block controls how the server reaches the backend when handling requests. 
runtime:
  transport: stdio
  base_url_env: API_BASE_URL
  base_url: https://api.example.com
  auth:
    type: bearer
    token_env: API_TOKEN
FieldRequiredDescription
transportyesMust be stdio. HTTP transport is configured on the command line, not in the manifest.
base_url_envnoName of an environment variable holding the API base URL. Used by OpenAPI-backed tools. Takes precedence over base_url.
base_urlnoLiteral base URL. Used when base_url_env is not set.
authnoAuthentication config. See Auth.
Bridge resolves base_url_env from the process environment at server startup. If the variable is referenced but not set, the server exits with an error.

​
Auth

auth:
  type: bearer
  token_env: API_TOKEN
FieldDescription
typebearer is the only supported auth type today.
token_envName of an environment variable holding the bearer token. Bridge injects it as an Authorization: Bearer <token> header on every outbound HTTP request.

​
Tools

Each entry in tools is one MCP tool the server exposes to clients. 
tools:
  - name: get_users
    description: Returns a list of users.
    annotations:
      readOnlyHint: true
    input_schema:
      type: object
      properties:
        limit:
          type: integer
          description: Maximum number of results to return.
      required: []
    execute:
      type: http
      method: GET
      path: /users
      parameters:
        - name: limit
          location: query
          required: false
FieldRequiredDescription
nameyesTool name. Must be unique within the manifest. Only alphanumeric characters and underscores are allowed.
descriptionnoHuman-readable description shown to MCP clients.
annotationsnoMCP tool annotations. See Annotations.
input_schemayesJSON Schema object describing the tool’s input.
output_schemanoJSON Schema object describing the tool’s output. Optional.
executeyesThe execution plan. Either an HTTP call or a SQL SELECT. See Execute.

​
Annotations

Annotations are standard MCP tool hints. Bridge sets these automatically during generation. 
annotations:
  readOnlyHint: true
  destructiveHint: false
  idempotentHint: true
  openWorldHint: false
  title: Get Users
FieldDescription
readOnlyHintTool does not modify state. Bridge sets this to true for all generated tools.
destructiveHintTool may delete or modify data.
idempotentHintCalling the tool multiple times has the same effect as calling it once.
openWorldHintTool may interact with the outside world beyond the declared schema.
titleDisplay name for the tool, distinct from its machine-readable name.

​
Execute

The execute block is the execution plan Bridge uses to fulfill tool calls. Bridge validates this block at load time so misconfigured manifests fail immediately rather than at call time.

​
HTTP execute

Used by OpenAPI-backed tools. 
execute:
  type: http
  method: GET
  path: /users/{id}
  operation_id: getUser
  parameters:
    - name: id
      location: path
      required: true
    - name: include_deleted
      location: query
      required: false
FieldRequiredDescription
typeyeshttp
methodyesHTTP method. GET is the only supported value today.
pathyesURL path, relative to the base URL. May include {param} placeholders.
operation_idnoOpenAPI operationId, for traceability.
parametersnoOrdered list of parameters mapping tool input fields to path or query slots.
Each parameter entry:
FieldDescription
nameParameter name, matching a field in input_schema.
locationpath or query. Path parameters are interpolated into the URL. Query parameters are appended as ?key=value.
requiredWhether the parameter is required.

​
SQL SELECT execute

Used by database-backed tools. 
execute:
  type: sql_select
  connection_ref: db
  schema: public
  table: users
  mode: list
  selectable_columns: [id, name, email, created_at]
  column_types:
    id: integer
    name: text
    email: text
    created_at: timestamp
  filterable_columns: [id, name]
  sortable_columns: [id, created_at]
  limit:
    default: 25
    max: 100
FieldRequiredDescription
typeyessql_select
connection_refyesName of a Bridge connection in bridge.yaml. Resolved at serve time.
schemayesDatabase schema name. Only [a-zA-Z0-9_] characters are accepted.
tableyesTable or view name. Only [a-zA-Z0-9_] characters are accepted.
modeyeslist returns multiple rows. get_by_key returns one row by a key column.
selectable_columnsyesColumns projected in the SELECT clause. Only these columns can appear in filters or sorts.
column_typesnoPer-column SQL types used for safe casting and JSON decoding. Keys must match selectable_columns.
filterable_columnsnoColumns allowed as equality filters. Must be a subset of selectable_columns.
sortable_columnsnoColumns allowed in ORDER BY. Must be a subset of selectable_columns.
key_columnnoColumn used by get_by_key mode. Must also appear in filterable_columns.
limitnoPagination bounds for list mode. See below.
Column types (column_types values): integer, float, numeric, boolean, text, timestamp, uuid, json Limit spec: 
limit:
  default: 25
  max: 100
FieldDescription
defaultDefault row limit when the caller does not specify one.
maxMaximum rows a caller can request. Cannot exceed 1000 (the server hard cap). default cannot exceed max.
Bridge enforces the hard row cap at load time. Manifests with limit.max above 1000 are rejected before the server starts.

​
Validation

Bridge validates the manifest at load time (when you run bridge mcp serve or bridge mcp serve-http). It also validates at generation time. Validation checks:
  • kind is exactly bridge.mcp/v1
  • name is non-empty
  • all tool names are unique and non-empty
  • input_schema is a JSON object for every tool
  • all column names in SQL plans contain only [a-zA-Z0-9_]
  • filterable_columns and sortable_columns are subsets of selectable_columns
  • key_column is also in filterable_columns
  • limit.max does not exceed 1000
  • limit.default does not exceed limit.max
Manifests that fail validation exit immediately with a manifest_error and a description of the problem.

​
A complete example

OpenAPI-backed manifest: 
# Generated by bridge. Do not edit by hand unless you know what you are doing.
# Manifest kind: bridge.mcp/v1
kind: bridge.mcp/v1
name: petstore
source:
  type: openapi
  path: ./petstore.yaml
runtime:
  transport: stdio
  base_url_env: PETSTORE_API_URL
  auth:
    type: bearer
    token_env: PETSTORE_TOKEN
tools:
  - name: list_pets
    description: Returns all pets from the store.
    annotations:
      readOnlyHint: true
    input_schema:
      type: object
      properties:
        limit:
          type: integer
      required: []
    execute:
      type: http
      method: GET
      path: /pets
      parameters:
        - name: limit
          location: query
          required: false
  - name: get_pet_by_id
    description: Returns a single pet by ID.
    annotations:
      readOnlyHint: true
    input_schema:
      type: object
      properties:
        petId:
          type: integer
      required: [petId]
    execute:
      type: http
      method: GET
      path: /pets/{petId}
      parameters:
        - name: petId
          location: path
          required: true

Generate an MCP server

Generate a manifest from an OpenAPI spec, Postgres, or SQLite.

Serve an MCP server

Run a manifest over stdio or HTTP and wire it into Claude Desktop or Cursor.

Commands

Full reference for bridge generate mcp and bridge mcp serve.

Security and errors

How Bridge validates manifests and handles runtime errors.