Oracle Integration MCP Gateway Explained: OIC Architecture, MCP Tools, and Trust Boundaries
Oracle Integration 3 (OIC) developers already know how an integration accepts a request, applies mappings and orchestration, invokes an application, and returns a result. The new question is how an AI application discovers which business capabilities it may call—and how the enterprise governs that access.
The Model Context Protocol (MCP) standardizes a way for an AI application to discover and request tools. Oracle Integration MCP Gateway adds a managed control point in front of selected MCP servers, so access to existing integrations and approved third-party tools can be governed through a common route.
📘 Before You Begin: MCP Fundamentals
This tutorial focuses on Oracle Integration MCP Gateway. If you are new to MCP, start with the MCP fundamentals series to learn the basic protocol concepts, then return here for the gateway architecture and implementation walkthrough.
Imagine a procurement assistant asked, “What is the status of purchase order PO-1048?” The answer should come from a real business workflow, not the language model's guess. The assistant needs a clearly described tool, a compatible protocol connection, an approved identity, and a path to the integration that queries the source system. The gateway helps govern that path; it does not replace the integration's business logic or the target application's authorization.
📑 In This Post
- Why corporate AI agents need governed OIC access
- MCP hosts, clients, servers, and tools
- Tool discovery and invocation: tools/list and tools/call
- Connections, transport, and compatibility
- Project MCP server vs MCP Gateway vs OCI API Gateway
- Trace a request from AI client to business application
- Find and follow this architecture in OIC
- Enterprise rollout: a safe starting point
- Common architecture mistakes
- FAQ
- References and further reading
🔀 Quick Comparison
| Component | Main responsibility | Think of it as |
|---|---|---|
| OIC project MCP server | Makes eligible integrations registered as agentic AI tools available through that project's MCP endpoint. | The capability counter for one OIC project. |
| Oracle Integration MCP Gateway | Provides a governed MCP endpoint for selected OIC and approved third-party MCP servers, using configured authorization and policies. | A managed checkpoint before selected MCP capabilities are reached. |
| OCI API Gateway | Publishes and governs configured HTTP/REST API routes to backend services. | An API front door—not a synonym for the MCP governance layer. |
01
Why Corporate AI Agents Need Governed Access to OIC Integrations
An ordinary integration is usually invoked by a known caller that was configured to use a particular endpoint. An AI assistant adds a decision step: a model interprets the user's request and may propose one of several available tools. That flexibility is useful, but it creates a governance question: which tools may this caller discover and invoke, under which identity, with which inputs, and with what evidence afterward?
MCP stands for Model Context Protocol. It defines a shared way for a client to communicate with a server that exposes capabilities such as tools. A tool is a named operation with a description and an input contract; it might check an order, retrieve a supplier profile, or submit a draft request. MCP standardizes the exchange, but the protocol alone does not grant business permission to perform that operation.
🟠 Analogy: a building directory is not an access badge
A directory can tell an employee which department handles purchase orders. It does not prove that the employee may enter the records room or approve a purchase. Similarly, a tool description helps the model understand a capability; identity checks, gateway controls, integration logic, and target-system permissions determine whether a request is allowed to proceed.
Without a common control point, each assistant may need its own connection details, server list, credentials, filtering decisions, and operational logging. As the number of clients and servers grows, these decisions can diverge. Oracle Integration MCP Gateway is intended to provide a centrally governed path to selected OIC and approved third-party MCP servers. Depending on the configured design, its controls can include caller authorization, tool filtering, business and security policies, downstream credential handling, routing, and tracing.
🛡️ Safety Check
Risk: The model can propose a tool that is technically available but not appropriate for the caller or business task.
Control: Expose the minimum necessary tools, authorize the client at the gateway, apply relevant policies, and enforce authoritative validation and permissions inside the integration or target application.
Remaining risk: A gateway reduces fragmented access decisions; it cannot guarantee that every input is safe or that another direct route to a backend does not exist.
An agent needs to use business workflows across OIC projects or approved external MCP servers and your organization needs clearer control over access, policy enforcement, and usage evidence.
02
MCP Hosts, Clients, Servers, and Tools Explained for OIC Developers
The simplest way to learn MCP is to separate the application that coordinates the assistant from the protocol connection and the business workflow. The names are related, but they do not describe the same object.
| Term | What it does | Procurement example |
|---|---|---|
| MCP host | The application environment that manages the model interaction, user experience, permissions, and one or more MCP clients. | The company's procurement assistant application. |
| MCP client | The protocol participant that connects to a particular MCP server, discovers its advertised tools, and sends MCP requests. | The assistant's MCP connection configured for the gateway endpoint. |
| MCP server | A service that publishes MCP capabilities and handles protocol requests for them. | An OIC project's MCP endpoint or an approved supplier-score MCP service. |
| MCP tool | One named operation with metadata and an expected input schema. | get_purchase_order_status, an illustrative name only. |
| OIC integration | Executes the enterprise workflow and communicates with the target application through its configured connections and adapters. | Validates the purchase-order identifier, queries the back-end, and maps the result. |
| Identity provider / authorization server | Issues tokens according to the configured OAuth grant, scopes, client, and trust settings. | Issues the token that the MCP client presents to the intended gateway resource. |
In this architecture, the host and model decide which available capability appears relevant; the client sends the protocol request; the gateway applies its configured governance; and the downstream server and integration perform the actual business operation. These are different responsibilities. A model proposing a tool call is not the same event as a client transmitting it, and neither event proves that the transaction is authorized.
For an OIC project to provide integrations as MCP tools, Oracle documents a project-based process: an eligible integration is registered as an agentic AI tool, MCP is enabled for the project, and the project receives its own MCP server URL. Only integrations registered as tools are discoverable from that project's MCP server. Oracle's project FAQ documents tools/list and tools/call as the supported operations for this project MCP-server route.
🟠 Analogy: the host is the dispatch desk; a client is one phone line
The dispatch desk coordinates the request and chooses which service to contact. Each phone line connects to a particular service. The MCP server answers requests for the capabilities it offers. The analogy describes the roles only; real trust depends on identity, endpoint configuration, and enforcement controls—not on the job titles.
Reviewing an architecture sketch or debugging a connection. First ask which host, client, server, gateway, integration, and target system owns the step that failed.
03
MCP Tool Discovery and Invocation: Understanding tools/list and tools/call
A tool-using assistant needs two distinct things: a description of the capabilities available to it and a way to request the execution of one selected capability. MCP separates these into discovery and invocation.
Discovery: tools/list. The client asks the connected server for the tools available through that connection. Tool metadata commonly includes a name, description, and input schema. The name is the identifier used for the call; the description helps a model judge when the tool may be relevant; the schema communicates the shape of acceptable arguments. For an OIC project MCP server, Oracle documents this discovery operation.
Invocation: tools/call. After deciding a tool is relevant, the host/model proposes the arguments. The MCP client sends the protocol request to the server for that named tool. The request then encounters the applicable gateway/server checks and downstream business workflow. A returned tool result becomes input to the host, which interprets it and prepares a user-facing answer.
✅ Worked example: discover, call, and explain an order-status tool
This is an original, fictional metadata example for learning. The tool name and fields are not claims about a tool already configured in your OIC tenant.
| Discovered item | Illustrative value |
|---|---|
| Tool name / identifier | get_purchase_order_status |
| Description | Returns the status of one purchase order for which the caller is permitted to obtain information. |
| Input schema | Required string field: purchaseOrderNumber. |
| Proposed argument | purchaseOrderNumber = "PO-1048" |
| Illustrative business result | Status: Awaiting shipment. Last updated: 2026-10-16. |
- The MCP client discovers the tool and reads its name, purpose, and required input. A description is guidance to the model, not an authorization rule.
- The user asks about PO-1048. The host/model proposes the discovered tool and argument; the client—not the model directly—sends the MCP invocation.
- The gateway evaluates the configured access and policy controls, then routes an allowed request to the registered downstream MCP server. The project's tool invokes its associated OIC integration.
- The integration's result is returned through the MCP path. The host uses the result to form an answer. The sample result above is illustrative, not observed tenant evidence.
Keep three different result layers distinct. An HTTP response describes the transport-level exchange. An MCP/JSON-RPC response carries a protocol-level result or error. The tool's content may describe a business outcome, such as “not found” or “awaiting shipment.” A tool can complete successfully at the protocol layer and still report a business rejection. Conversely, an HTTP authorization failure may happen before the server ever processes a tool call.
🛡️ Safety Check
Risk: A plausible tool name or model-generated argument is treated as proof that the operation is safe and permitted.
Control: Use the actual discovered name and schema, validate arguments in the OIC integration, apply authorization at the relevant layers, and test both expected and rejected inputs.
Remaining risk: A valid schema cannot establish that the user is entitled to a particular record or that the business data returned is correct.
Defining tool contracts or tracing why a model selected a capability. Check, in order, the user's request, the discovered identifier and schema, the arguments proposed, the server response, and the business result.
04
MCP Connections, Transport, and Compatibility in an OIC Implementation
A protocol defines the meaning and structure of messages; a transport defines how those messages travel between the client and server. A useful comparison is a business document versus the delivery method: the document's fields keep their meaning whether it travels through one delivery channel or another, but the sender and recipient still need to support the chosen channel.
The MCP specification defines JSON-RPC-based messages and standard transports. The current MCP reference describes Streamable HTTP as using HTTP POST requests to a single MCP endpoint, with responses delivered as JSON or a request-scoped server-sent events stream. That is protocol-level context. For the direct OIC project MCP-server route, Oracle specifically documents Streamable HTTP as the transport to use from a compatible MCP client. That Oracle-specific instruction is the one to follow for that route.
Do not assume that every MCP implementation supports every transport or every revision of the specification. A client configured for a locally launched server over standard input/output (stdio), for example, should not be assumed to connect directly to a managed OIC endpoint by simply pasting in a URL. Likewise, a third-party MCP server's availability does not alone prove that its transport, authentication method, network path, or protocol features are supported in the selected gateway configuration.
For the fictional procurement example, the assistant's MCP client is configured with the gateway endpoint when the intended design is to use gateway governance. A separate, direct connection to a project's MCP server is useful in a controlled test to isolate the source server and integration from gateway-related behavior, where permitted. It must not quietly become an unreviewed production bypass around the gateway.
| Compatibility question | Evidence to check | Why it matters |
|---|---|---|
| Endpoint | Confirm whether the client needs the gateway URL or the project's MCP server URL. | These addresses represent different entry points and governance paths. |
| Transport | Verify the transport specified by Oracle for the selected route and supported by the client and downstream server. | A matching URL cannot compensate for a mismatched transport. |
| Protocol revision | Check the actual client and server documentation, including supported lifecycle and capabilities. | The public MCP specification evolves; current protocol features are not automatically supported by every OIC endpoint. |
| Authentication | Verify the grant, token audience, scopes, and security policy for that precise hop. | A token accepted at one endpoint may be inappropriate for another resource. |
| Network reachability | Confirm DNS, TLS certificates, outbound connectivity, and any required network restrictions for the deployed server. | A valid protocol and token cannot resolve a blocked or incorrectly addressed network route. |
The correct design therefore has a small compatibility contract: client ↔ intended MCP endpoint; endpoint ↔ supported protocol and transport; endpoint ↔ configured security policy; downstream server ↔ reachable and trusted destination. Record these separately. Do not copy a transport, header, handshake sequence, or token scope from a different client/server combination without verifying it for the environment at hand.
🛡️ Safety Check
Risk: A protocol example copied from another MCP implementation is treated as a verified OIC request sequence.
Control: Use Oracle's guide for the precise endpoint, the client's supported MCP transport/revision, and the selected gateway/server security documentation. Test with non-sensitive data and capture redacted error details.
Remaining risk: Compatibility can change after client, server, or service upgrades; a successful discovery test does not prove every tool call or error path works.
A connection fails before tools are listed or behaves differently with another client. Confirm endpoint, transport, protocol support, token, network path, and downstream-server configuration before changing business logic.
05
OIC Project MCP Server vs OIC MCP Gateway vs OCI API Gateway
These components can all appear in an enterprise integration architecture, but they answer different questions. The project MCP server answers, “Which registered OIC integration tools does this project expose through MCP?” The Oracle Integration MCP Gateway answers, “Which selected MCP servers and tools can be reached through this governed MCP entry point?” OCI API Gateway answers a different API-management question: “Which configured HTTP/REST routes should be published and protected as API endpoints?”
| Question | Project MCP server | OIC MCP Gateway | OCI API Gateway |
|---|---|---|---|
| Primary interface | MCP endpoint associated with an OIC project. | MCP endpoint representing the selected gateway configuration. | Configured HTTP/REST API endpoint(s). |
| Main job | Expose integrations registered as agentic AI tools. | Govern access to selected MCP servers and tools. | Publish selected API routes and apply API-level controls. |
| Can it replace the integration? | No. The integration still runs the workflow. | No. It governs MCP access to a downstream server. | No. The published backend still handles the request. |
| Typical choice | A compatible MCP client needs access to tools from one project. | The organization wants centralized governance across selected MCP servers. | Consumers need published REST routes with API gateway controls. |
A gateway is an additional governance layer, not a mandatory extra compute instance. Oracle Integration MCP Gateway is a feature of Oracle Integration; the presence of an OCI Compute VM in an existing architecture does not turn that VM into the managed gateway. OCI API Gateway is also a separate product. Do not create either service just because the name contains “gateway”; start with the traffic and governance problem you actually need to solve.
Also distinguish the gateway endpoint from the downstream MCP server endpoint. The MCP client connects to the former when using the governed design. The gateway uses the latter to reach the server registered behind it. They have different recipients, security configuration, and potentially different credentials. Substituting one URL for the other makes the path unclear and can invalidate the intended controls.
✅ Worked example: choose the component from the requirement
Requirement A: One controlled assistant should query an OIC integration in a single project. A project's MCP server may provide the tool endpoint, provided its authorization and direct access are appropriate for the use case.
Requirement B: The enterprise wants a governed endpoint for purchase-order tools from an OIC project plus an approved third-party supplier-score MCP server. Evaluate OIC MCP Gateway for its selected-server and policy governance, after verifying third-party compatibility.
Requirement C: An external consumer needs a conventional REST endpoint with API routing controls. Evaluate OCI API Gateway against that REST requirement; do not describe it as the OIC MCP Gateway or assume it translates arbitrary REST traffic into MCP.
A proposed diagram contains more than one gateway or server type. Label each endpoint with its protocol, responsibility, owner, and caller instead of relying on a product name alone.
06
Tracing a Corporate Tool Request from AI Client to Business Application
This worked trace brings the concepts together. Assume a fictional nonproduction procurement assistant is allowed to read synthetic purchase-order information through an OIC integration. The gateway is already configured by the platform team for the selected OIC project MCP server. This is an architecture walkthrough, not a report of an executed deployment.
✅ Worked example: follow one read-only request
| Hop | Sender → recipient | What happens and who owns the control |
|---|---|---|
| 1 | MCP client → authorization server | The configured OAuth grant is used to request an access token. The authorization server issues a token only under its configured client, grant, scope, and trust rules. This is token acquisition—not yet the protected MCP request. |
| 2 | MCP client → OIC MCP Gateway endpoint | The client sends the MCP request to the gateway and presents the token intended for that resource. The gateway's configured authorization mode determines the audience and scopes to validate; the gateway then applies its relevant policies and tool-selection controls. |
| 3 | Gateway → registered OIC project MCP server | For an allowed tool, the gateway routes the invocation to the registered downstream server using its configured downstream security path. Do not assume that the inbound bearer token is automatically forwarded or is valid for this second recipient. |
| 4 | Project MCP server → registered OIC integration | The project exposes its registered integration tool. The OIC integration validates the input, performs the intended workflow, and invokes the target with its configured connection credentials or separately designed identity path. |
| 5 | Integration ↔ target application | The business application checks its own permissions and rules, returns the record/status, and does not rely on the language model as an authorization authority. |
| 6 | Target → integration → server → gateway → client | The business result returns through the response path. The MCP client passes the tool result to the host; the host interprets it and produces the answer shown to the user. |
The identity boundaries matter as much as the message flow. A client-credentials token normally identifies the configured client/service; it does not, by itself, prove which employee initiated the chat. If the use case requires downstream authorization as the interactive user, use a documented and deliberately configured user-assertion/propagation design and verify the target's audit evidence. Never infer that user identity passes through every hop automatically.
At the tool-selection stage, the model can propose get_purchase_order_status with a purchase-order identifier. The client sends the request; it does not ask the target application to trust a model's explanation. The integration should still reject malformed identifiers and should retrieve only records the authenticated execution path is permitted to access. A read-only lab can use a synthetic order and demonstrate the full return path before any write tool is contemplated.
For troubleshooting, label the failure with the layer where it occurred: token issuance, gateway authentication/authorization, tool discovery, gateway policy, downstream server connection, protocol request handling, OIC integration execution, or target-system authorization/business logic. An HTTP status alone is not enough to identify the cause. Correlate redacted client errors, available gateway traces, OIC integration instance evidence, and target audit records without copying secrets or sensitive payloads into logs or the article.
🛡️ Safety Check
Risk: A single access token or policy is assumed to secure every hop from the assistant to the business record.
Control: Document the audience, identity, credential source, and enforcement owner at each hop. Test the caller-to-gateway access separately from gateway-to-server access and integration-to-target authorization.
Remaining risk: Layered checks reduce exposure but do not rule out excessive permissions, compromised identities, application defects, or alternative direct routes.
Architecture sketch checkpoint
On a blank page, draw the six hops in the table above. For every arrow, write four labels: sender, recipient, credential/token or identity, and enforcement owner. Then circle the point where the tool is selected, the point where gateway policy is evaluated, and the point where the business application enforces record access. If you cannot identify one of these for a hop, record it as an unresolved design question rather than filling it in with an assumption.
Explaining the architecture to security, integration, and application teams. A good design makes the request path, response path, token recipients, and control owners explicit.
07
Find and Follow This Architecture in OIC
Connect the concepts to the console now. Milestones A–C provide a bounded setup path; D–E locate the policies and gateway that complete the architecture. Use a nonproduction instance, approved test credentials, and synthetic data. The integration must already work as a read-only REST-triggered workflow before tool registration. Obtain the required project and identity permissions through your normal corporate process.
The tool-provider project contains the integration. The project used for gateway management contains the downstream server registrations, policies, and gateway. They may be the same project or different projects in your chosen design; two projects are not a mandatory product requirement. Establish which project is used at each step.
Milestone A — Register the Existing Read-Only Integration
Task: Guided nonproduction setup
Start here: An active, not-yet-registered lab integration in a project, with a REST Adapter trigger using OAuth and JSON. If it is already registered, reuse its tool rather than creating a duplicate.
Navigation: Projects > selected tool-provider project > Integrations > integration Actions
- Select Projects in the OIC navigation pane.
- Open the project containing the approved read-only integration.
- Locate the integration under Integrations and confirm its active state.
- Open its Actions menu.
- Select Create agentic AI tool to open the initial tool panel.
- Review the initial name, identifier, and description. Explain the actual read-only purpose. Check these values before creation: the documented name and identifier cannot subsequently be changed.
- Select Create to open the tool details.
- Review the supported guidelines and parameter settings there; identify which inputs are visible and required.
- Select Save.
Milestone B — Locate the Project MCP Setting and URL
Task: Inspect existing configuration; enable it only in the approved lab if needed
Start here: The same tool-provider project. An authorized administrator has supplied the OAuth client configuration needed for later access tests.
Navigation: Projects > selected project > upper-right edit icon > Project details
- Select Projects and open the tool-provider project.
- Click the upper-right edit icon to display Project details.
- Inspect the Enable MCP server setting. If already enabled, retain it. If disabled and this lab is authorized for exposure, enable it.
- If you changed the setting, select Save changes.
- Reopen Project details using the edit icon and identify the project MCP server URL.
Expected result: Identify the project MCP endpoint without confusing it with a gateway URL. If enablement or a registered tool is missing, resolve that prerequisite before treating this as a usable server.
Milestone C — Register That Server for Gateway Management
Task: Guided nonproduction setup
Start here: The chosen gateway-management project; the project MCP URL and an approved downstream OAuth client configuration are available.
Navigation: Projects > selected management project > MCP Gateway > MCP servers > Add
- Open the selected gateway-management project.
- Select MCP Gateway in the left toolbar.
- Under MCP servers, select Add.
- Enter a descriptive server Name.
- Review the generated Identifier.
- Enter a Description explaining the registered server’s purpose.
- Select Add. The MCP connection page opens.
- Set MCP Endpoint to the project MCP URL identified in Milestone B.
- Select OAuth 2.0 Client Credentials for this service-identity example.
- Populate the security fields using the approved identity configuration described in the table below.
- Select Test. If it fails, resolve the endpoint or identity issue before proceeding.
- After a successful test, select Save.
- Review the discovered tools against the saved integration-tool definition.
| Field | Value source | Meaning |
|---|---|---|
| Access Token URI | Approved authorization-server token endpoint | Where this downstream client obtains its token. |
| Client Id / Client Secret | Approved confidential application; enter its secret only into the designated secure field | Which service client authenticates to the token endpoint. |
| Scope | Scopes approved for the downstream project-server route | Do not substitute gateway-specific scopes. |
| Auth Request Media Type / Client Authentication | Settings required by that token endpoint | Verify format and whether credentials belong in the supported header or body option. |
Expected result: The registration connects the governance workspace to the tool-provider server. This alone does not create, authorize, or activate a gateway.
Milestone D — Locate the Security and Business Policy Areas
Task: Inspect existing configuration
Start here: The same management project and its MCP Gateway workspace.
Navigation: Projects > management project > MCP Gateway > policy sections
- Open MCP Gateway in the management project.
- Locate Security policies. Identify existing tool-filter or PII-policy entries if available.
- Locate Business policies. Identify existing rules associated with the intended server/tool.
- If either list is empty, record that state. A registration does not automatically populate these policies; creation and testing are separate configuration tasks.
Expected result: You can identify where exposure and data/business controls are configured. A policy entry is not proof that the policy has been assigned to a gateway.
Milestone E — Inspect the Gateway Route and Obtain Its Endpoint
Task: Inspect an existing configured gateway
Start here: The management project has an existing activated gateway available for inspection. If none exists, gateway assembly and activation remain explicit prerequisites for runtime testing.
Navigation: Projects > management project > MCP Gateway > MCP gateways
- Locate the gateway under MCP gateways.
- Open its name to inspect the configured server assignments, selected policies, and policy evaluation order. Do not change or save shared configuration during orientation.
- Return to the gateway entry. For an available configured runtime route, select Actions and then Run.
- Identify the gateway URL in the Run details panel. Compare its role with the project MCP URL from Milestone B; the governed client uses the gateway endpoint.
Expected result: You can identify the route the client should use and the downstream server it references. Retrieving a URL does not itself demonstrate valid authorization or successful invocation.
Milestone F — Place the Components Outside OIC
The host/client belongs to the chosen assistant or MCP test client, not to an invented OIC project menu. Its server connection uses the gateway URL when following the governed route. OAuth application administration belongs to the selected identity domain. The ERP application is the target reached by the integration connection.
Practical checkpoint: In your own architecture sheet, identify each component's actual configuration owner and location. Leave client-specific clicks unresolved until the chosen product/version has been verified.
What you have achieved: you can follow the integration-to-tool entry point, project MCP exposure, registered downstream server, policy workspace, gateway configuration, and final client endpoint. Complete the remaining identity/activation prerequisites before invoking tools. Record actual tests separately; none of these expected outcomes is a claim of a deployment performed for this article.
08
Enterprise Rollout: A Safe Starting Point
An architecture overview should lead to a bounded experiment, not an assumption of production readiness. Start by deciding what the assistant must accomplish and which single capability is essential. Prefer a read-only action that returns limited synthetic or otherwise approved data. Add external servers only after their endpoint, authentication, supported transport, compatibility, and network path have been reviewed.
1. Confirm the service context. Check the OIC instance release, edition, commercial realm and region, project, roles, and whether MCP Gateway is visible and available.
2. Agree on the capability contract. Identify the OIC integration that will perform the work, its input/output shape, and whether it is eligible to be registered as a project MCP tool. Oracle's project guidance requires project membership, an active integration, and a REST trigger using the REST Adapter with OAuth and JSON payloads for the documented integration-tool route. Treat the actual tool identifier and schema discovered from the environment—not a tutorial's sample name—as authoritative.
3. Assign each control to an owner. The platform/identity team owns client identity, scopes, and token lifecycle. The gateway owner controls server registration, exposed tools, gateway authorization, relevant policies, and gateway observability. The integration owner validates arguments and orchestrates the workflow. The application owner remains responsible for target data permissions and business rules. One team may hold multiple roles, but ownership should still be named.
4. Test the intended route—and likely bypasses. Establish that the approved caller can discover and invoke the included read-only tool through the intended endpoint. Where a second harmless tool actually exists, test the behavior when it is excluded: check discovery and invocation independently, and record the layer that blocked it. Review whether a caller with existing permissions can reach the project MCP server or backend through a separate route; hiding a tool from one discovery response does not, by itself, prove every alternate route is closed.
5. Decide what may be logged. Oracle's current activation guide distinguishes Production tracing, which records gateway activity without request/response payloads and lists 32-day retention, from Audit tracing, which captures payloads and lists eight-day retention. The guide advises against Audit tracing for production because payloads may contain sensitive data. Recheck those settings and retention figures in the current product documentation before using them in an operating procedure, and align the choice with internal privacy and retention rules.
6. Add write capabilities only after controls are proven. A draft procurement request is not the same as approving a purchase. Put authoritative validation and authorization in the integration or target system. Test missing, malformed, negative, boundary, and over-limit values as relevant to the business rule; verify a denied write creates no record or side effect; and test retries so the same request cannot silently create duplicate records. Keep final approval outside the assistant's tool set unless a separately supported human-approval design is explicitly implemented and verified.
🛡️ Safety Check
Risk: A successful tool call is mistaken for proof that the overall use case is ready for production.
Control: Record expected and observed outcomes for positive, negative, bypass, identity, and recovery tests; use sanitized evidence and require security and operational approval.
Remaining risk: A small pilot does not establish capacity, all failure modes, all data-access paths, or long-term operational readiness.
Keep the deployment path distinct from this overview. Oracle's documented gateway workflow includes registering the downstream server, controlling which tools are discoverable, creating the gateway, activating it with the chosen tracing and authorization mode, and retrieving the gateway URL. This article explains how those objects relate; it does not substitute for the current step-by-step guide, tenant-specific authorization setup, or a tested deployment procedure.
Planning a pilot or reviewing an existing MCP architecture. Start with one capability, one clearly named identity, a documented route, and observable acceptance evidence before expanding scope.
09
Common Architecture Mistakes
Mistake 1: Treating the model as the protocol client. A model proposes a tool and arguments. The host/client is responsible for issuing the protocol request. Keep model selection, client transport, gateway enforcement, and integration execution as separate responsibilities.
Mistake 2: Treating a tool description as a security boundary. Descriptions help the model choose appropriately, but they are not an access-control mechanism. Apply permissions and validation at the relevant enforcement layers.
Mistake 3: Confusing the project endpoint and gateway endpoint. The MCP client uses the endpoint for the path it is intended to take. The gateway uses a separately registered downstream endpoint. Record both and their different token requirements.
Mistake 4: Assuming one bearer token is valid everywhere. Tokens have an intended recipient and permissions. Determine the credential used at each hop; do not blindly forward the inbound access token to a downstream server or application.
Mistake 5: Treating every MCP server as feature-equivalent. MCP is an interoperability protocol, but deployments expose different transports, protocol revisions, and capabilities. Oracle's project FAQ documents tools/list and tools/call; this is not evidence that every protocol feature is implemented on that route.
Mistake 6: Assuming tool invisibility proves denial. A tool filter is used to control discoverability. Test an existing tool's invocation separately with valid authorization and record which layer rejects it. Assess alternate direct access as its own question.
Mistake 7: Confusing protocol errors with business results. A token rejection, invalid MCP request, downstream timeout, failed OIC integration, and target business-rule rejection are different failures. Locate the failing layer and use its evidence to select the smallest correction.
Mistake 8: Calling a diagram or tutorial a lab result. An expected response is not an observed response. Label architecture assumptions, documentation-checked claims, proposed tests, and executed tests separately. A real production decision needs evidence from the actual supported environment and the organization's security and operations review.
Reviewing a design, incident, or tutorial before sharing it with a wider team. If two adjacent components seem interchangeable, write the exact endpoint, identity, protocol, and control that distinguishes them.
10
❓ FAQ
What is Oracle Integration MCP Gateway?
It is an Oracle Integration feature that provides a governed MCP entry point for selected OIC and approved third-party MCP servers, using configured controls for identity, tool access, policies, and operational visibility.
Are an OIC project MCP server and the MCP Gateway the same component?
No. A project MCP server exposes integrations registered as tools in that project. The gateway is a separate governance layer that can manage selected OIC and third-party MCP servers through its endpoint.
Does MCP Gateway replace OIC integrations or their business rules?
No. The integration continues to execute the workflow, and the target application remains responsible for its own permissions and business rules. Gateway controls are an additional governance layer.
Is OCI API Gateway the same as Oracle Integration MCP Gateway?
No. OCI API Gateway publishes and governs configured HTTP/REST API routes. Oracle Integration MCP Gateway governs MCP access to registered MCP servers and tools. Choose based on the protocol and control problem to be solved.
If a tool is missing from discovery, does that prove it is blocked everywhere?
No. Missing from discovery shows only what that client can see through that path at that time. Test invocation separately and assess other direct routes to the server or backend as a separate access-control question.
11
🔗 References & Further Reading
Oracle documentation establishes Oracle-product behavior; the MCP specification describes protocol concepts and does not, by itself, prove feature support in OIC.
- MCP fundamentals — introductory MCP series. Recommended background reading on the basic concepts of the Model Context Protocol before exploring MCP Gateway.
- Oracle Integration 26.10 release notes — September 2026. Confirms the MCP Gateway feature and minimum version shown in the release notes.
- Oracle Integration AI Feature Availability. Confirms the listed region/realm availability and notes that AI feature availability can depend on edition.
- Why an MCP Gateway Is Required. Explains the governance role of the managed MCP gateway.
- FAQs for Projects as MCP Servers. Describes project MCP server behavior, supported operations, and documented integration requirements.
- Discover Integrations as Tools from MCP Clients. Identifies Streamable HTTP for the direct project MCP-server client route.
- Define MCP Servers to Manage. Documents registering OIC or external MCP servers for gateway management.
- Steps to Create an MCP Gateway and Activate an MCP Gateway. Establish the broader object lifecycle and the authorization/tracing choices.
- About API Gateways in Oracle Integration documentation. Distinguishes API Gateway handling of REST routes from non-REST traffic.
- Model Context Protocol specification: Architecture, Tools, and Transports. Used for protocol-level terminology and the distinction between messages and transport.
- Oracle Integration product-team introduction to MCP Gateway. Additional context on the feature's enterprise purpose and design intent.
- Google Search Central: Changes to FAQ rich results. Google documents that FAQ rich results are generally limited to well-known, authoritative government and health websites; valid markup does not guarantee display.
Product and protocol names remain the property of their respective owners. References support the stated technical facts.
12
📝 Summary
- The host coordinates the assistant, the MCP client sends protocol requests, and the server exposes tools.
- An OIC project MCP server exposes integrations registered as agentic AI tools; the gateway is a separate governance layer for selected MCP servers and tools.
- For the documented project MCP-server route, Oracle specifies Streamable HTTP and documents
tools/listandtools/call. - The project MCP URL, gateway URL, identity, and downstream credential path have distinct purposes. Do not substitute them casually.
- Gateway governance complements rather than replaces integration validation and target-system authorization.
The first architecture skill is not memorizing a product diagram. It is being able to follow one request and explain who sends it, where its identity is checked, which tool is invoked, which component runs the business logic, and what evidence confirms the outcome.
Happy learning and designing.

Comments
Post a Comment