This tutorial starts with a live custom chatbot that already has a text input, a Send button, an LLM and an application backend. The goal is to understand how a request from that chatbot reaches MCP Gateway, how Gateway routes it to an approved tool, how the tool executes an OIC integration, and how the original user's identity and permissions can be carried to Oracle Fusion ERP.
We will not build the chatbot or its agent runtime. We will configure and verify the OIC side of the connection, identify what the existing application must supply, and follow one transaction from the user's message to the actual downstream result.
Our running example is a fictional employee who enters: “Please create an invoice of 5,000 USD against PO-9090.” The application should retrieve permitted purchase-order information, present a complete invoice preview, obtain explicit confirmation, and then invoke the invoice-creation tool.
📑 In This Post
- What happens when the user clicks Send?
- Understand the application-to-Gateway boundary
- Prepare the OIC and identity configuration
- Prepare the OIC integrations and tool contracts
- Register tools and enable the project MCP server
- Register the project MCP server in Gateway
- Configure tool filters and business policies
- Activate Gateway and obtain its URL
- Propagate the caller's identity to Fusion ERP
- Trace the live request and response
- Prove role and permission enforcement
- Troubleshooting the failing layer
- Common mistakes
- Enterprise rollout
- FAQ
- References and further reading
- Summary
01
What Happens When the User Clicks Send?
Imagine that a user is already logged in to an enterprise chatbot. The page is open, the chat input is working, and the LLM is configured. We begin at the point where that existing application can make an MCP request.
The Send button does not directly activate an OIC integration. It submits a message to the existing application's runtime. If that runtime determines that an approved OIC tool is needed, its MCP client invokes that tool through the configured Gateway endpoint.
Analogy — a service desk and its authorized work orders. The chatbot receives a request. The MCP client carries a structured work order, Gateway checks the configured access rules, the project MCP server identifies the registered tool, and the OIC integration performs the business operation. Sending a message alone does not authorize the work order.
The runtime sequence
ONE-TIME / SESSION SETUP
Existing application obtains or associates the appropriate
OAuth access token with the authenticated caller.
Existing MCP client connects to the OIC MCP Gateway endpoint.
MCP client discovers the allowed tools and their schemas.
RUNTIME — USER CLICKS SEND
1. User
|
| "Create an invoice of USD 5,000 against PO-9090"
v
2. Existing chatbot runtime / LLM
|
| Decides that PO information is required
v
3. Existing MCP client
|
| tools/call: permitted PO lookup tool
| OAuth access token for the selected Gateway authorization mode
v
4. OIC MCP Gateway
|
| Authenticates/authorizes caller
| Applies applicable policies
v
5. Managed project MCP server
|
| Dispatches the registered tool
v
6. OIC integration
|
| Validates request and calls the target API
v
7. Oracle Fusion ERP
|
| Applies target privileges and business rules
v
8. Response returns through OIC, MCP server and Gateway
|
v
9. Existing application
|
| Displays verified PO details and asks for missing values
AFTER THE USER CONFIRMS THE EXACT PREVIEW
Existing application
|
| tools/call: invoice-creation tool
v
Gateway -> Project MCP server -> OIC integration -> Fusion Payables
|
| Actual response, or an uncertain outcome that needs reconciliation
v
Existing application displays the verified result or honest failure.
There are two important protocol operations:
| Operation | Purpose | Does the business integration run? |
|---|---|---|
tools/list |
Requests available tool names, descriptions and input schemas. | No. It is a discovery operation. |
tools/call |
Requests execution of a specific tool with its arguments. | It can dispatch the registered OIC integration after authorization and applicable policies succeed. |
Oracle's project MCP server documentation identifies tools/list and tools/call as supported operations. For this route, the documented MCP client transport is Streamable HTTP. The MCP SDK handles protocol framing and the negotiated connection lifecycle; the client should not treat an arbitrary REST POST as a complete MCP session.
Reference: FAQs for Projects as MCP Servers and Discover Integrations as Tools from MCP Clients.
You need to troubleshoot whether a chatbot message reached the agent runtime, whether the client invoked Gateway, and whether Gateway actually dispatched an OIC tool.
02
Understand the Application-to-Gateway Boundary
The third-party chatbot remains outside OIC. We do not need to recreate its frontend or agent loop. We only need to establish the contract it must satisfy to invoke the OIC-managed tools.
| Component | Responsibility | What we verify |
|---|---|---|
| Existing chatbot application | Accepts user messages and runs the application-side agent logic. | It has a compatible MCP client and supplies the appropriate caller token. |
| MCP client | Discovers tools and invokes them using MCP. | It connects to the actual Gateway URL using supported Streamable HTTP and OAuth configuration. |
| OIC MCP Gateway | Provides the governed endpoint to configured MCP servers. | The caller is authorized for the selected Gateway mode and applicable policies permit the operation. |
| Project MCP server | Exposes integrations registered as tools in an OIC project. | The required integration tools are registered and discoverable. |
| OIC integration | Performs the integration workflow and invokes the target API. | The request is validated, the correct outbound identity is used, and the target response is mapped accurately. |
| Fusion ERP | Applies the target application's permissions and business rules. | The real user has the required privileges and the invoice satisfies target validation. |
What must already exist in the external application? Only the relevant integration points: a compatible MCP client, the correct Gateway URL, a method of obtaining the access token required by the configured authorization mode, and a way to supply discovered tool definitions to its existing agent runtime.
The external application does not need to know how the OIC integration connects to Fusion. That is OIC's responsibility. Conversely, Gateway does not automatically detect a user's typed message or decide that every Send click should invoke an integration. The existing agent runtime selects an available tool and asks its MCP client to call it.
An illustrative logical tool call might contain the following information:
Tool identifier:
find_permitted_purchase_order
Business arguments:
purchaseOrderNumber = "PO-9090"
Destination:
The actual OIC MCP Gateway URL
Authentication:
OAuth access token required by the selected
Gateway authorization mode
This is a logical description of the request, not a complete wire-level MCP message. The discovered identifier must match the real tool identifier registered in OIC. The client SDK generates the protocol exchange.
Safety Check — the client must use the governed endpoint
Risk → The chatbot might call a project MCP server or an integration endpoint directly, bypassing the intended Gateway policies.
Control → Configure the real Gateway URL in the MCP client and separately test whether the project endpoint or REST trigger can be reached using other permissions.
Remaining risk → Direct access can remain possible if other grants or network routes permit it. The presence of Gateway does not prove that alternate routes are disabled.
03
Prepare OIC and Identity Configuration
Before configuring the Gateway, distinguish the authentication requirements for three different connections:
- Chatbot MCP client → Gateway: the token, audience and scopes accepted by the Gateway authorization mode.
- Gateway → project MCP server: the security policy used for the managed-server connection.
- OIC integration → Fusion ERP: the outbound connection's authentication and target authorization.
These are separate trust boundaries. A successful token exchange for one boundary does not prove the credentials or identity are correct for another.
Console navigation — identify the correct identity domain
OCI Console → Identity & Security → Domains → select the identity domain used for the relevant OIC application configuration → Integrated applications.
Record the domain URL, client ID, configured grant, allowed resources, scopes and roles. Determine whether the selected OAuth flow authenticates the end user or authenticates an application as a service principal.
Why the grant type matters. A client-credentials token identifies a client application. It must not automatically be treated as the identity of the employee who typed into the chatbot.
Oracle documents a user-identity-propagation pattern where the Gateway caller obtains an OAuth Authorization Code token and uses that token to invoke Gateway. The downstream MCP-server connection is configured for OAuth using JWT User Assertion, and the target integration maps the triggering Subject to the outbound invoke Subject.
In contrast, the dedicated Gateway authorization activation path requires a confidential client configured with client credentials and the Gateway-specific audience and scopes. If the business requirement is to propagate an interactive user's identity, do not assume that the dedicated client-credentials example alone satisfies that requirement. Confirm the exact grant and identity-propagation combination for your selected release and environment.
| Authorization choice | What it provides | What must not be assumed |
|---|---|---|
| Dedicated Gateway authorization | Gateway-specific audience and scopes, with narrower access isolation between Gateways. | That a client-credentials token represents the interactive user or automatically enables the published JWT user-propagation flow. |
| OIC integration authorization | Uses the existing OIC integration resource and authorization model for the instance. | That all users have identical access or that Fusion privileges are automatically granted. |
For the worked identity-propagation scenario, use Oracle's documented Authorization Code caller and JWT user-assertion propagation pattern as the reference. Follow the current Gateway activation instructions and explicitly verify the selected authorization mode. Where the required caller-token grant is incompatible with the chosen mode, stop and resolve the architecture rather than substituting a shared service token.
Also verify that the necessary confidential client application is activated and has the roles and scopes required by the selected OIC authorization configuration. Oracle's project MCP client prerequisites identify the ServiceInvoker role for the relevant confidential-client configuration. The exact resource and scopes must come from the actual identity-domain and Gateway configuration, not from a guessed URL or another tenancy's values.
Reference: Activate an MCP Gateway, Create and Activate the Client Application and Propagate User Identity for MCP Tool Invocations.
04
Prepare the OIC Integrations and Tool Contracts
An OIC project MCP server exposes integrations that have been registered as agentic AI tools. An active integration alone is not enough. The integration must belong to a project and satisfy the documented trigger requirements.
Oracle's documented requirements include an active project integration with a REST Adapter trigger and a JSON payload. The project MCP server discovers only integrations registered as tools.
Use a small set of clearly defined tools. For the invoice scenario, four tools provide the required read and write capabilities:
| Illustrative tool | Business responsibility | Key control |
|---|---|---|
find_permitted_purchase_order |
Retrieve permitted PO details, supplier, currency and eligible lines. | Only disclose purchase orders the caller is permitted to read. |
resolve_invoice_reference_data |
Resolve required invoice reference values and matching information. | Return verified values or report missing and ambiguous information. |
create_payables_invoice |
Create a supplier invoice using the Fusion Payables API. | Validate the canonical request, authorization, confirmation and duplicate protection. |
get_payables_invoice_status |
Retrieve the state of a previously created invoice. | Check caller permissions and report the actual target status. |
These tool identifiers are original illustrative names. The actual identifiers generated in your OIC project are authoritative and may differ. The tool's description helps the LLM understand when to use it; it does not itself authorize execution.
Build or verify each integration in OIC.
Console navigation — project integrations
OIC design-time console → Projects → select your project → Integrations.
- For an existing integration, confirm the integration belongs to the selected project and is active.
- Confirm that the first connection is the REST Adapter trigger.
- Confirm the incoming request uses OAuth authentication and a JSON payload as required for project MCP tool registration.
- For the read tools, verify the target REST call, filters and response mapping. A PO lookup must not return arbitrary records outside the caller's permitted scope.
- For the creation tool, validate the request and use the appropriate Fusion Financials Payables invoice operation.
- For the status tool, use a supported invoice read operation and verify target permissions on the record.
- Validate, save and activate the integration using the appropriate OIC lifecycle actions.
For an integration that must preserve the originating user's identity, verify the trigger's security properties and the outbound invoke connection as part of the identity-propagation procedure in Section 09. Do not treat OAuth on the REST trigger alone as proof that Fusion receives the same user.
Expose only meaningful business arguments. A PO lookup can accept purchaseOrderNumber. An invoice-creation tool can accept the canonical invoice details required by the target API. Do not create model-editable parameters such as accessToken, username, role, Subject or isAdmin. Security identity must come from a trusted execution context.
Worked example — the read-tool contract
Illustrative tool input:
{
"purchaseOrderNumber": "PO-9090"
}
Illustrative normalized response from a synthetic target record:
{
"found": true,
"purchaseOrderNumber": "PO-9090",
"supplier": "Acme Industrial Supplies",
"supplierSite": "US-WEST",
"businessUnit": "Vision Operations",
"currency": "USD",
"eligibleLines": [
{
"lineNumber": 1,
"remainingMatchableAmount": 5000
}
]
}
This is test data, not a verified Fusion response. It supplies information for the application to prepare a draft. The create operation still requires all mandatory invoice fields, fresh server-side validation and explicit confirmation.
05
Register the Tools and Enable the Project MCP Server
Registering the integration as an agentic AI tool makes it discoverable through the project's MCP server. Enabling MCP then provides the MCP endpoint for that project.
Console navigation — register an integration as a tool
OIC → Projects → select the project → Integrations.
- Locate the active integration to expose.
- Select the integration's Actions menu, then choose Create agentic AI tool.
- Review the Name and Identifier. The identifier is sent as tool metadata and is used to identify the tool. Oracle documents that these fields cannot be changed after creation.
- Provide a clear description of what the tool does and when it should be used.
- Select Create.
- On the tool details page, review its description, guidelines and input parameters.
- Set the appropriate visibility and parameter values supported by the editor, then select Save.
- Repeat for each integration that the chatbot needs.
The integration's display name and tool identifier are not the same conceptual value. The description and guidelines help the LLM choose and use the tool, but they are not an authorization policy. Required fields, visible fields and enum settings must match the real integration contract, and the integration must independently validate the received request.
Now enable MCP for the project.
Console navigation — enable the project's MCP server
OIC → Projects → select the project → click the project details edit icon at the upper right.
- Select Enable MCP server.
- Select Save changes.
- Open the project details again using the edit icon.
- Record the displayed MCP server URL.
Each OIC project has its own MCP server URL. Use the actual URL displayed in your project. Do not guess its identifier from the project name or reuse the endpoint from a different OIC instance.
Expected milestone: the active integrations are registered as tools, the project MCP server is enabled, and the project details show its runtime MCP URL. That URL is the downstream server endpoint for Gateway registration; it is not yet the endpoint the chatbot should use when the design requires Gateway policies.
Reference: Register the Integration as an Agentic AI Tool and Enable MCP for the Project.
06
Register the Project MCP Server in MCP Gateway
The project MCP server exposes the registered tools. Gateway becomes the managed entry point for the existing chatbot. In the configuration, you are telling Gateway which server it should connect to and what security policy it must use for that connection.
Console navigation — define the managed MCP server
OIC → Projects → select the project in which Gateway is configured → left toolbar → MCP Gateway → MCP servers → Add.
- Enter a descriptive server Name, such as
invoice-project-server-dev. This is a tutorial label, not a required product identifier. - Review the generated Identifier and provide a description of the tools the server contains.
- Select Add to open the MCP connection configuration page.
- Enter the actual project URL in MCP Endpoint.
- Select the appropriate security policy for the downstream connection.
- Complete the fields required by the selected policy, then select Test.
- Resolve any error, save the configuration and inspect the discovered tools.
Security policy selection matters. Oracle documents OAuth 2.0 Client Credentials, OAuth using JWT User Assertion, and No Security Policy for managed MCP server connections. The No Security Policy option adds no downstream authentication and is not suitable for a sensitive public traffic path.
| Managed-server policy | What you configure | Use and caution |
|---|---|---|
| OAuth 2.0 Client Credentials | Access Token URI, Client ID, Client Secret, Scope and other fields required by the editor. | Authenticates the configured client. It does not by itself prove that the original end user's identity reaches Fusion. |
| OAuth using JWT User Assertion | Access token endpoint, signing key alias, scope and applicable issuer, subject, audience and signing-key identifier values. | Use when following the documented user-identity propagation design and the receiving authorization server trusts the asserted identity. |
| No Security Policy | No downstream authentication is added by that policy. | Do not use for sensitive public traffic that requires authenticated downstream access. |
If using JWT user assertion, Oracle's guide identifies additional configuration values and a signing-key trust path. Do not paste sample usernames, client IDs, certificate identifiers or scopes from documentation into your tenancy. Obtain the values from your own application registration and identity-domain configuration.
When the connection test succeeds, confirm that the tools displayed in the discovered inventory are the tools expected for this project. A successful test verifies that the configured route can connect and discover metadata; it does not demonstrate that every tool is authorized for every user or that a downstream invoice can be created.
Reference: Define MCP Servers to Manage.
07
Configure Tool Filters and Business Policies
Gateway policies have different responsibilities. A tool filter selects which tools are discoverable through the managed-server route. A business policy evaluates rules for selected tools before the request is sent to the MCP server. A PII policy handles configured sensitive data in selected request or response scopes.
These mechanisms should not be described as though they all inspect every request in the same way or enforce user-specific business roles automatically.
Create a tool filter.
Console navigation — tool-filter policy
OIC → Projects → select the Gateway project → MCP Gateway → Security policies → Add → Tool filter.
- Enter a descriptive name and review the generated identifier.
- Select Add to open the tool-filter configuration.
- From MCP server, choose the managed project server.
- Select Include Tools and select only the identifiers that should be discoverable through this filter.
- Select Save.
- Later, attach the correct filter to the Gateway's managed server and verify the effective configuration.
For the initial safe exercise, expose the permitted read tools first. Add the invoice-creation tool only after the identity and confirmation controls have been reviewed. If another Gateway needs a different set of tools, use the appropriate filter for that managed server and Gateway.
Oracle documents the tool filter as a discoverability control; its scope is a selected MCP server and its enforcement point is not equivalent to a per-user authorization decision. Test both discovery and attempted direct invocation of an excluded tool. Also test alternate routes to the underlying project server and integration endpoints.
Create a business policy where an extra Gateway-level rule is useful. For example, a nonproduction policy might reject invoice-creation requests with an amount exceeding a configured pilot threshold. Oracle's editor supports generated JavaScript rule bodies, manual changes, the allow() and deny() contract, and Validate Syntax.
The field binding in the following example is explicitly illustrative. Use it only after confirming that the selected tool's Tool Payload binding actually exposes the invoice amount as input.invoiceAmount.
// Illustrative rule only: verify the actual Tool Payload binding first.
const amount = Number(input.invoiceAmount);
if (!Number.isFinite(amount) || amount <= 0 || amount > 10000) {
deny("Invoice amount is outside the configured pilot limit.");
} else {
allow("Invoice amount passes the Gateway limit.");
}
In the business-policy editor, select the MCP server and tool, enter the rule or generate an initial rule through AI Assist, inspect the actual payload fields, select Validate Syntax, correct any displayed errors and select Save. The monetary limit is fictional and must not be treated as a real business rule.
A successful syntax check does not prove business correctness. Test amounts below, at and above the limit, malformed input and missing fields. The OIC integration must independently enforce authoritative invoice validation; the target system must still apply its business rules.
What about PII detection? A Personally Identifiable Information policy can inspect configured fields and block or redact detected information. Oracle's current configuration guide identifies the OCI Language compartment, detector/pattern configuration, enforcement scope, request/response direction, selected fields and the chosen action as parts of policy setup.
Apply a PII policy only after deciding which input and output fields should be inspected. Redacting fields needed for invoice matching may break legitimate processing. PII detection does not inspect a separate initial application-to-LLM request, and it is not comprehensive prompt-injection or data-loss prevention.
Reference: Create Security Policies for MCP Servers and Create Business Policies for MCP Servers.
Safety Check — exposure is not authorization
Risk → A filtered-out write tool or a rule described in natural language may be mistaken for complete authorization.
Control → Test the filter, business rule, direct invocation and downstream target permissions separately. Keep authoritative validation in the integration and target system.
Remaining risk → A bypass route or incorrectly scoped permission may still permit an action unless separately identified and tested.
08
Create, Assign and Activate MCP Gateway
At this point, the project MCP server is enabled, its connection is configured, and the required security/business policies exist. Gateway still needs to be created, assigned the managed server and policies, and activated.
Console navigation — create the Gateway
OIC → Projects → select the project → left toolbar → MCP Gateway → MCP gateways → Add.
- Enter a descriptive Gateway name and description.
- Select Create.
- Open the Gateway configuration and assign the intended managed MCP server.
- Attach the intended security and business policies to the applicable server.
- Review policy order and scope in the actual editor, then save the configuration.
- Review all exposed tools before activation. Exclude tools not approved for the intended runtime.
Activate the Gateway.
Console navigation — activate
OIC → Projects → select the Gateway project → MCP Gateway → select the Gateway → Actions → Activate.
- Select the appropriate tracing level.
- Select the intended authorization mode.
- Review any required authorization configuration and ensure the selected client application grants the required resource/audience and scopes.
- Select Activate.
- Verify the resulting Gateway state and the actual authorization details presented by the configured environment.
Oracle documents two Gateway authorization choices. Dedicated Gateway authorization has a Gateway-specific audience and scopes and requires a confidential application configured with client credentials. OIC integration authorization uses the broader instance authorization model. The correct choice depends on the required identity flow and isolation requirement; do not assume the two choices are equivalent.
The dedicated authorization model is useful when clients should have access to a particular Gateway rather than inheriting broader instance authorization. But if user identity propagation is required, the selected grant and downstream propagation flow must be confirmed explicitly. A client-credentials token by itself identifies the client application, not the interactive user.
Obtain the actual Gateway URL.
Console navigation — Gateway Run details
OIC → Projects → select the project → MCP Gateway → select the Gateway → Actions → Run.
Record the Gateway URL displayed in the run details panel. Give this URL to the team responsible for configuring the existing chatbot's MCP client, together with the verified authorization mode and associated resource/scope instructions.
Do not send the project MCP server URL to the application when the intended design requires the client to pass through Gateway. Keep both URLs separately documented.
For Gateway tracing, Oracle documents Production tracing without request/response payload capture and Audit tracing with payload capture. The documented retention figures are 32 days for Production activity and eight days for Audit activity at the time checked. Revalidate retention before establishing operational commitments; Audit payloads can contain sensitive data.
Reference: Create and Configure an MCP Gateway, Activate an MCP Gateway and Get the URL for the MCP Gateway.
09
Propagate the Authenticated User's Identity to Fusion ERP
This is the critical part when an invoice must be created under the originating employee's identity rather than under a shared technical account.
A JWT user assertion is a signed token used in an OAuth flow to obtain access to a protected service on behalf of a user, subject to the authorization server's configured trust. It is not itself the same thing as an ordinary user session or the final downstream access token.
Oracle's documented user-identity-propagation pattern covers the MCP Gateway, project MCP server, tool-registered integration and endpoint system. It depends on the OAuth using JWT User Assertion security policy and explicit mapping of the trigger Subject to the outbound invoke Subject.
Understand the identity hops.
| Hop | What must be true | Evidence |
|---|---|---|
| User → existing chatbot | The application has authenticated the user and can associate the proper token with that user's session. | Validated caller/session context without exposing tokens in the browser or model prompt. |
| MCP client → Gateway | The caller token is accepted by the selected authorization mode and has the expected audience and scopes. | Authorized tool discovery and invocation tests. |
| Gateway → project MCP server | The managed-server connection uses the configured security policy and any required assertion-signing trust. | Connection test and evidence for actual runtime identity propagation. |
| Integration → Fusion | The REST Adapter invoke has the appropriate JWT user-assertion configuration and the source Subject is mapped to the target Subject. | Target audit evidence identifies the expected user and enforces the user's privileges. |
Step A — create and trust the signing key. Use your organization's approved key-generation and certificate process. For a nonproduction test, the identity and OIC administrators should create designated signing material and a corresponding public certificate. The private signing key must stay in the approved secure location and must never be copied into chatbot prompts, screenshots or source control.
Oracle's published procedure requires a signing key uploaded on the OIC Certificates page, together with JWT header and payload JSON files for the REST Adapter invoke connection. The receiving identity-domain application must trust the corresponding public certificate as required by the configured assertion grant.
Console navigation — upload the OIC signing key
Oracle Integration → Settings → Certificates.
- Select Upload.
- Enter a purpose-specific alias for the nonproduction signing key.
- Select the documented signing-key type and the file format supported by the actual upload page.
- Supply a password only if required by the selected format.
- Complete the upload and verify the alias is listed.
Use the current Oracle certificate upload instructions. The exact upload format and whether the key file requires a password depend on the key material and current console controls.
Step B — configure the managed MCP-server assertion policy. Return to the managed MCP server created in Section 06. Select the documented JWT user-assertion security policy. Configure the endpoint's required access token URI, signing-key alias and scope. Supply issuer, subject, audience and signing-key ID values as required by the actual screen and trust relationship.
For values connected with a confidential application, use that application's actual client ID, token endpoint and registered public-certificate identifier. The user subject must be governed by the supported identity-propagation configuration rather than an editable business argument supplied by the LLM.
Step C — configure the Fusion REST Adapter invoke connection. Open the integration that calls the Fusion Payables API. Configure its invoke connection with the documented OAuth using JWT User Assertion policy, using the token endpoint, relevant client details, uploaded signing-key alias, scope and JWT header/payload templates required by your target identity domain.
Do not copy timestamp values, issuer identifiers, client identifiers or user subjects from documentation examples. Generate valid assertion claims according to the receiving OAuth server's requirements and verify the expected audience and key identifier.
Step D — map the security Subject.
Console navigation — map source identity to target identity
OIC → Projects → select the project → Integrations → open the relevant tool integration → open its design canvas → open the mapper between the REST trigger and the outbound invoke.
- Inspect the REST trigger's security properties and locate Subject where available for the configured policy.
- Inspect the outbound invoke connection's security properties and locate the target Subject.
- Map the source trigger Subject to the outbound invoke Subject.
- Save the mapping, validate the integration and activate the required version.
- Test using two authorized synthetic users and examine actual downstream identity evidence.
The mapping is what tells OIC to propagate the source identity. Oracle's documentation explicitly states that without this mapping the originating user cannot be received by the endpoint through this propagation mechanism.
This does not mean that simply mapping a text field containing an employee name establishes an authenticated identity. The source Subject must be the security property provided by the authenticated execution context, not a normal JSON field that the chatbot can change.
Step E — verify the final user's permissions. Fusion ERP must recognize the propagated user and apply the privileges associated with that user. If the user lacks the permission to create a Payables invoice, the request should be rejected. Do not silently fall back to a privileged shared service identity unless the organization has explicitly approved a different security architecture.
Safety Check — identity propagation
Risk → A shared application token, fixed Subject or incorrect mapping can cause several employees' actions to run under an unintended identity.
Control → Configure the documented JWT user-assertion flow, map the authenticated trigger Subject to the invoke Subject and test two users against the real target authorization model.
Remaining risk → Identity propagation cannot grant appropriate business rights if Fusion lacks the user or has incorrect privileges, and it does not eliminate alternate access paths.
Reference: Use Case: Propagate User Identity for MCP Tool Invocations.
10
Trace the Live Request and Response
Now connect the configured OIC path to the existing chatbot. The application team supplies the actual Gateway endpoint, OAuth configuration and exposed-tool metadata. The OIC team verifies that the configured tools are available, that the selected request is routed correctly and that the integration response is mapped back to the caller.
First, test discovery without creating a transaction. Use the existing application's MCP client or an approved MCP test client such as Postman, configured for MCP and the appropriate OAuth mode. Connect to the actual Gateway endpoint and inspect the returned tool inventory.
For the project MCP server, Oracle documents Streamable HTTP. The required URL is available in the project details. For Gateway, use the URL displayed in the Gateway's Run details. Do not substitute one endpoint for the other.
Next, invoke the read tool. Select the actual identifier for the registered PO lookup tool. Use synthetic test data and confirm that the invocation produces the intended response through Gateway and OIC.
Worked example — read a purchase order before creation
User message:
“Please create an invoice of 5,000 USD against PO-9090.”
The runtime determines that it needs PO information first and asks the MCP client to invoke the registered lookup tool.
Logical tool arguments:
{
"purchaseOrderNumber": "PO-9090"
}
The Gateway routes the tool call through the configured project MCP server. The registered OIC integration receives the arguments, performs its lookup under the configured security model and returns the normalized result. That result returns through the server and Gateway to the MCP client and then to the existing application.
A successful lookup is not an invoice-creation result. The application next checks whether required invoice fields are missing, displays the relevant facts and obtains confirmation before invoking the write operation.
Then test the invoice creation path. Only after the PO lookup and invoice preview are validated should a nonproduction test invoke the registered create tool. The application must enforce confirmation independently of the LLM's answer. The integration should validate the canonical request again and call the correct Fusion Payables resource.
For supplier invoice creation, the documented Payables resource family is based on /fscmRestApi/resources/11.13.18.05/invoices. Receivables invoices are customer billing transactions and use a different resource. Confirm the endpoint and required header/line fields in the Financials REST API documentation applicable to the target release and tenant before implementing a write request.
A creation request usually requires actual supplier, business-unit, invoice number, date, currency and matching details in addition to the amount and PO number. The exact required attributes depend on the target operation and tenant configuration. The application and integration must not fabricate missing values.
Confirm the actual downstream result. Capture the response from the integration and verify whether it contains a valid target invoice identifier and status. If the target call times out, do not assume the invoice was not created. Reconcile using the integration's correlation/request identifier and supported target lookup before retrying.
A successful MCP response is not by itself proof that the invoice was approved or paid. Return only the actual state established by the Fusion response or subsequent status lookup.
For tracing, correlate the application request to the Gateway activity, OIC integration execution and Fusion result using approved correlation identifiers. Avoid recording access tokens, signing keys, passwords or unnecessary full business payloads. Audit tracing should only be enabled when the associated payload exposure and retention are acceptable.
11
Prove Role and Permission Enforcement
A valid OAuth token does not automatically mean that its holder can create every invoice. The access path must distinguish the caller's authorization to use Gateway, permission to invoke the relevant tool, and the target user's actual business privileges.
Use at least three synthetic test identities:
| Test identity | Test case | Required evidence |
|---|---|---|
| Invoice creator A | Retrieve an authorized PO, confirm the exact invoice preview and create a valid invoice in the nonproduction environment. | The intended user identity is propagated and the actual target result identifies the created invoice. |
| Invoice creator B | Repeat using a separate session and another permitted PO. | The second identity is not replaced by the first user's session or a shared unintended principal. |
| Read-only user | Request invoice creation, attempt a direct invocation and try to reuse a creator's preview identifier. | The write is denied and the target contains no unintended invoice record. |
Separate authorization responsibilities.
- OAuth/Gateway authorization: determines whether the caller's token can access the selected Gateway under its configured audience, scopes and authorization mode.
- Gateway tool filter: determines which tools are exposed through the managed-server filter. It is not a dynamic per-user row-level authorization engine.
- Existing application's role check: determines whether the application allows the logged-in user to initiate the create action. Do not infer roles from untrusted tool arguments.
- OIC integration: validates the business request and enforces any required integration-side authorization logic and identity mapping.
- Fusion ERP: enforces actual target privileges, business-unit data access, supplier/PO matching and Payables business rules.
If OIC must independently enforce a particular employee role, implement an authoritative check using a trusted identity/authorization source or rely on the supported target authorization model. Do not assume that Gateway's general caller authorization automatically implements your organization's business roles at tool granularity.
Test a missing, expired or wrong-audience token; an excluded tool; a read-only user's attempted write; an inaccessible PO; an invalid invoice amount; and an uncertain result after a downstream timeout. For denied requests, verify both the denial evidence and the absence of an unintended business record.
Safety Check — authorization must be demonstrated
Risk → A user may appear to be blocked in the chatbot while an alternate route can still reach the underlying operation.
Control → Test the Gateway route, direct project MCP endpoint and integration endpoint separately. Verify target audit evidence and the absence of writes after denials.
Remaining risk → Unidentified alternate permissions or identity mappings may permit access until tested and remediated.
12
Troubleshooting: Identify the First Failed Layer
Start from the earliest point at which observable evidence differs from the expected request path. A 401, 403, HTTP 5xx, MCP error or business validation error does not have one universal cause.
| Symptom | Targeted check | Minimal correction and retest |
|---|---|---|
| Chatbot sends text, but no Gateway activity appears. | Check whether the application runtime selected a tool and whether its MCP client uses the Gateway URL rather than the project URL. | Correct the external client route/configuration and repeat a read-only tool call. |
| OAuth token is rejected by Gateway. | Verify selected authorization mode, audience, scopes, issuer, expiration and grant configuration. | Use the exact token and client configuration required by that Gateway mode; retest discovery and invocation. |
| Gateway connects but expected tools are missing. | Check integration active state, project membership, tool registration, MCP enablement, server discovery and filter selection. | Correct the missing lifecycle step, save or reactivate where needed, and repeat discovery. |
| Managed-server test fails. | Check endpoint, transport, selected authentication policy, token endpoint, key alias, audience and scopes where applicable. | Correct the failed connection setting and retest before changing unrelated policies. |
| Excluded tool is still callable through another route. | Check Gateway filter assignment and separately inspect direct project-server and integration access. | Correct the relevant grants or access design and repeat every affected path test. |
| JWT assertion or downstream authentication fails. | Check signing-key alias, certificate trust, issuer, subject, audience, validity period, token URI and scope. | Correct the relevant trust/configuration value, obtain a new token and test using a synthetic user. |
| Fusion receives the wrong user. | Inspect the trigger's security Subject, outbound invoke Subject mapping, configured identity flow and target audit evidence. | Repair the mapping or trust configuration and repeat the test with two users. |
| Fusion rejects the invoice. | Inspect the sanitized target error, required fields, PO matching, supplier site, currency, date and target privileges. | Correct and revalidate the business request or authorization, then retest with synthetic data. |
| Create call times out. | Inspect the integration execution, correlation/request ledger and target record using the approved reconciliation process. | Determine whether the target committed before retrying. Do not assume timeout means no invoice exists. |
Keep diagnostic evidence separate by layer. For each test, record the application request reference, Gateway operation, OIC integration execution identifier and target result where available. Never include tokens, client secrets, private keys or passwords in the diagnostic bundle.
13
Common Mistakes
Mistake 1 — expecting OIC to receive every chat message automatically. Gateway receives MCP requests from a configured client. The application runtime must decide to invoke a tool, and its MCP client must send that invocation to the Gateway endpoint.
Mistake 2 — giving the chatbot the project URL instead of Gateway. The project server URL exposes the project's registered tools. If the architecture requires Gateway policies, configure the client to use the actual Gateway URL from Run details.
Mistake 3 — confusing client authentication with employee identity. A client-credentials token is not automatically an interactive user's identity. Verify the caller grant and downstream JWT user-assertion configuration separately.
Mistake 4 — assuming a tool filter enforces every role. A filter determines which tools are exposed through the selected managed-server route. It does not automatically implement dynamic user-to-business-unit authorization or prevent every direct-access route.
Mistake 5 — treating descriptions as enforced security. A tool description can guide the model. It cannot replace authorization checks in the application, the integration and the target system.
Mistake 6 — treating an uncertain create response as a failed create. A timeout can happen after the target has committed. Reconcile before retrying to avoid duplicate invoices.
Mistake 7 — reporting a transaction as successful based on model text. Return success only after the integration has a verified target result. A proposed function call, an accepted MCP request and an actual invoice creation are different events.
14
Enterprise Rollout
Start with a controlled read-only test. Verify that the live chatbot discovers the intended tools through Gateway, invokes a synthetic PO lookup, receives the expected data and respects the authenticated user's permissions. Add the creation tool only after the caller identity, target mapping, confirmation process and recovery handling have been demonstrated.
Assign ownership clearly.
- Application team: owns the live chatbot's MCP client configuration, application session and confirmation flow.
- Identity administrator: owns the confidential client application, grants, scopes, roles, signing-key trust and relevant identity-domain configuration.
- OIC team: owns integration eligibility, registration as tools, project MCP server configuration, Gateway policies, Subject mapping and activation.
- Fusion ERP team: owns API compatibility, Payables privileges, supplier/business-unit access and target business rules.
- Operations/security: owns observability, credential rotation, incident handling, retention and authorization-change verification.
Record each acceptance test as Passed, Failed or Not Executed. Include the expected result, actual result, sanitized evidence and owner. Never mark a proposed test as passed merely because its configuration is documented.
The pilot should include token failures, correct and incorrect audiences/scopes, tool discovery, excluded-tool invocation, two-user identity propagation, read-only denial, invalid invoice inputs, direct-access bypass, duplicate requests, target timeouts and certificate rotation. Production rollout requires the relevant critical tests to pass and the organization's security and operational owners to accept the remaining risks.
15
❓ FAQ
Q1. Does clicking Send directly invoke an OIC integration?
No. The existing application's runtime interprets the message. When an OIC tool is needed, its MCP client invokes that tool through Gateway, which routes the request to the project's MCP server and registered integration.
Q2. Should the live chatbot connect to the project MCP server or MCP Gateway?
When Gateway governance is required, configure the MCP client with the actual Gateway URL obtained from the Gateway's Run details. The project MCP server has a separate URL used by Gateway to reach the registered OIC tools.
Q3. Does Gateway automatically know the employee's application role?
Not merely because the chatbot is logged in. The caller token and Gateway authorization mode determine whether the client can access Gateway. Application roles, tool exposure, integration authorization and Fusion privileges must be enforced at their respective layers.
Q4. Does user identity automatically propagate from the chatbot to Fusion ERP?
No. The chosen OAuth flow, Gateway and managed-server security configuration, JWT user assertion, signing-key trust and trigger Subject-to-invoke Subject mapping must be configured and tested. Fusion must recognize the resulting principal and enforce its privileges.
Q5. Does a successful tool call guarantee that a Payables invoice was created?
No. The invocation can fail in OIC or Fusion, and a timeout can leave the outcome uncertain. Report creation success only after the target result is verified and reconcile an uncertain outcome before retrying.
16
🔗 References & Further Reading
Specific endpoint values, role assignments and supported authorization combinations remain subject to the actual tenancy and release.
Gateway architecture and authorization
Secure and Manage MCP Servers with MCP Gateway
Why an MCP Gateway Is Required
Activate an MCP Gateway
Get the URL for the MCP Gateway
Project MCP server and tool registration
FAQs for Projects as MCP Servers
Register an Integration as an Agentic AI Tool
Enable MCP for the Project
Get the URL for the MCP Server
Discover Integrations as Tools from MCP Clients
Define MCP Servers to Manage
Security, business policies and identity propagation
Create Security Policies for MCP Servers
Create Business Policies for MCP Servers
Business and Security Policies for MCP Gateway
Use Case: Propagate User Identity for MCP Tool Invocations
Create and Activate the Client Application
Release and downstream API
Oracle Integration September 2026 (26.10) Release Notes
Oracle Fusion Financials REST API Reference, 26D
Verify the Payables invoice create and status operation schemas for the target tenant before implementation.
Oracle and other vendor names belong to their respective owners.
17
📝 Summary
The Send button does not itself trigger OIC. The existing application's runtime decides when a tool is needed and asks its MCP client to invoke the tool through the configured OIC MCP Gateway URL.
Gateway authenticates and authorizes the caller according to its selected mode, applies its applicable policies and routes the invocation to the configured project MCP server. The project server exposes registered OIC integrations as tools, and the selected integration performs the actual business workflow.
When the user's identity must reach Fusion ERP, the OAuth grant, managed-server security policy, JWT assertion trust and Subject mapping must be configured and verified. Fusion must then enforce the user's actual Payables rights.
Start with a read-only lookup, trace the request through each layer, prove the identity mapping with two users, and only then test invoice creation using synthetic records and explicit confirmation. The target response—not the model's wording—determines whether the transaction succeeded.
Keep every hop observable, every permission intentional and every reported result supported by evidence.

Comments
Post a Comment