# OpenAPI MCP demonstration on OCI Generative AI

A runnable FastMCP implementation and interactive companion to Oracle's
[OpenAPI MCP deployment tutorial](https://docs.oracle.com/en-us/iaas/Content/generative-ai/deploy-openapi-mcp-server-oci-generative-ai.htm).
The walkthrough follows the tutorial's seven steps and adds a working Python
server, Windows/PowerShell/Podman examples and live OAuth/Responses API checks.

```text
Swagger Petstore REST API -> FastMCP tools -> OCI Hosted Application
                                                ^
Browser -> local demo backend -> OCI Responses API
```

This example uses FastMCP instead of the AWS Labs implementation referenced in
the Oracle tutorial. It exposes only GET operations tagged `pet`: `findPetsByStatus`,
`findPetsByTags` and `getPetById`, alongside `/health`, `/ready` and `/mcp`.

## Demo video

[Watch the MCP Server walkthrough on YouTube](https://www.youtube.com/watch?v=2dw2_nIwn6k).

The walkthrough demonstrates the example deployment. To repeat the live calls,
configure your own OCI resources and OAuth application as described below.

## Prerequisites

* Python 3.11 and Conda; PowerShell for the supplied Windows launchers.
* Your own OCI Generative AI project, supported model and Responses API access.
* An OCI API-key profile with signing key configured outside the repository.
* For the full live flow: your own hosted MCP deployment and OCI Identity Domain
  OAuth confidential application, audience and scope.
* Docker or Podman and OCIR permissions to build and deploy your own server.

No shared hosted endpoint, OCI project or OAuth application is provided.
The demonstration does not depend on the author's deployment remaining available.

## Local setup

From the project folder:

```powershell
conda create -n mcpserver python=3.11 -y
conda activate mcpserver
python -m pip install -r requirements-dev.txt
# First setup only; preserve an existing .env.
Copy-Item .env.sample .env
```

Fill the placeholders in `.env` with your own configuration. Keep API signing
keys in your OCI configuration directory and OAuth credentials in the ignored
local configuration. Never put credentials in the browser page or recordings.

## Deploy the MCP server

Follow the [official tutorial](https://docs.oracle.com/en-us/iaas/Content/generative-ai/deploy-openapi-mcp-server-oci-generative-ai.htm)
for IAM, OCIR, OAuth, application creation and deployment. Use this project's
`Dockerfile` and `server.py` as the concrete server implementation:

```powershell
podman build --platform linux/amd64 -t openapi-mcp-server:v1 .
```

Docker is also supported. Push your image and configure your own hosted resources
as described in the tutorial. The container listens on port 8080. Its configuration
uses `API_NAME`, `API_BASE_URL` and `API_SPEC_URL`; keep the Petstore GET filter
in mind before adapting it to a different API.

The server retrieves the public Petstore OpenAPI specification at startup and
calls the public Petstore service during tool execution. It needs outbound access.

## Run the interactive walkthrough

```powershell
.\start_demo.ps1
```

Open http://127.0.0.1:8787. The local page explains the seven steps, shows code
and distinguishes recorded/replayed actions from actual service calls.
The local tutorial pane is a presentation snapshot; consult Oracle's linked
documentation for current service instructions.

The **Get OAuth token** and **Run** controls make real calls using your private
settings. The OAuth token stays in backend memory. Live results and tool-call
evidence are displayed in the browser; configuration values are represented by
placeholders. Starting the walkthrough does not build or deploy OCI resources.

Stop the local demo with `.\stop_demo.ps1`.

The three short, silent Console walkthroughs for steps 3, 4 and 5 are included
under `media/sanitized/`, with their thumbnails under `media/posters/`. They show
recorded actions, not changes to your own OCI environment. The recordings use
the Console layout from August 2026; current screens may differ. Raw recordings
and production/review files are not included.

## Command-line live check

```powershell
.\run_responses_mcp_smoke_test.ps1
```

This calls the hosted MCP server through the Responses API using your own
configuration. Hosted endpoint OAuth and Responses API signing are separate
authentication paths; a working token for one does not prove the other works.

## Main files

| File | Purpose |
|---|---|
| `server.py`, `Dockerfile` | Remote OpenAPI-to-MCP server and image |
| `demo_app.py`, `demo_runtime.py` | Local walkthrough backend, OAuth and live calls |
| `static/` | Walkthrough page, code views and tutorial snapshot |
| `media/` | Three final presentation clips and their posters |
| `responses_mcp_smoke_test.py` | Explicit live Responses API/MCP check |
| `.env.sample` | Reader-owned configuration template |

## License and sources

The author's code and demonstration additions use the [MIT License](LICENSE).
The Oracle-derived tutorial snapshot retains its Oracle copyright and is not
relicensed under MIT. Oracle documentation remains the authoritative source.
FastMCP, the OCI/OpenAI libraries and Swagger Petstore retain their own licenses.