Oracle Cloud Infrastructure Documentation

Deploy an OpenAPI MCP Server with OCI Generative AI

Deploy an OpenAPI MCP server as an OCI Generative AI application. Then, create and activate a deployment, configure OAuth inbound authentication, and use the hosted MCP server from the OCI Responses API.

Overview

Important

This tutorial uses the AWS Labs OpenAPI MCP Server as an example implementation of an OpenAPI-backed MCP server. The AWS Labs project dynamically creates MCP tools from OpenAPI specifications. In this tutorial, you adapt that use case for OCI Generative AI by deploying a containerized OpenAPI MCP server as an application, protecting the hosted endpoint with OAuth, and using the hosted MCP server from the OCI Responses API. If you use the AWS Labs implementation, follow its license and attribution requirements and ensure that the container exposes a remote Streamable HTTP endpoint on 0.0.0.0:8080.

An OpenAPI MCP server is a service that turns an OpenAPI-described REST API into tools that an AI agent can call. OpenAPI describes the REST API operations, and Model Context Protocol (MCP) exposes those operations as callable tools.

In this tutorial, you deploy an OpenAPI MCP server as an OCI Generative AI application. The MCP server uses an OpenAPI specification, such as the Swagger Petstore API, to expose API operations as MCP tools. Then, you create and activate a deployment, protect the hosted endpoint with OAuth, and use the hosted MCP server from the OCI Responses API.

OpenAPI REST API -> MCP server tools -> OCI Generative AI application -> Responses API MCP Calling

OCI Generative AI provides applications and deployments for running containerized agent workloads.

  • An application defines the managed runtime configuration, including scaling, storage, networking, and authentication.
  • A deployment is a versioned release of an application based on a container image and image tag.
  • An application can have several deployments, but only one deployment can be active at a time.
  • The active deployment serves requests through the application endpoint.

Key tasks:

  • Prepare an OpenAPI MCP server container image.
  • Push the image to Oracle Cloud Infrastructure Registry.
  • Configure OAuth inbound authentication with an OCI identity domain.
  • Create an OCI Generative AI application.
  • Create and activate a deployment.
  • Use the hosted MCP server with OCI Responses API MCP Calling.

For background, see Hosted Applications and Deployments and Overview of Deploying Agents in OCI Generative AI.

Before You Begin

Complete the relevant setup in the QuickStart. At minimum, you need access to OCI Generative AI resources, a configured Responses API authentication method, the OCI Responses API endpoint, and a supported model in US Midwest (Chicago).

This tutorial uses the following values:

  • Console region name: US Midwest (Chicago)
  • Region identifier: us-chicago-1
  • Hosted-application endpoint: https://application.generativeai.us-chicago-1.oci.oraclecloud.com/20251112/hostedApplications/

You also need:

  • Permission to create and manage OCI Generative AI applications and deployments. Your user group needs manage access to generative-ai-hosted-application and generativeaihosteddeployment, or to generative-ai-family. See QuickStart Permissions for Users.
  • Runtime permissions for the hosted application to retrieve and validate the container image. Configure a dynamic group for OCI Generative AI applications and deployments, and grant it permission to read the OCIR repository and Vulnerability Scanning results. See For OCI Generative AI Applications.
  • Permission to push container images to the OCIR repository. To push to an existing repository, you need REPOSITORY_READ and REPOSITORY_UPDATE. If you create the repository, you also need REPOSITORY_CREATE. See Policies to Control Repository Access.
  • Docker installed locally and an OCI auth token for signing in to OCIR. See Preparing for Container Registry.
  • The AWS Labs OpenAPI MCP Server source configured to use the Swagger Petstore API. This tutorial uses https://petstore3.swagger.io/api/v3 as the API URL and https://petstore3.swagger.io/api/v3/openapi.json as the OpenAPI specification URL. The container must expose MCP over Streamable HTTP.
  • An OCIR repository in US Midwest (Chicago) for the container image. If you don't have one, see Creating a Repository.
  • An active OCI identity domain in which you can create or manage a confidential application. Every tenancy includes a Default identity domain. You can use the Default identity domain or create another domain. See Managing Identity Domains and Step 1. Create an Identity Domain (Optional).
Important

Inbound authentication controls client access to the hosted application endpoint. This tutorial uses identity domain bearer token authentication with an OCI IAM identity domain. For an overview of authentication methods for hosted applications, see Authentication. Responses API authentication is separate. The QuickStart authentication choices apply to calls to the OCI Responses API, not to inbound access for the hosted application endpoint.
Note

If the OpenAPI MCP server implementation that you use runs as a local stdio MCP server by default, use a container image or wrapper that exposes the MCP server as a remote Streamable HTTP endpoint on 0.0.0.0:8080.
Note

Outbound authentication controls how the deployed application accesses other OCI resources. Use IAM policies and resource principal access only if the deployed workload needs access to OCI resources.

1. Prepare the OpenAPI MCP Server Container

Prepare a container image that OCI Generative AI can run as an application deployment.

This tutorial uses the AWS Labs OpenAPI MCP Server with the Swagger Petstore API. Configure the server with the following values:

  • API name: petstore
  • API URL: https://petstore3.swagger.io/api/v3
  • OpenAPI specification URL: https://petstore3.swagger.io/api/v3/openapi.json
Important

The AWS Labs implementation uses stdio transport by default. Use a container image or wrapper that exposes the server through a remote Streamable HTTP endpoint on 0.0.0.0:8080. A stdio-only server can't be used with this tutorial.
  1. Set up a container that exposes the MCP server over Streamable HTTP and meets the hosted application requirements.
    • Listens on host 0.0.0.0.
    • Listens on port 8080.
    • Has a readiness endpoint at /ready.
    • Has a liveness endpoint at /health.
    • Supports Streamable HTTP.
    • Returns Content-Type: application/json for JSON responses.
    • Returns Content-Type: text/event-stream for streaming responses when appropriate.
    • Writes temporary files only to /tmp.
    Note

    Some OpenAPI MCP server implementations are configured for stdio transport by default. A stdio MCP server isn't enough for this tutorial unless the container also provides the remote Streamable HTTP endpoint that OCI Responses API can call.
    Important

    Don't define reserved platform environment variables such as PORT, K_SERVICE, K_CONFIGURATION, K_REVISION, OCI_RESOURCE_PRINCIPAL_VERSION, OCI_RESOURCE_PRINCIPAL_PRIVATE_PEM, OCI_RESOURCE_PRINCIPAL_RPST, or variables matching KUBERNETES_*.
  2. Build the image for linux/amd64. 
    docker buildx build --platform linux/amd64 -t openapi-mcp-server:v1 --load .

    The image openapi-mcp-server:v1 exists locally.

2. Push the Image to OCIR

Make the MCP server image available to OCI Generative AI.

Before pushing the image, create or select an OCIR repository and ensure that you have permission to push images to it. You also need an OCI auth token. See Creating a Repository and Pushing Images Using the Docker CLI.

  1. Sign in to OCIR. 
    docker login us-chicago-1.ocir.io -u '<tenancy_namespace>/<username>'

    When prompted for a password, enter your OCI auth token.

  2. Tag the image. 
    docker tag openapi-mcp-server:v1 us-chicago-1.ocir.io/<tenancy_namespace>/<repository>/openapi-mcp-server:v1
  3. Push the image. 
    docker push us-chicago-1.ocir.io/<tenancy_namespace>/<repository>/openapi-mcp-server:v1

    The image is available in OCIR.

3. Configure OAuth Inbound Authentication

Create or configure an identity-domain confidential application that issues access tokens accepted by the hosted application.

An identity domain manages users, applications, and OAuth configuration. This tutorial uses a confidential application as both an OAuth resource server and client. You can use the tenancy's Default identity domain or another active identity domain. See Managing Identity Domains and Adding a Confidential Application.

  1. In the OCI Console, open the navigation menu  and select Identity & Security.
  2. Under Identity, select Domains.
  3. Open an existing identity domain, or create a domain.
  4. Select Integrated applications.
  5. Select Add application.
  6. Select Confidential Application, and then select Launch workflow.
  7. Enter a name and description, and then select Submit.
  8. Open the application and select OAuth configuration.
  9. Select Edit OAuth configuration.
  10. Enable Configure this application as a resource server now.
  11. For Primary audience, enter the Chicago hosted-application data-plane URL. 
    https://application.generativeai.us-chicago-1.oci.oraclecloud.com/20251112/hostedApplications/
  12. Add the required OAuth scope. For this tutorial, use invoke. 
    invoke
  13. Enable Configure this application as a client now.
  14. For the grant type, select Client credentials.
  15. Select Submit.
  16. From the Actions menu, select Activate.
  17. Record the Domain URL, Client ID, Client secret, Primary audience, and Scope.

    The confidential application is active and can issue OAuth access tokens. The Primary audience value must match the value that you enter later in the OCI Generative AI application's Audience field.

4. Create an OCI Generative AI Application

Define runtime settings for the MCP server.

For more information, see Creating an Application.

  1. In the OCI Console, select US Midwest (Chicago).
  2. Open the navigation menu  and select Analytics & AI.
  3. Under AI Services, select Generative AI.
  4. Select Applications.
  5. Select Create application.
  6. In Basic Information, enter the application name, description, and compartment.
  7. In Scaling, use minimum replicas 1 and maximum replicas 3.
  8. In Storage (Optional), don't enable managed storage unless the MCP server requires it.
  9. In Environment Variables, add any variables required by the MCP server.

    For a Petstore-backed OpenAPI MCP server, use the following variables:

    API_NAME=petstore
API_BASE_URL=https://petstore3.swagger.io/api/v3
API_SPEC_URL=https://petstore3.swagger.io/api/v3/openapi.json

    If the backing OpenAPI API requires authentication, configure the MCP server with the authentication variables that the server implementation supports, such as variables for bearer token, API key, or basic authentication. This authentication is separate from the OAuth token that clients use to call the hosted application endpoint.

    To limit which operations the MCP server exposes as tools, configure the server-side include or exclude settings supported by the MCP server implementation. For example, a Petstore-backed server might expose only operations tagged for pets.

  10. In Networking (Optional), use default service-managed networking and a public endpoint.
  11. In Authentication, select OCI Identity Domain.
  12. Select Choose an existing identity domain or Paste an identity domain URL.
  13. For Scope, enter invoke. 
    invoke
  14. For Audience, enter the same value that you configured as the identity-domain application's Primary audience. 
    https://application.generativeai.us-chicago-1.oci.oraclecloud.com/20251112/hostedApplications/
  15. In Review and Create, review the settings.
  16. Select Create.

    OCI Generative AI creates the application.

5. Create and Activate a Deployment

Release the OCIR image as the active version of the application.

For more information, see Hosted Deployments.

  1. On the Applications list page, select the application that you created.
  2. On the application details page, select the Deployments tab.
  3. Select Create deployment.
  4. For Repository compartment, select the compartment that contains the OCIR repository.
  5. For Repository, select the repository.
  6. For Version tag, select v1.
  7. Enable Deploy and activate.
  8. Select Create deployment.
  9. Wait until the deployment status is Active.

    The deployment is active and serves requests through the application endpoint.

6. Get an OAuth Access Token

Generate the token required to call the hosted application endpoint.

Set the OAuth values and generate an access token. 
export IDCS_DOMAIN_URL="https://<your-domain>.identity.oraclecloud.com:443"
export IDCS_CLIENT_ID="<client-id>"
export IDCS_CLIENT_SECRET="<client-secret>"
export IDCS_SCOPE="https://application.generativeai.us-chicago-1.oci.oraclecloud.com/20251112/hostedApplications/invoke"

export HOSTED_APP_ACCESS_TOKEN=$(curl -s -X POST "${IDCS_DOMAIN_URL}/oauth2/v1/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=${IDCS_CLIENT_ID}" \
  -d "client_secret=${IDCS_CLIENT_SECRET}" \
  -d "scope=${IDCS_SCOPE}" | jq -r .access_token)

HOSTED_APP_ACCESS_TOKEN contains a raw OAuth access token.

7. Use the Hosted MCP Server from the Responses API

Verify that OCI Generative AI can use tools exposed by the hosted MCP server.

Review the QuickStart Tools section. Under Add OpenAI Tools to OCI Responses API, expand MCP Calling.

MCP tools are executable functions or capabilities exposed by a remote MCP server. During a Responses API request, OCI Generative AI can communicate directly with the remote MCP server. MCP Calling supports Streamable HTTP. SSE is deprecated and unsupported.

Use allowed_tools when the application needs only a subset of tools exposed by the MCP server. Restricting tools can reduce unnecessary cost and latency. Server-side filtering controls what the MCP server exposes, and allowed_tools controls which exposed tools the Responses API request can use.

  1. Set the hosted MCP server URL. 
    export MCP_SERVER_URL="https://application.generativeai.us-chicago-1.oci.oraclecloud.com/20251112/hostedApplications/<application_ocid>/actions/invoke/mcp"
  2. Define the MCP tool in the Responses API request. 
    response_stream = client.responses.create(
    model="<supported-model-id>",
    tools=[
        {
            "type": "mcp",
            "server_label": "petstore",
            "server_description": "OpenAPI MCP server for the Petstore API.",
            "server_url": MCP_SERVER_URL,
            "authorization": HOSTED_APP_ACCESS_TOKEN,
            "allowed_tools": ["getPetById"],
            "require_approval": "never",
        }
    ],
    input="Use the Petstore MCP server to get pet 3.",
    stream=True,
    store=False,
)
    Important

    Pass only the raw token value in authorization. Don't include the Bearer prefix. Use a TLS-encrypted MCP server endpoint.
  3. Run the Responses API request with the hosted MCP server configured as a tool.

    The Responses API request calls the hosted MCP server tool and returns a response.

What You've Accomplished

You successfully:

  • Prepared an OpenAPI MCP server container image.
  • Pushed the image to OCIR.
  • Configured OAuth inbound authentication.
  • Created an OCI Generative AI application.
  • Created and activated a deployment.
  • Used the hosted MCP server from an OCI Responses API request.