OpenAPI MCP demonstration on OCI Generative AI

A runnable FastMCP implementation and interactive companion to Oracle's OpenAPI MCP deployment tutorial. The walkthrough follows the tutorial's seven steps and adds a working Python server, Windows/PowerShell/Podman examples and live OAuth/Responses API checks.

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.

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

Related MCP server: test-12-mcp

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:

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 for IAM, OCIR, OAuth, application creation and deployment. Use this project's Dockerfile and server.py as the concrete server implementation:

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

.\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

.\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

License and sources

The author's code and demonstration additions use the MIT 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.