Skip to main content

Oracle Integration MCP Gateway: Create, Activate, Configure OAuth and Test Access

Calculating read time…

Creating an Oracle Integration 3 (OIC Gen3) MCP Gateway is not simply a matter of grouping servers behind one URL. You must understand the objects that the gateway depends on, decide how callers will be authorized, attach the appropriate policies, complete activation, and verify that the resulting endpoint permits the intended operations while rejecting unauthorized requests.

Consider a fictional procurement assistant that needs to retrieve purchase-order status from an existing OIC integration. The integration already works, but exposing it directly to an AI client is not the complete enterprise design. The organization also wants to control which tools are discoverable, validate requests before they reach the integration, protect the downstream connection, and distinguish a caller who can discover tools from one who is permitted to invoke them.

Oracle Integration MCP Gateway provides a managed place to assemble those controls around selected Model Context Protocol (MCP) servers. This tutorial follows the dependency order from the existing server and policies through gateway creation, activation, OAuth authorization, endpoint discovery, positive and negative tests, and authorization-mode changes.

Analogy — the corporate service desk

Think of an MCP server as a service desk that offers specific operations. The gateway is a controlled entrance to selected service desks. The security policies determine which tools are exposed or how traffic is handled, while business policies evaluate defined conditions before applicable requests are forwarded. The identity system establishes who is making the request. The gateway does not replace the permissions enforced by the underlying integration or target application.

📑 In This Post

  1. Understand gateway objects and dependencies
  2. Verify prerequisite and access gates
  3. Register a managed MCP server and prepare its policies
  4. Create the gateway and assign servers and policies
  5. Choose authorization mode and activate the gateway
  6. Retrieve the URL and test access
  7. Change authorization mode and retest
  8. Common mistakes and targeted corrections
  9. Enterprise rollout and acceptance evidence
  10. Frequently asked questions
  11. References and further reading
  12. Summary

01
Understand MCP Gateway Project Objects and Their Dependencies

Before opening the gateway configuration page, establish what each object represents. MCP, or Model Context Protocol, defines a way for an MCP client to discover and invoke tools made available by an MCP server. An MCP tool is an operation with a name, description, and input contract. It is not automatically a new integration, a new API, or a separate business process.

Oracle Integration can expose eligible integrations through a project's MCP server. The gateway can then manage selected OIC or approved third-party MCP servers through a governed entry point. The project MCP server and the gateway are different objects with different responsibilities.

Object Responsibility Dependency or evidence
Source OIC projectContains integrations registered as agentic AI tools and exposes them through the project's MCP server.The project, eligible integrations, tool registrations, active states, and MCP server URL must exist.
Managed MCP server registrationStores the gateway's connection information for a selected MCP server.A verified server endpoint and the appropriate downstream authentication configuration.
Security policyControls a documented aspect of MCP tool exposure or traffic handling.A tool filter can restrict discoverable tools. PII detection is a separate, optional control with additional dependencies.
Business policyEvaluates configured business conditions for a selected tool before its request is sent to the server.The actual tool input schema and a reviewed, validated rule body.
MCP GatewayGroups selected servers and the policies assigned to them, then provides the managed gateway route after activation.Server registrations, usable policies, gateway configuration, and a completed activation workflow.
Confidential client applicationRepresents the OAuth client that obtains a token for a specified resource and permission boundary.The correct grant, resource audience, scopes, application state, and any required roles.

These objects do not all perform the same kind of check. The gateway authorization mode governs the inbound caller's access. A server registration's security configuration governs how the gateway connects to the downstream server. Tool filters affect exposure and discovery, while business policies evaluate configured request conditions. The integration and target application remain responsible for their own business validation and permissions.

Engineering principle

Creating a gateway does not automatically configure downstream authentication, authorize a client application, or prove that every tool is safe to invoke. Each boundary requires separate configuration and evidence.

Project placement: This article uses a source project named PROCUREMENT_TOOLS and a separate governance project named PROCUREMENT_GATEWAY_GOV. This separation is a recommended organizational choice for the example, not a claim that Oracle requires two projects. A single project arrangement may be suitable where it matches the documented design and governance model.

🎯 Use this when...

You need to decide what must exist before creating a gateway, or you need to troubleshoot a gateway that exists but cannot connect to its MCP server or discover the expected tools.

02
Verify Prerequisite and Access Gates

The first task is not to click Add. It is to confirm that the intended instance, edition, identity domain, project, endpoint, and client identities are ready. This is particularly important for a corporate environment because the presence of a menu item does not independently prove that the associated feature is licensed or that every dependency is available.

Gate What to establish Do not continue until...
Release and entitlementConfirm the actual OIC release, edition, region, and realm.MCP Gateway is supported and licensed for the intended instance.
OIC project accessConfirm permission to work with the selected project's MCP Gateway objects and prerequisite configurations.You can view the correct project and have authority to make the intended changes.
Source MCP serverConfirm the project's MCP server is enabled and its required tool registrations are active and discoverable.The expected MCP endpoint and real tool identifiers are available.
Server connection identityObtain the required confidential application configuration for the downstream connection.The selected security policy, actual scope, resource audience, credential, and necessary role are understood.
Gateway caller identityDetermine whether inbound authorization will be dedicated gateway authorization or OIC integration authorization.The intended client application and permission boundary are identified.
Policy dependenciesConfirm the tool filter and business policy objects to assign, along with any optional security policy dependencies.Each policy has a defined scope and has been checked against the actual tool schema.

Safety Check — release and entitlement

Risk: The team builds a design around a feature that is not usable under the target instance's actual release or licence.

Control: Confirm release, edition, realm, feature availability, privileges, and the required identity-domain access before configuration.

Enforcement owner: OIC administrator, cloud tenancy administrator, and the organization's licence owner, according to their responsibilities.

Verification: Record the relevant instance and entitlement evidence without exposing secrets.

Remaining risk: A successful design-time check cannot prove that every downstream service, permission, or runtime dependency will be available.

Initial state for the worked example: An administrator has already registered and activated two harmless, read-oriented integration tools, enabled MCP for the source project, and confirmed that their input schemas can be discovered. One retrieves synthetic purchase-order status; the other reads synthetic supplier information. Their names in the following examples are illustrative and must be replaced by identifiers actually returned by the source server.

An OIC integration registered as an agentic AI tool must satisfy the documented requirements, including project membership, active status, a REST Adapter trigger connection as its first connection, OAuth authentication for the trigger, and a JSON payload. Review the official project MCP FAQ and tool-registration guide if those prerequisites are not already satisfied.

🎯 Use this when...

You are starting a lab, approving a corporate pilot, or troubleshooting a feature that is missing or unavailable in the intended OIC instance.

03
Register a Managed MCP Server and Prepare Its Policies

A gateway needs a managed server definition that tells Oracle Integration how to reach the downstream MCP server. For this example, the downstream server is the MCP server of the existing procurement tools project. This is the gateway-to-server network and identity boundary in the walkthrough; the client-to-gateway boundary is configured separately.

The important distinction is between two endpoints. The project MCP server URL is the endpoint the gateway uses to reach that server. The gateway URL is the endpoint the final client will use later. Do not enter the eventual gateway URL into the downstream server registration.

Analogy — two separate doors

The source MCP server has its own entrance and authentication requirements. The gateway has another entrance for its callers. Giving a client permission to enter the gateway does not automatically provide the gateway with valid credentials for the downstream server, and the gateway's downstream credentials are not automatically the caller's credentials.

Task A — Retrieve the existing project MCP server URL

Start here: Oracle Integration 3, in the source project PROCUREMENT_TOOLS. The project must already contain the intended registered tools and have MCP enabled.

Navigation: Projects > PROCUREMENT_TOOLS > project-details edit icon

Steps

  1. In the OIC navigation pane, select Projects.
  2. Select PROCUREMENT_TOOLS. Confirm you have selected the source project rather than the governance project.
  3. In the upper-right area of the project page, select the edit icon to display the project details.
  4. Locate the displayed MCP server URL. Copy the actual endpoint into your approved configuration record. Do not substitute an invented URL or the URL of a different project.
  5. Confirm that the endpoint belongs to the expected service instance and source project before continuing.

Expected result: You have the actual source MCP server endpoint. Its value is tenant-specific; this article deliberately does not invent it.

If this fails: Stop if the MCP server URL is absent. Verify project-level MCP enablement, the active registered tools, the correct project, and the instance release before attempting gateway registration. Oracle's Enable MCP for the Project and Get the URL for the MCP Server instructions document this source endpoint.

Next, create the managed server entry in the governance project. The example assumes that a suitable downstream confidential client application already exists and has been assigned the permissions needed to call the source project's MCP server. If it does not exist, obtain the required identity-domain administrator assistance before continuing.

Task B — Add and test the managed MCP server

Start here: Oracle Integration 3, in the governance project PROCUREMENT_GATEWAY_GOV. Task A must have produced a verified source endpoint. A downstream confidential application and the necessary permissions must already be available.

Navigation: Projects > PROCUREMENT_GATEWAY_GOV > left toolbar MCP Gateway > MCP servers > Add

Steps

  1. Select Projects in the OIC navigation pane, then select PROCUREMENT_GATEWAY_GOV.
  2. Select MCP Gateway in the project's left toolbar.
  3. In the MCP servers section, select Add. The Add MCP server panel opens.
  4. Enter the server metadata shown in the field table below. Treat the name and description as human-readable labels; Oracle Integration generates the identifier from the name.
  5. Select Add. The MCP connection page opens. The server registration object now exists, but the connection has not yet been verified.
  6. Enter the actual source URL in MCP Endpoint. Choose OAuth 2.0 Client Credentials under Security for this example. This authenticates the gateway's connection to the source MCP server using the configured downstream client, rather than reusing the eventual inbound gateway token.
  7. Complete the applicable downstream OAuth fields in the same connection page. Use the exact identity-domain token URI, confidential application details, and scope from the approved configuration for the source project. Do not construct a resource audience or scope from guesswork.
  8. Select Test. Stop if the connection test fails. Correct the endpoint, authentication choice, token URI, scope, permissions, or client configuration before moving forward.
  9. After a successful connection test, select Save to save the MCP server connection information.

Expected result: The server connection has been tested and saved. The configured connection and the discovered tools should be visible in the relevant server details. A test result alone does not establish that final gateway callers are authorized.

If this fails: Do not continue to gateway activation with an untested server connection. Check the actual source MCP URL, the identity application's state and permissions, the OAuth token URI, the requested scope, and the chosen security policy. Record the supplied error without capturing a client secret or access token.

Registration field Purpose and value source Verification
NameHuman-readable server registration name. Example: Procurement Project MCP Server.Review the name before adding the object because the identifier is generated from it.
IdentifierGenerated from the name by Oracle Integration.Use the actual displayed identifier; do not assume that it is freely editable later.
DescriptionDescribes the type of tools exposed by the server.Keep the description consistent with the real tools and their intended use.
MCP EndpointThe actual source MCP server URL retrieved in Task A.Check the instance and project segment against the intended source.
Access Token URIThe token endpoint for the downstream OAuth application, sourced from the identity-domain configuration.Confirm that the host is the intended identity-domain service instance.
Client ID and Client SecretIdentify and authenticate the downstream OAuth client. Obtain them from the approved confidential application.Never record the secret in this tutorial, screenshots, source control, or troubleshooting notes.
Scope and client authenticationDescribe the permitted downstream access and how the client authenticates to the token endpoint. Obtain the exact values from the configured application and Oracle's applicable guidance.Check that the configured token client is authorized for the scope being requested.

For a client-credentials connection, the downstream application requires the appropriate OAuth setup and permissions for the source resource. Oracle's client-application prerequisite guide describes the confidential client workflow and the ServiceInvoker role used when calling OIC integration tools. The identity used here is the gateway's configured downstream service identity unless a supported user-assertion arrangement is deliberately configured. For this service-client example, requests from different employees can reach the target as the same application identity. Record-level permissions must follow that design; an employee name supplied as a tool argument is not authenticated identity. Do not assume dedicated gateway scopes provide per-tool or per-record permissions.

Oracle Integration also documents OAuth using JWT User Assertion and No Security Policy as registration options. JWT user assertion is relevant when the required supported identity-propagation design is configured. No Security Policy adds no application-level gateway credential for the downstream call and is not a substitute for an approved authentication design. HTTPS server-certificate verification is a separate check and must not be disabled to bypass a connection failure.

Next, create the two policy objects the example uses. The tool filter limits discovery to the intended read-oriented tool. The business policy checks a condition for requests directed to that tool. These controls serve different purposes and should be tested independently.

Task C — Create a tool filter for controlled discovery

Start here: Oracle Integration 3, in PROCUREMENT_GATEWAY_GOV. Task B must have saved the managed server connection and made the real server tools available for selection.

Navigation: Projects > PROCUREMENT_GATEWAY_GOV > MCP Gateway > Security policies > Add

Steps

  1. Open the governance project and select MCP Gateway in the left toolbar.
  2. In the Security policies section, select Add.
  3. Select Tool filter. The tool-filter creation panel opens.
  4. Enter a descriptive name such as Procurement Read Tool Filter. Oracle Integration generates the identifier from the name; provide a description if useful.
  5. Select Add. The Tool filter page opens.
  6. From MCP server, select the actual registered procurement server.
  7. Select Include Tools to display the available tools. Select the actual read-oriented purchase-order-status tool from that list. The tutorial's example name is GET_PURCHASE_ORDER_STATUS; do not type that name as a substitute for selecting your actual tool.
  8. Select Save.

Expected result: The saved filter identifies the server and the tools that should be discoverable through this filter.

If this fails: If the server or tool is missing, return to the server registration and check the endpoint connection test, Save result, and tool discovery. Do not interpret a filter over an absent tool as a valid access-denial test.

Task D — Create a business policy for the selected read tool

Start here: Oracle Integration 3, in the same governance project. The managed server connection is saved, and the target tool is listed with its actual input schema available for inspection.

Navigation: Projects > PROCUREMENT_GATEWAY_GOV > MCP Gateway > Business policies > Add

Steps

  1. Open MCP Gateway in the governance project and select Add in the Business policies section.
  2. Enter a descriptive name such as Validate Procurement PO Number. Review the generated identifier and description.
  3. Select Create Policy. The business policy editor opens.
  4. From MCP Server, select the registered procurement server. From MCP Tool, select the actual purchase-order-status tool.
  5. Review the tool input schema. In AI Assist, describe a rule appropriate to that schema and select Generate rules. Generated rules are a draft that requires engineering review, not evidence that the business rule is correct.
  6. Inspect the JavaScript rule body. The illustrative body below applies only when the actual tool field is a string named purchaseOrderNumber. Replace the field reference and format rule if your selected tool has a different schema.
  7. Review Tool Payload and confirm the actual shape exposed through the editor's input parameter. Use payload suggestions where available. The example below assumes input.purchaseOrderNumber; if the field is nested differently, adapt the property path. Do not assume a generic JSON-RPC params.arguments path or a mapper screen not documented by this editor.
  8. Select Validate Syntax. Correct any syntax errors and validate again until the editor reports no syntax errors.
  9. Select Save.

Expected result: The business policy is saved against the chosen server and tool. Syntax validation does not prove that the rule is complete or that the runtime denies precisely the intended requests.

If this fails: Check that the server and tool are selected, every referenced input field exists in the actual schema, and the JavaScript rule uses the documented allow() and deny() contract correctly. Retest the business outcomes after saving the policy.

Illustrative JavaScript rule body only — not a tenant-verified script.

var poNumber = input && input.purchaseOrderNumber;

if (
    typeof poNumber !== "string" ||
    !/^PO-[0-9]{6}$/.test(poNumber)
) {
    deny("Purchase order number must use PO- followed by six digits.");
} else {
    allow("Purchase order number format is valid.");
}

Paste only the rule body into the editor's existing function wrapper. This example guards a missing input object, checks the string type, and applies the exact format pattern. The anchored expression requires PO- followed by exactly six ASCII digits; leading/trailing whitespace and line terminators are rejected. This is a format check only: it does not establish that a purchase order exists or that the caller may read it. The example separates a schema-valid but business-invalid value from a valid one only when the actual schema permits both candidate strings. If the field schema specifies a string, test PO-104281 and a malformed string such as PO-ABC. The first should satisfy this illustrative rule; the second should be denied by the rule if configured and executed as intended. Confirm the actual rule evaluation in the gateway evidence and verify that a denied request did not reach the integration. Do not treat a client-side schema error as proof that the business policy executed. Also test a missing field, a wrong type, leading/trailing whitespace, a final newline, too few/many digits, and a non-ASCII digit. The reviewed JavaScript can be checked locally, but OIC payload binding and policy evaluation still need tenant tests. If the schema itself rejects PO-ABC, select another schema-valid value that violates the intended business rule rather than weakening the schema for the test.

The gateway creation procedure is designed to bring together registered servers, security policies, and business policies. For a corporate read-only route, the tool filter and the reviewed business rule above provide a bounded example. Do not add a PII detection policy by default just to make the object count larger. PII detection has its own configuration requirements, selected detector set, field inclusion, enforcement scope, and OCI Language dependency.

Safety Check — tool visibility and invocation

Risk: A tool disappears from the discovery list, creating a false impression that it cannot be invoked or that the underlying business operation is protected against every other access path.

Control: Treat the tool filter as an exposure/discovery control. Independently test direct invocation of an excluded tool and inspect the actual enforcement evidence. Keep critical authorization and business validation in the integration and target system where appropriate.

Enforcement owner: OIC gateway administrator for gateway configuration; integration and target-application owners for authoritative business access.

Verification: Confirm a harmless baseline tool call before changing the filter, then compare discovery and direct invocation results after the filter is attached to an activated gateway.

Remaining risk: A filter does not automatically eliminate direct-backend bypasses or establish dynamic per-user and row-level authorization.

🎯 Use this when...

You need to establish the actual downstream route and the policy objects before creating the gateway, or you need to isolate a connection failure from a gateway authorization failure.

04
Create the Corporate Gateway and Assign Its Servers and Policies

The gateway object is the assembly point. Creating it establishes the configuration object, but that action alone does not complete activation or prove that a caller can use the runtime endpoint.

The following procedure uses the same governance project in which Tasks B, C, and D created the managed server and policies. It does not switch to the source project just because the source server belongs to another project.

Task E — Create the gateway configuration object

Start here: Oracle Integration 3, in PROCUREMENT_GATEWAY_GOV. The source server registration is saved, the intended security policy is saved, and the required business policy is saved.

Navigation: Projects > PROCUREMENT_GATEWAY_GOV > left toolbar MCP Gateway > MCP gateways > Add

Steps

  1. Open the governance project and select MCP Gateway in its left toolbar.
  2. In the MCP gateways section, select Add. The Create MCP gateway panel appears.
  3. Enter a descriptive name, such as Corporate Procurement Gateway.
  4. Review the generated Identifier. Oracle Integration generates this value from the name. Do not assume that you can freely change it after creation.
  5. Enter a description of the server group and its intended use. Keep the description accurate and avoid promising a level of authorization that has not been configured.
  6. Select Create. The MCP gateway details page opens. This is the completion of object creation, not runtime activation.

Expected result: The gateway exists and its details page is available for server and policy assignments.

If this fails: Confirm that the selected project is the intended governance project and that prerequisite objects have been saved. Do not continue by attempting to activate a gateway that has not been created successfully.

Task F — Assign the managed server, security policies, and business policies

Start here: Oracle Integration 3, in the same governance project, on the newly created gateway's details page. Do not return to the source tools project for this assignment.

Navigation: Projects > PROCUREMENT_GATEWAY_GOV > MCP Gateway > select Corporate Procurement Gateway

Steps

  1. From the gateway details page, locate the MCP Servers section.
  2. Select the registered procurement MCP server from the list. The policies associated with the selected server become available for assignment.
  3. In the Policies section, select the applicable tool-filter security policy for that server.
  4. Select the saved business policy against the same server, checking that it applies to the intended tool.
  5. Review the Policy evaluation order section. Use the displayed up and down controls to set a deliberate evaluation order. If multiple policies are present, do not assume their order is irrelevant.
  6. Review the selected server and associated policies together. Confirm that no unintended server or write-capable tool has been included.
  7. Select Save.

Expected result: The gateway configuration is saved with the intended server and assigned policies. The object is now prepared for activation, but the actual client access path still needs to be established.

If this fails: Confirm that the security and business policies were created in the intended project and are associated with the selected server. If a policy does not appear, inspect its saved scope and dependency rather than inventing an alternative policy attachment.

The policy evaluation sequence is a design choice with operational consequences. For example, placing a business rule before an optional PII processing step can avoid running a later step for a request that is rejected earlier. The actual order should follow your chosen policy behavior and the current Oracle-defined execution contract; do not infer universal fail-closed behavior from the position of a policy in the configuration.

Worked example — what the saved gateway should represent

The illustrative gateway named Corporate Procurement Gateway includes one registered source MCP server. Its tool filter selects the real purchase-order-status tool from the discovered tool list. A separate saved business policy validates a field whose name and schema have been checked in that tool's details.

The important result is not the name of the object. It is the saved relationship between the gateway, the registered server, and the actual policies selected for that server. No successful runtime test has been performed merely by viewing this configuration.

🎯 Use this when...

You need a single managed endpoint for selected MCP servers and want the team to agree on exactly which servers and policies belong to the gateway before it is activated.

05
Choose Dedicated Gateway Authorization or OIC Integration Authorization

The activation workflow requires a deliberate choice of how the gateway's inbound clients will be authorized. This decision is separate from the security policy used by the gateway to connect to the registered MCP server.

An authorization mode establishes the resource and permission model used by the caller. It does not automatically create every client application, assign the necessary scopes to it, or prove that a selected caller is appropriately isolated.

Comparison Dedicated gateway authorization OIC integration authorization
Resource boundaryUses a gateway-specific resource server and gateway-specific authorization information.Uses the existing Oracle Integration service-instance authorization model.
Discovery and invocation permissionsThe generated gateway-specific scopes distinguish tool discovery and invocation: tools:list and tools:call.Uses the existing OIC service-instance audience and integration scope, including urn:opc:resource:consumer::all, according to the applicable client configuration.
Client application workUse a confidential client application configured for the client-credentials grant and explicitly grant it the actual gateway-specific scopes after activation.Use a suitable confidential client application with the OIC integration audience, scope, and permissions required by the intended path.
IsolationSupports grants that are specific to a gateway, giving administrators a narrower resource boundary.Uses broader service-instance permissions rather than a resource server dedicated to the gateway.
Typical useA corporate gateway where individual gateway access must be explicitly granted and revoked.Development or test arrangements where the existing OIC integration authorization boundary is acceptable.

For the corporate procurement example, use dedicated gateway authorization as the starting recommendation because it offers an explicit gateway-level permission boundary. This is an architecture recommendation, not a substitute for your organization's security review. OIC integration authorization may be the appropriate choice for another environment, but its broader permission boundary must be understood and accepted.

Important distinction — audience, scope, and grant: The audience identifies the intended protected resource. A scope identifies the access being requested within the authorization model. The OAuth grant type describes how the client obtains a token. They are related but are not interchangeable. In particular, configuring client credentials does not make a service identity equivalent to an interactive employee identity.

For dedicated authorization, do not paste a generic scope string into the client application and assume it is gateway-specific. Oracle Integration generates the actual resource-server information for the configured gateway. Read the generated resource-server name from Run details after activation, then find that resource server under the confidential application's Add Scope picker in the identity domain. Select and copy the actual full scope values there. The guide does not require you to reconstruct scopes or assume every UI version displays them directly in Run details.

Task G — Activate the configured gateway

Start here: Oracle Integration 3, in PROCUREMENT_GATEWAY_GOV, with the gateway configuration saved by Tasks E and F.

Navigation: Projects > PROCUREMENT_GATEWAY_GOV > MCP Gateway > select the gateway > Actions > Activate

Steps

  1. Open the governance project and select MCP Gateway.
  2. Select the configured gateway in the MCP gateways section.
  3. Select Actions, then select Activate. The activation configuration flow opens.
  4. Choose the tracing level. For this corporate design, choose Production tracing unless a justified, approved nonproduction investigation requires Audit tracing.
  5. Select Use dedicated gateway authorization for the worked example. This choice uses the gateway-specific authorization resource and generated access scopes.
  6. Review the configuration choices. Selecting the tracing level and authorization mode is not the final completion step.
  7. Select the final Activate action in the activation flow.

Expected result: Oracle Integration completes the activation flow and the gateway becomes available for runtime use, subject to the selected authorization model and caller configuration.

If this fails: Do not attempt client tests against an unactivated gateway. Recheck saved server registration, selected policies, prerequisites, and the activation error. Resolve the blocking issue and repeat the documented activation sequence.

Oracle documents two tracing choices with different privacy implications. Production tracing records gateway activity without capturing request or response payloads; the current activation guide specifies a 32-day retention period. Audit tracing captures request and response payloads for troubleshooting and documents an eight-day retention period. Payload capture can include sensitive information, so Audit tracing is not recommended for production. Confirm the applicable behavior in the deployed release before establishing retention commitments. These gateway tracing settings do not establish what integration traces, client consoles, identity logs, or target systems retain. Review those separately and correlate sanitized timestamps and available request/integration identifiers.

Safety Check — OAuth boundary

Risk: A caller obtains a token for the wrong resource or uses a broad permission to access more gateways than intended.

Control: Choose the intended authorization mode, use the actual generated resource-server information, and grant only the required scopes to the appropriate client application.

Enforcement owner: Oracle Integration enforces its documented gateway authorization; the identity-domain administrator owns the corresponding application and scope configuration.

Verification: Obtain a token for the correct resource and permission set and test discovery and invocation independently.

Remaining risk: Correct inbound authorization does not prove that the registered server's downstream identity or the target application's business permissions are correct.

06
Retrieve the Gateway URL and Run the First Tests

Activation and URL retrieval are separate steps in the documented workflow. After activation, retrieve the gateway URL from the gateway's Run details panel. That value is the inbound endpoint for the final MCP client. Do not reuse the source MCP server URL for this request.

Task H — Retrieve the actual gateway endpoint and generated resource information

Start here: Oracle Integration 3, in the governance project, with the gateway activation completed. A dedicated-authorization gateway has created gateway-specific resource-server information that must be assigned to the appropriate client application.

Navigation: Projects > PROCUREMENT_GATEWAY_GOV > MCP Gateway > select the gateway > Actions > Run

Steps

  1. Open Projects and select the governance project.
  2. Select MCP Gateway in the project's left toolbar.
  3. Select the activated gateway from the MCP gateways section.
  4. Select Actions, then Run. The MCP Gateway run details panel opens.
  5. Copy the displayed MCP gateway URL into the approved client configuration. Treat it as a tenant-specific runtime value; do not construct it from the source server URL.
  6. For dedicated gateway authorization, copy the displayed mcp_resource_server_NAME value. In Task I, search for that resource server in the identity-domain Add Scope picker to select and copy its two complete scope values.

Expected result: You have the actual gateway runtime URL and, for dedicated authorization, the generated resource-server information required for client configuration.

If this fails: Confirm that the selected gateway is activated and that you are viewing the correct project. The gateway URL and source project MCP URL are different configuration values with different purposes.

With dedicated authorization, the identity-domain client application must now be granted the gateway's actual scopes. This is a distinct step from activating the gateway. The gateway having a resource server is not proof that a particular OAuth client has permission to use it.

Task I — Assign the generated scopes to a confidential client application

Start here: Oracle Cloud Console, in the identity domain used by the OIC instance. An activated confidential client application configured for client credentials is available, or the authorized identity administrator can create and activate one. Task H must have provided the actual gateway resource-server information.

Navigation: Identity & Security > Domains > select the compartment and identity domain > Integrated applications > select the intended confidential application

Steps

  1. Sign in to the Oracle Cloud Console using the authorized identity-domain administrative account.
  2. Open Identity & Security, then select Domains.
  3. Select the correct compartment and identity domain, then open Integrated applications.
  4. Select the confidential client application intended to call this gateway. Do not automatically reuse the downstream server's credential or application just because it already exists.
  5. Open the application's OAuth configuration tab and select Edit OAuth configuration.
  6. In the OAuth configuration, locate the Resources section and select Add Scope.
  7. Search for the actual resource-server name recorded from the gateway Run details. Expand or select the resource server belonging to this gateway.
  8. Select the two generated gateway scopes for tool discovery and invocation. Oracle's current activation guide illustrates the scopes by their suffixes, tools:list and tools:call. Copy the actual complete values from your gateway's resource-server information rather than constructing them manually.
  9. Select Submit to save the OAuth configuration changes.
  10. Confirm that the client application remains active and is ready to obtain a token with the newly assigned scopes.

Expected result: The selected confidential application has the actual gateway-specific scopes granted. The scopes have not been invented from a sample URL.

If this fails: Verify the identity domain, the selected client application, its client-credentials configuration, the gateway resource-server name, and the scope assignments. If the actual generated resource server is not available, stop and recheck gateway activation and the Run details panel.

If the client application does not yet exist, Oracle's confidential client prerequisites describe the creation workflow: use Add application, select Confidential Application, launch the workflow, configure it as a client, select the appropriate allowed grant type, submit the OAuth configuration, and activate the application. The gateway-specific scopes can only be assigned after the gateway's generated resource server is available. Do not confuse that post-activation scope assignment with creating the downstream client used to authenticate the gateway to the source project. The linked project-client prerequisite guide also contains OIC integration resource scopes and a ServiceInvoker assignment. Those belong to its project/integration access recipe; do not copy them blindly into a dedicated gateway-only caller. Follow the gateway activation guide's generated resource and scope configuration for that inbound client, and verify any additional privileges required by the actual deployment.

The client then obtains a token from the intended identity-domain authorization server and presents it to the gateway endpoint. For client credentials, the token endpoint is the one belonging to the configured identity domain, commonly represented as https://<identity-domain-host>/oauth2/v1/token. The actual host must come from the configured domain. Never include a client secret ticket, screenshot, or command history that will be shared.

Identity flow — which component calls whom?

StepSender and recipientMeaning
1MCP client to identity providerThe client requests a token under its configured grant and scopes. The identity provider returns a token or an authorization error.
2MCP client to gatewayThe client presents the token to the protected gateway endpoint. The gateway applies its inbound authorization rules.
3Gateway to registered MCP serverThe gateway routes the permitted MCP request using the registered server's configured downstream connection and identity design.
4Registered OIC integration to target systemThe integration executes the business workflow using its configured invoke connection and target authorization. A user-identity path requires separate supported configuration.
5Return path to the clientThe result travels back through the applicable MCP server and gateway path to the client. Record correlation and execution evidence at the available layers.

The gateway does not automatically turn the inbound bearer token into valid credentials for every downstream server. Each hop must use the documented and configured identity mechanism for that boundary.

For the runtime client, use an MCP-capable client that supports the applicable gateway connection workflow. Oracle demonstrates MCP gateway use with Postman in its published examples, while its project-client documentation explicitly describes Streamable HTTP for the project MCP server. Do not assume that every client's transport, session handling, or version works identically with every gateway or third-party server. The exact Postman navigation is version-dependent and has not been verified against a tenant or a specified local Postman version in this tutorial.

Client setup checklist: Configure the MCP client with the actual gateway URL, the relevant OAuth token acquisition settings, and a token with the intended gateway authorization. Connect using the client's supported MCP workflow. Confirm discovery first, then call an actual discovered tool with schema-valid test arguments. Do not treat an ordinary REST POST as a substitute for an MCP connection workflow.

A concrete manual client sequence

In Postman, create an MCP request, choose HTTP for the applicable remote MCP transport, and paste the activated gateway URL. In Authorization, select OAuth 2.0 and Client Credentials. Enter the actual identity-domain token URL, client ID, protected secret reference, and both full generated gateway scopes separated by a space. Oracle's example sends client credentials as a Basic Auth header. Get a new access token and choose Use Token, with Proceed if prompted. Keep token sharing off.

Load Capabilities, open Tools, select an actual discovered tool, enter schema-valid synthetic arguments, and select Run. Record the client version and supported protocol revision. Let the client manage the applicable protocol exchange; do not force a handshake or session header from a different MCP revision. A manual MCP test needs no LLM and does not test automatic model selection. Inspect the protocol result and business content: an HTTP success response alone does not establish a successful tool operation.

Source: Postman — Create an MCP request.

Source: Postman — OAuth 2.0 authentication.

Worked example — discovery to invocation

An authorized client connects to the actual gateway endpoint and discovers the real tool metadata. For illustration, imagine the discovered tool has the display name Get Purchase Order Status, a stable tool identifier that the client reports, and a string input field named purchaseOrderNumber. These labels are hypothetical until discovery in the real server confirms them.

Business requestRetrieve the status of purchase order PO-104281.
Tool discoveryThe client receives the actual discovered identifier, description, and input schema from the server through the gateway.
Proposed argumentsThe host/model may propose a purchase-order number, but the host or client is responsible for issuing the actual protocol request.
Gateway decisionThe gateway applies the configured authorization and applicable policies before routing the request.
Business executionThe registered integration performs the workflow and communicates with the target system using its configured credentials and permissions.
Returned resultThe tool result travels back to the MCP client. The host uses that result as input to its response. Inspect the real tool result instead of assuming particular business fields exist.

This is a responsibility walkthrough, not a claim that a client request was executed or that a tenant has these exact field names. Oracle documents tools/list and tools/call for project MCP servers. Use the actual documented client exchange and negotiated protocol behavior; do not infer a complete runnable JSON-RPC exchange from this conceptual example.

The positive baseline must use both generated scopes required by Oracle's connection procedure, a real included tool, and schema-valid synthetic input. A discovery-only token is an optional reduced-scope experiment, not a documented guarantee that connection and discovery will succeed with one scope. Establish whether the actual endpoint/client supports that flow, then record whether rejection occurs at connection, discovery, or invocation. Never report a connection failure as proof of a separate invocation-scope check.

Because the identity provider issues tokens according to its configured application and scope permissions, confirm that the reduced-scope token was actually issued with the intended permissions before drawing conclusions from the gateway request. A token issuance failure is evidence about token acquisition, not proof that the gateway rejected an otherwise valid request.

Test Expected behavior Evidence and limitation
Discovery with the documented full-scope baseline tokenThe client connects and can discover the intended, actually included tools.Record the real tool identifiers, descriptions, and visible schemas. This does not prove each tool is safe to invoke.
Invocation with full valid authorization and valid test inputThe intended read-oriented tool returns its actual result.Correlate the gateway activity, OIC integration execution, and target evidence where available. This article has not executed the test.
Optional reduced-scope experiment: token lacks invocation scopeAccess requiring absent permission should be denied; the request may already be rejected during connection or discovery. Determine the observed enforcement point.Verify the token was issued with the intended reduced permissions and that a new request reached the gateway. Record the actual rejection point, absence of unintended data disclosure, and relevant execution evidence.
Business-rule rejection with schema-valid argumentsA malformed string should be rejected if it reaches the configured illustrative rule and the rule is functioning as intended.Check policy evaluation and confirm the integration was not invoked. Do not confuse a schema rejection or client validation failure with business-policy enforcement.

For a basic authentication-negative test, use a fresh separate MCP request to the same gateway with No Auth. Verify that it sends no inherited Authorization header or credentials and performs a new server exchange instead of showing cached tool metadata. Keep the valid baseline intact and repeat its successful read afterward. Do not change or revoke a shared client merely to run this test. All outcomes in the preceding test matrix are expected behavior, not observations from a running gateway. Where a denied request should not reach the integration, corroborate the gateway decision with available downstream evidence; a missing monitoring row alone is not conclusive. Actual results and the rejection layer must be recorded by the person executing the tests.

🎯 Use this when...

You need to separate activation, token acquisition, gateway authorization, tool discovery, invocation routing, and integration execution rather than treating every connection problem as one generic MCP failure.

07
Change Gateway Authorization Mode and Retest

Changing the authorization mode is not merely a client-side OAuth edit. Oracle's activation documentation instructs administrators to deactivate the activated gateway, change the authorization selection, and reactivate it. The client must then be checked against the resulting authorization configuration.

For example, a development gateway may initially use OIC integration authorization to simplify a controlled test. Later, the organization may decide that the gateway requires a dedicated resource-server boundary. This change requires configuration review, scope assignment, token acquisition, and fresh acceptance tests.

Analogy — changing the access card

Changing the authorization mode is like changing which access system recognizes an employee's card. The physical door may still have the same address, but the card's permission is not guaranteed to remain valid under the new access model. Verify the new permission source, obtain the appropriate credential, and retest before reconnecting users.

Task J — Deactivate, change the mode, and reactivate

Start here: Oracle Integration 3, in PROCUREMENT_GATEWAY_GOV, with an activated gateway and a planned change approved for the test environment.

Navigation: Projects > PROCUREMENT_GATEWAY_GOV > MCP Gateway > select the gateway > gateway lifecycle actions

Steps

  1. Review the change plan and capture the existing mode, current client-application scopes, tracing selection, gateway URL, and baseline test results. Confirm the impact on active users before proceeding.
  2. In the selected gateway's lifecycle actions, choose the documented Deactivate action. The current activation guide requires deactivation before the mode change, but it does not spell out a separate full click path for the deactivation screen; use the available lifecycle control in your release rather than assuming that an unverified label or dialog exists.
  3. Wait until the gateway reflects the resulting inactive state. Do not initiate fresh runtime acceptance tests while the required activation state has not been restored.
  4. Return to the selected gateway and use the documented Actions > Activate workflow.
  5. Select the intended new authorization mode in the activation flow. Review the scope boundary and any client-application changes required by that mode.
  6. Select the required tracing option and complete the final Activate action.
  7. Open the gateway's Run details again. Record the currently displayed URL and resource-server information relevant to the new mode. For dedicated authorization, verify the gateway-specific resource server and scopes; for OIC integration authorization, verify the existing OIC resource and scope configuration.
  8. Update the intended client application where required, obtain a fresh token using the appropriate configured grant and permissions, and retest tool discovery and invocation separately.
  9. Compare positive and negative test evidence against the baseline before restoring user access. Review expected downtime and any in-flight operations with the service owner; this tutorial does not establish automatic draining, cancellation, or rollback behavior. Obtain fresh client evidence so an old cached token or tool list does not mask the change.

Expected result: The gateway has been reactivated using the new authorization mode and its authorized client path has been tested again.

If this fails: Stop before restoring callers. Check whether the gateway is active, whether the token belongs to the intended resource and scope set, and whether the identity application reflects the new mode. Restore the approved prior configuration through the documented lifecycle, client configuration, and token procedures if the change cannot pass acceptance testing.

Retest matrix for a mode change:

Control Dedicated gateway authorization OIC integration authorization
Correct resourceConfirm the gateway-specific resource server and actual generated scopes.Confirm the OIC service-instance audience and existing integration authorization scope.
Valid clientConfirm the client is authorized for the required gateway-specific resource and scopes.Confirm the client is authorized for the broader OIC integration authorization model.
DiscoveryFirst use a baseline token containing both scopes required by Oracle's gateway connection procedure.Test using a valid token for the OIC integration authorization path.
InvocationTest with the intended invocation scope and separately attempt a valid reduced-scope negative test where supported.Test with the appropriate OIC integration permissions. Do not assume that a missing dedicated tool scope exists under this mode.
Downstream executionConfirm the registered server's own security configuration remains valid.Confirm the registered server's own security configuration remains valid.

Do not assume that changing the inbound authorization mode changes the downstream server's security policy. Equally, do not assume the gateway URL or generated scope will remain unchanged across every lifecycle change. Re-read the displayed values after activation and use the actual values for the active configuration.

Safety Check — configuration drift

Risk: A gateway is reactivated with a different authorization mode while the client continues using an old token or old scope assumptions.

Control: Treat the mode change as a controlled lifecycle operation: deactivate, change the setting, reactivate, retrieve the active configuration, configure the client, obtain an appropriate token, and retest.

Enforcement owner: OIC administrator and identity-domain administrator, with the client owner responsible for its configured credentials and scopes.

Verification: Capture the new mode, the generated authorization values where applicable, the new token-acquisition result, and positive and negative runtime test results.

Remaining risk: Successful gateway activation cannot prove that every external consumer has updated its credentials or that direct access to a downstream server is blocked.

08
Common Mistakes and Targeted Corrections

When a newly configured gateway cannot be used, start by identifying the first failing layer. Avoid changing several unrelated objects at once, because doing so destroys the evidence needed to identify the actual defect.

Symptom Targeted check Minimal correction and retest
Gateway activation is unavailable or fails.Verify instance release, entitlement, saved gateway configuration, server registration, policy assignment, and the actual activation error.Resolve the specific prerequisite or configuration defect, then repeat activation. Do not assume that another instance's release proves this one is eligible.
The gateway connects, but expected tools are missing.Inspect actual source discovery, filter server selection, included tools, and saved policy assignment.Repair the tool selection or registration and recheck discovery. Do not use a nonexistent tool identifier in an invocation test.
Token acquisition fails.Check identity-domain host, OAuth grant, client configuration, requested scopes, application state, and permission assignment.Correct the identity-provider configuration and prove a token can be issued before testing gateway enforcement.
The client obtains a token but gateway access fails.Compare the actual gateway URL, authorization mode, token's intended resource, and granted scopes.Use the authorization details associated with the current activation and obtain a new appropriate token. Do not rely on a hand-built audience string.
The connection test for a registered server fails.Check the source endpoint, selected server security policy, token endpoint, downstream scope, and the actual authentication error.Correct the downstream server registration. Do not troubleshoot this solely by changing the inbound gateway client.
A policy rejects a request that appears valid.Inspect the actual input schema, payload binding, rule logic, policy order, and the recorded rejection layer.Correct the minimum necessary policy or test data, validate the rule, then run the positive and negative cases again.
A tool disappears after a filter change.Confirm whether the tool is absent from discovery as expected and whether the changed filter is attached to the relevant gateway.Correct the selection if accidental. Separately test invocation of the real excluded tool; missing from discovery alone does not prove invocation denial.

HTTP status, client error, MCP protocol error, policy rejection, OIC integration failure, and target business-rule rejection are different evidence types. A single status code cannot reliably identify the responsible layer without the accompanying configuration and runtime evidence.

For a productive investigation, capture the OIC release, selected project, gateway activation state, authorization mode, sanitized error, whether token issuance succeeded, whether discovery succeeded, the specific tool identifier, and the relevant policy configuration. Never send an access token, client secret, private key, or unmasked customer payload as diagnostic evidence.

🎯 Use this when...

You need a repeatable troubleshooting approach that isolates identity configuration, gateway enforcement, server routing, policy evaluation, integration execution, and target permissions.

09
Enterprise Rollout: Prove the Boundary Before Enabling Users

A gateway can be technically active and still be unready for enterprise use. Production approval must consider the actual caller, its authorization, the server connection, selected tools, policy behavior, downstream identity, observability, change ownership, and alternative routes to the backend.

For the procurement example, keep final purchase approval outside the assistant's exposed tool set. The example is intentionally read-oriented. A write capability should be introduced only in a nonproduction environment with synthetic data, a reviewed authorization design, authoritative target-side validation, and controls that prevent unintended duplicate side effects. A tool description or gateway policy must not replace the business transaction's real authorization and validation.

Acceptance item Evidence to collect Status at publication
Instance and gateway eligibilityRelease, entitlement, region/realm, project, gateway state, and saved configuration.Documentation checked; tenant not tested.
Server registrationReal MCP endpoint, selected security policy, connection test result, discovered tools, and saved registration.Proposed lab gate; not executed.
Successful caller accessA valid token, successful discovery, and one read-oriented tool invocation with synthetic inputs.Proposed test; no observed runtime result.
Authorization negative testA fresh unauthenticated request is denied; any supported reduced-scope test identifies the actual rejection point and confirms no unintended data disclosure or execution.Proposed test; no observed runtime result.
Business policyA valid request is allowed, a schema-valid business-invalid request is rejected, and the denied case does not execute the integration.Illustrative rule; requires schema-specific implementation and test.
Tool filterAn actual tool works before filtering; after filtering, discovery changes as expected. Direct invocation is tested and recorded separately.Proposed test; no observed runtime result.
Downstream authorizationThe configured service identity or supported user-propagation path and corresponding target-side permission/audit evidence.Requires tenant-specific verification.
Mode-change recoveryDeactivation, reactivation, actual authorization configuration, fresh token, success/denial results, and rollback evidence.Proposed test; no observed runtime result.
Operational trace and ownershipSanitized trace evidence, retention expectations, access to logs, and named ownership for policies, integrations, identity, and incidents.Requires organization-specific approval.

For each test, record the expected outcome, actual outcome, evidence reference, execution date, responsible tester, and status. Use Passed, Failed, or Not executed. A simulated example must not be marked as lab-verified.

Where user identity must reach the target system, configure and test the documented identity-propagation mechanism explicitly. Oracle's JWT User Assertion use case describes how user identity can be propagated across the gateway, MCP server, registered integration, and endpoint when the appropriate security policy, signing configuration, and subject mapping are in place. A client-credentials gateway token alone is not proof of the identity of an interactive user. Oracle's propagation example uses an Authorization Code user token for the inbound caller and explicit trigger-Subject to invoke-Subject mapping in the integration. Validate compatibility with the selected gateway authorization mode before applying that user-token design; the dedicated client-credentials example in this article does not implement it.

Finally, test whether the source MCP server or target system can be called independently of the gateway by a principal who should not have that access. Gateway policy does not automatically close every other route. The relevant network paths, credentials, target permissions, and direct access controls must be assessed at their actual enforcement points.

Safety Check — production readiness

Risk: A gateway is approved because one client connected successfully, even though excluded tools, target permissions, direct access, business-policy behavior, and authorization changes have not been tested.

Control: Complete a controlled positive/negative acceptance matrix, confirm target-side permissions, assess bypass routes, define logging/retention, and assign operational owners.

Enforcement owner: OIC platform owner, identity/security owner, integration owner, target-system owner, and the organization's production approver, according to the responsibility model.

Verification: Review recorded runtime evidence and resolved gaps before authorizing the pilot.

Remaining risk: No one test, policy, token, or approval eliminates every failure mode or security risk. Production approval requires the organization's full operational and security review.

Learning checkpoint: Sketch your own procurement route in words. Identify the inbound client endpoint, the token's intended audience and permissions, the server registration's downstream credentials, the gateway's assigned policies, the integration's target identity, and the evidence that would prove one positive and one negative case. Mark every untested hop explicitly. The purpose is to demonstrate that the architecture and its test evidence agree, not simply that the gateway status says active.

🎯 Use this when...

You are preparing an internal demonstration, a supervised pilot, an authorization-mode migration, or a handover to the team that will own the gateway in production.

10
❓ Frequently Asked Questions

1. What release and edition do I need?

Oracle lists MCP Gateway with minimum version 26.10. Its edition matrix lists MCP Server support in Enterprise and Healthcare, not Standard; that supports the source project server used here. Confirm the actual gateway entitlement, instance release, and availability separately.

2. What is the difference between dedicated gateway authorization and OIC integration authorization?

Dedicated gateway authorization uses a gateway-specific resource server and generated discovery and invocation scopes. OIC integration authorization uses the existing OIC service-instance authorization model and a broader permission boundary rather than a resource server dedicated to that gateway.

3. Does activating the gateway automatically grant the generated scopes to a client?

No. For dedicated authorization, activation creates the gateway-specific resource server. Copy its name from Run details, find it in the confidential application's Add Scope picker, select the two generated scopes, submit the configuration, and then obtain a token.

4. Does a tool filter guarantee that direct invocation of an excluded tool is denied?

No. A tool filter controls tool availability and discoverability for the selected MCP server; independently test direct invocation and enforce critical permissions in the integration or target system.

5. Does the gateway automatically propagate the caller's identity to the backend?

No. Caller-to-gateway authorization and gateway-to-server credentials are separate. User propagation requires a supported configured identity path, such as OAuth using JWT User Assertion, plus the required mapping and downstream authorization.

11
🔗 References and Further Reading

Review the live documentation for your deployed release before applying a procedure.

The procurement scenario, identifiers, and expected outcomes are fictional teaching material. Product procedures are attributed to the primary references, and the revised rule is an illustrative format check rather than a deployed policy. Oracle and other vendor/product names remain the property of their respective owners. The use of product documentation as factual reference does not mean that a gateway was deployed or tested for this article.

12
📝 Summary

Understand the objects: A project MCP server exposes eligible registered tools; a managed server registration defines the gateway's downstream connection; policies govern their assigned scope; and the gateway assembles the selected servers and controls.

Create in dependency order: Verify the source endpoint, configure and test the managed server, save the required security and business policies, create the gateway, and assign the server and policies.

Activate completely: Choose a tracing level and authorization mode, then complete the final Activate action. Retrieve the endpoint from Run details only after the gateway's lifecycle state is correct.

Configure the actual OAuth boundary: Dedicated authorization requires the gateway-specific resource-server scopes to be granted to the intended client application. OIC integration authorization uses a broader service-instance boundary. Do not confuse either one with the downstream server's credentials.

Test both permission and failure paths: Prove successful discovery and invocation, then test a fresh unauthenticated request, any supported reduced-scope flow, and the behavior of applicable business and tool-filter controls. Record the real rejection layer and verify downstream execution evidence.

Change deliberately: Deactivate, change the authorization configuration, reactivate, retrieve the current values, obtain the appropriate token, and rerun the acceptance tests before restoring callers.

Final engineering principle

A working gateway URL is the beginning of the runtime acceptance test, not the end of the security review. The useful outcome is an endpoint whose authorized use, denied use, downstream behavior, and operational ownership are all supported by evidence.

Keep learning, test carefully, and document what your environment actually proves.

Comments