mcp-api-bridge

An MCP server that puts your existing in-house catalog search APIs in front of any MCP client, with Amazon Bedrock doing the natural-language → structured query translation.

Two ideas carry the whole thing:

1. Catalogs are configuration, not code. A YAML file describes each API's URL, auth, request shape, and response shape. Adding a catalog means adding a config block.
2. The filter vocabulary is the prompt. The description, type, and values you write for each filter are handed to Bedrock verbatim as the vocabulary it maps language onto. Describe a filter well and query understanding works for it — there is no separate prompt to maintain.

MCP client ──▶ mcp-api-bridge ──▶ Bedrock (Claude)   plan the query
                     │
                     └──────────▶ your catalog REST API   execute the search

Tools exposed

Tool	What it does
list_catalogs	Describes every configured catalog: its filters, allowed values, and sorts. Call this first to learn the vocabulary.
catalog_search	Runs a search with explicit filters / sort / paging. No model in the loop.
catalog_get_item	Fetches one item by id, for catalogs that configure a get_item endpoint.
understand_query	Bedrock turns a natural-language query into a QueryPlan — keywords, filters, sort, synonyms — without searching.
smart_search	understand_query then catalog_search, returning both the plan and the results.

catalog_search is deliberately usable on its own: when the client is already an LLM that knows the filter vocabulary from list_catalogs, the Bedrock hop is redundant latency. Reach for smart_search when a raw end-user string needs interpreting.

Quick start

uv venv && uv pip install -e ".[dev]"

cp config/catalog.example.yaml config/catalog.yaml   # then edit
cp .env.example .env                                 # then fill in

export MCP_API_BRIDGE_CONFIG=./config/catalog.yaml
export CATALOG_TOKEN=...        # whatever your config's auth blocks name
export AWS_REGION=us-east-1     # plus standard AWS credentials

.venv/bin/mcp-api-bridge        # speaks MCP over stdio

Register it with an MCP client:

{
  "mcpServers": {
    "catalog": {
      "command": "/path/to/mcp-api-bridge/.venv/bin/mcp-api-bridge",
      "env": {
        "MCP_API_BRIDGE_CONFIG": "/path/to/config/catalog.yaml",
        "CATALOG_TOKEN": "...",
        "AWS_REGION": "us-east-1"
      }
    }
  }
}

Importing from OpenAPI

Hand-writing config stops being viable fast: the bundled catalog-search-service-api.json declares 49 query parameters on one operation across three sibling endpoints. import-openapi reads the spec and emits config, so the wire contract comes from the API team's own document.

# See what's in the spec
mcp-api-bridge import-openapi catalog-search-service-api.json --list

# Generate, curating the filters that reach the model
mcp-api-bridge import-openapi catalog-search-service-api.json \
  --operation productions=searchProductions \
  --include productions=startDate,endDate,city,stateCode,months,minListingPriceFloor \
  --operation performers=getPerformers \
  --include performers=activeFilter,minProductionCount \
  -o config/catalog.yaml

config/vividseats.example.yaml was scaffolded this way, then hand-edited for the parts below that no spec can supply.

It takes from the spec: base URL, method, path, parameter names, types, enums, descriptions, paging defaults, the response envelope, and the auth scheme. It strips HTML out of descriptions first — 81 of the 150 parameter descriptions in that spec contain <br/> or <b>, and those strings become the model's vocabulary.

It cannot take the semantic roles, because OpenAPI does not carry them: which parameter is the free-text query, which response field is the title, when each sort applies. Those are guessed by name and every guess is reported — to stderr as it runs, and as a comment block at the top of the generated file:

note: roles matched by name: query=query, page=page, page_size=pageSize, sortBy=sort — verify
note: first_page=1 taken from the 'page' default
TODO: base_url ...vividseats-staging.com looks non-production — confirm before deploying
TODO: sort descriptions are blank — the spec has only raw enum values

--include matters more than it looks. Every filter enters the query-understanding prompt, so importing all 45 makes the prompt expensive and gives the model a wide surface to invent against. The importer nags when an uncurated import exceeds 15 filters.

One thing the spec cannot fix. That spec declares no securitySchemes at all, so the importer writes auth: none; if a gateway fronts the API, that is invisible here. (The opaque-id problem it also surfaces is handled — see the next section.)

The importer needs no dependencies beyond PyYAML — $refs are resolved on demand with cycle guards, because real specs are cyclic (Production → Venue → Production).

Opaque ids: names in, ids out

The best filters on a real catalog are keyed by ids — regionId, performerId, venueId, categoryId. No model turns "Taylor Swift in Chicago" into performerId=9134&regionId=5 from a description, so a filter like that is dead weight in the vocabulary. Declaring how a filter's values resolve brings it back to life. Two strategies, because there are two shapes of id:

lookup — closed sets (regions, categories). The bridge fetches the table once, publishes the names as the filter's vocabulary, and translates back to the id on the way out. This is not an optimization: GET /v1/regions filters by IP and lat/long only, so holding the list is the only way to match "Chicago".

region:
  param: regionId
  type: integer
  description: Metro area the event's venue sits in.
  lookup:
    path: /v1/regions
    id_field: id
    name_field: name
    alias_fields: [listName]     # accept "Chicago, IL" too

resolve — open sets (performers, venues). No table can be preloaded, so the model supplies the name it read and the bridge searches a sibling catalog for it. Pointing this at the Algolia-backed search service is deliberate — it handles misspellings and partial names, which is exactly what resolution needs.

performer:
  param: performerId
  type: integer
  description: Artist, team, or touring show.
  resolve:
    api: performers              # another configured catalog

Either way the caller passes a name and gets told what it became:

"resolutions": {
  "performer": {"name": "Taylor Swift", "id": "9134"},
  "region":    {"name": "Chicago",      "id": "5"}
}

That readback matters because resolution is a guess where names collide — "Chicago" is a city, a band, and a musical. list_catalogs marks these filters accepts_name, listing allowed_values for closed sets and leaving it null for open ones. An id passed directly still works and skips the lookup entirely; an unrecognised name gets a did-you-mean.

config/vividseats.example.yaml wires both services together this way: catalog-service for authoritative data and the reference tables, catalog-search-service for name resolution.

Configuring a catalog

config/catalog.example.yaml is a commented walkthrough of both common shapes: a GET search API with a nested response envelope, and a POST search API with body filters and zero-indexed paging. Generated config uses the same format, so anything below applies to imported catalogs too. The pieces:

Request templating. Any value under query: or body: may contain {query}, {page}, {page_size}, or {sort}. A value that is exactly one placeholder keeps its type (size: "{page_size}" sends an integer). A placeholder with nothing to fill it drops the whole parameter — that is how optional params disappear when the caller omits them. Values with no placeholder are sent as-is, which covers static params like channel: web.

Response mapping. items_path and total_path locate the result list and the count inside whatever envelope the API uses. Paths are dotted with optional indices — data.items, media[0].url, variants[*].sku. fields maps the five normalized fields (id, title, description, url, image); attributes carries anything else through untouched. With no fields mapping at all, the raw upstream item passes through as attributes.

Auth. none, bearer, api_key (header or query param), or basic. Every variant names an environment variable; no credential is ever read from the config file.

Paging. first_page: 0 for APIs that page from zero. Callers always pass 1-based page; the bridge translates.

The Bedrock layer

understand_query constrains Claude to the QueryPlan schema via structured outputs, so the response is always parseable — no regex over prose, no retry loop for malformed JSON. The plan carries:

• keywords — search terms with filter-like phrases removed, so the keyword match is not fighting the filters
• filters — only names the catalog actually exposes
• sort — only sorts the catalog actually exposes
• expansions — domain synonyms to retry with if results are thin
• intent and ambiguities — for the trace, and for a client deciding whether to ask a clarifying question

Filters and sorts the model invents anyway are dropped before they reach the catalog, so a hallucination degrades to a slightly broader search rather than a failed request.

Defaults are anthropic.claude-opus-5 at effort: low — query understanding is a short hop in front of the real work, and low effort keeps it cheap without changing the answers on typical queries. Override per deployment:

bedrock:
  model_id: anthropic.claude-opus-5
  effort: medium
  guidance: |
    Domain shorthand the model should know about.

or with $BEDROCK_MODEL_ID / $BEDROCK_EFFORT / $BEDROCK_REGION.

Bedrock is only ever on the understand_query and smart_search paths. If it is unreachable, catalog_search, catalog_get_item, and list_catalogs keep working — and smart_search says so in its error rather than failing silently.

Tests

.venv/bin/pytest

The suite mocks the catalog HTTP layer with respx and stubs the Bedrock client, so it runs with no network and no AWS credentials. The OpenAPI tests run against the real catalog-search-service-api.json rather than a tidy fixture — its cyclic $refs, HTML descriptions, 3.1 type unions, and missing security scheme each broke a first draft of the importer.