Ghibli REST → MCP POC

Landing page

The root URL contains a Three.js atmospheric landing page with connection instructions, the tool catalog, live `/health` status, copy-to-clipboard controls, acknowledgements, and the WebMCP browser bridge.

The landing page assumes a local video exists at `public/media/background.mp4`. It is served as `/media/background.mp4` and fills the entire viewport using `object-fit: cover`; a lightweight Three.js rain overlay and the site UI render above it. The MP4 is intentionally not included in this archive.

Static landing assets live in:

public/index.html
public/styles.css
public/app.js

The Three.js module is loaded client-side from jsDelivr, so no frontend build step is required and the Vercel Framework Preset can remain Other.

A small proof of concept that exposes the public Studio Ghibli REST API as MCP tools.

It demonstrates two different layers:

1. Mechanical conversion — GET operations are discovered from the bundled focused Swagger 2.0 document and registered as MCP tools.

2. Semantic MCP design — `search_films` is a hand-designed tool optimized for an agent, rather than mirroring one HTTP endpoint.

The upstream API is `https://ghibliapi.vercel.app` and requires no authentication.

Generated tools

The bundled Swagger specification produces these tools automatically:

• `list_films`
• `get_film`
• `list_people`
• `get_person`
• `list_locations`
• `get_location`
• `list_species`
• `get_species`
• `list_vehicles`
• `get_vehicle`

The POC then adds:

• `search_films`

`search_films` accepts text, director, producer, year range, minimum Rotten Tomatoes score, and result limit. It fetches the small film catalog and applies the semantic filtering in the MCP adapter.

Requirements

• Node.js 22.7.5+
• npm or pnpm

The MCP SDK v2 is used, which implements the MCP 2026-07-28 protocol and can also serve stateless 2025-era clients through the SDK's compatibility path.

Run the complete landing page locally

Keep `public/media/background.mp4` in place, then run the Vercel development runtime:

pnpm install
pnpm dlx vercel dev

Open `http://localhost:3000/`. The background video should be requested directly from `/media/background.mp4`.

Run the standalone MCP server with pnpm

pnpm install
pnpm start

`pnpm start` serves the standalone MCP/health HTTP server only; use `vercel dev` when testing the landing page.

Or with npm:

npm install
npm start

The Streamable HTTP endpoint is:

http://127.0.0.1:3000/mcp

Health endpoint:

curl http://127.0.0.1:3000/health

Run with Docker Compose

docker compose up --build

Then connect an MCP client to:

http://127.0.0.1:3000/mcp

MCP Inspector

Start the MCP server first, then run:

npx @modelcontextprotocol/inspector

In the Inspector choose Streamable HTTP and use:

http://127.0.0.1:3000/mcp

A ready-made `mcp.json` is included too.

stdio mode

For a client that launches MCP servers as child processes:

pnpm stdio

Equivalent client configuration:

{
  "mcpServers": {
    "ghibli": {
      "command": "node",
      "args": ["/absolute/path/to/ghibli-mcp-poc/src/stdio.js"]
    }
  }
}

Example agent requests

These exercise both the generated and semantic surfaces:

List Studio Ghibli films directed by Hayao Miyazaki.

A capable client should prefer `search_films({ director: "Hayao Miyazaki" })`.

Show me Studio Ghibli films from 1990 through 2000 with an RT score of at least 90.

Expected tool call shape:

{
  "year_from": 1990,
  "year_to": 2000,
  "min_rt_score": 90
}

And direct REST-shaped access remains available:

Get film 58611129-2dbc-4a81-a72f-77ddfc1b1b49.

which maps to `get_film({ id: "58611129-2dbc-4a81-a72f-77ddfc1b1b49" })`.

Architecture

MCP client / agent
                                |
                     Streamable HTTP or stdio
                                |
                         +------v-------+
                         |  MCP server  |
                         +------+-------+
                                |
              +-----------------+------------------+
              |                                    |
      generated Swagger tools                 semantic tools
 list_films/get_film/...                     search_films
              |                                    |
              +-----------------+------------------+
                                |
                         GhibliClient
                                |
                                | HTTPS JSON
                                v
                  https://ghibliapi.vercel.app

Why DAB is not used in this POC

Microsoft Data API Builder is a strong database → REST/GraphQL/MCP bridge. This POC starts from an already existing third-party REST API. DAB does not act as a generic REST/OpenAPI → MCP proxy, so inserting DAB here would add a database and an unnecessary replication step.

For this problem the thin MCP adapter is the correct comparison point.

If the source instead were SQL Server tables/views/stored procedures, DAB would be worth testing as the MCP layer itself.

What this POC proves

The mechanical part is small: read the API contract, turn parameters into MCP input schemas, and dispatch the tool call to the HTTP endpoint.

The important design work begins after that. A mechanically generated `list_films` tool is valid, but `search_films` is much better for an LLM because it directly captures user intent and avoids making the model fetch a large collection and reason over it itself.

That suggests a production architecture with two layers:

OpenAPI-generated MCP tools
          +
curated semantic MCP tools

The generated layer gives broad coverage cheaply; the curated layer contains the operations that deserve high tool-selection reliability, stronger schemas, authorization rules, aggregation, or multi-request workflows.

POC limitations

• Read-only by design because the upstream Ghibli API is read-only.
• Only GET Swagger operations are generated.
• Swagger `$ref` parameter definitions and advanced OpenAPI schema composition are not implemented. The bundled contract is a focused JSON copy of the endpoint/parameter metadata needed by the POC, based on the upstream Swagger documentation.
• No authentication because the upstream API has none.
• The HTTP POC intentionally does not add an OAuth resource server. Add authentication and explicit Host/Origin policy before exposing it beyond a trusted test environment.
• `search_films` filters locally because the catalog is tiny. For a real API, search/filtering should normally be delegated to the source service.

Deploy to Vercel

This repository contains a Vercel-native Function entry point in `api/mcp.js`.

The normal `src/http.js` entry point is still available for Docker, a VM, Cloud Run,

or any other host where a long-running Node process is appropriate.

Why a separate Vercel entry point is required

`src/http.js` calls Node's `httpServer.listen(...)`. That is appropriate for a

container or VM, but Vercel Functions are request handlers rather than persistent

HTTP listeners. `api/mcp.js` therefore exports the MCP Web-standard handler instead

of opening a port.

Deploy

From the project root:

pnpm install
npx vercel

For production:

npx vercel --prod

Or push the repository to GitHub and import it into Vercel. No build command is

required. Vercel should detect the functions under `api/`.

The public endpoints are then:

https://YOUR-PROJECT.vercel.app/
https://YOUR-PROJECT.vercel.app/health
https://YOUR-PROJECT.vercel.app/mcp

`/` is just a small status page. `/health` is suitable for browser/curl checks.

`/mcp` is the Streamable HTTP MCP endpoint and should normally be opened by an MCP

client rather than by browser navigation.

Test the deployment

Health:

curl https://YOUR-PROJECT.vercel.app/health

Expected shape:

{
  "ok": true,
  "service": "ghibli-rest-mcp-poc",
  "transport": "streamable-http",
  "mcp": "/mcp"
}

Then open MCP Inspector and connect using Streamable HTTP to:

https://YOUR-PROJECT.vercel.app/mcp

Vercel routing

`vercel.json` rewrites the friendly public paths to the generated Functions:

/mcp    -> /api/mcp
/health -> /api/health

The MCP function also explicitly includes `spec/**` in its bundle because the POC

loads the focused Swagger document from the filesystem at runtime.

WebMCP browser bridge

This version also exposes the same backend MCP tool surface through the experimental

WebMCP browser API.

The important design choice is that the browser does not contain a second hard-coded

copy of the Ghibli tools. `public/webmcp.js` dynamically mirrors the backend server:

browser agent
    |
    v
document.modelContext
    |
    | registerTool(...)
    v
public/webmcp.js
    |
    +-- POST /mcp  tools/list   -> discover current tool schemas
    |
    +-- POST /mcp  tools/call   -> execute the same backend tool

This means adding or changing a backend MCP tool automatically changes the WebMCP surface

after the page reloads.

Local WebMCP testing in Chrome

WebMCP is experimental. For local development with a supported Chrome build:

1. Open `chrome://flags/#enable-webmcp-testing`.

2. Set WebMCP testing to Enabled.

3. Relaunch Chrome.

4. Start the project with:

pnpm install
pnpm dlx vercel dev

5. Open `http://localhost:3000/`.

The landing page WebMCP card should change to active and report the number of mirrored

tools.

You can also inspect the tools directly from DevTools:

const tools = await document.modelContext.getTools()
tools.map(tool => tool.name)

And manually execute the semantic film search:

const tools = await document.modelContext.getTools()
const search = tools.find(tool => tool.name === 'search_films')

await document.modelContext.executeTool(
  search,
  JSON.stringify({
    director: 'Hayao Miyazaki',
    min_rt_score: 90,
    limit: 5
  })
)

For bridge diagnostics independent of WebMCP browser support:

await window.ghibliWebMcp.listBackendTools()
await window.ghibliWebMcp.call('search_films', {
  director: 'Hayao Miyazaki',
  min_rt_score: 90,
  limit: 5
})

Production origin trial

As of August 2026, WebMCP is still experimental. Chrome exposes it through an origin trial

(starting with Chrome 149), Edge has its own origin trial, and Brave has experimental Leo

integration. A production deployment therefore needs the applicable browser trial enabled.

For Chrome, register the production origin and add the issued token near the top of

`public/index.html`:

// Code block

The project already sends these headers on Vercel:

Permissions-Policy: tools=(self)
Origin-Agent-Cluster: ?1

Feature detection is intentional: browsers without WebMCP keep the normal landing page and

the backend `/mcp` endpoint continues to work normally.

Illustrated credit cards

The acknowledgement cards for Hayao Miyazaki, Isao Takahata, and Toshio Suzuki use locally bundled illustrated portrait backgrounds under `public/media/credits/`. The landing page also links the public Wikimedia Commons portrait references used for visual research.