Upgrade `oracle-mcp` to MCP v2 and the modern protocol

[fredluz]

Summary

Upgrade Oracle’s MCP integration to the TypeScript SDK v2 and the modern MCP protocol.

This would replace Oracle’s older MCP foundation with the current server abstractions, simplify several parts of the existing implementation, strengthen schema and transport behavior, and make newer MCP capabilities available for future Oracle features.

Compatibility with clients using the previous MCP protocol should be maintained.

Why Oracle should upgrade

Oracle currently uses the monolithic v1 MCP SDK and manually manages parts of the stdio server lifecycle and tool-handler plumbing that are handled more directly by SDK v2.

The upgrade would be useful even if Oracle added no new tools or user-facing behavior. It would reduce bespoke protocol code, improve validation and transport handling, and provide a better foundation for features that are awkward to implement against the existing integration.

Immediate improvements include:

• Current MCP protocol support
  Modern MCP clients could negotiate and use the current protocol rather than Oracle remaining limited to the previous protocol generation.

• Simpler server lifecycle management
  SDK v2 provides supported abstractions for stdio startup, protocol negotiation, connection handling, shutdown, and transport errors. Oracle would no longer need to reproduce as much of that lifecycle itself.

• Smaller runtime dependency surface
  The v2 SDK separates server and client packages. Oracle’s runtime needs only the server package, while the client package can remain limited to tests and development tooling.

• Cleaner schema definitions
  Oracle’s MCP tools currently use raw Zod-shape patterns partly to accommodate the older SDK. V2 supports explicit Standard Schema objects, allowing tool input and output schemas to be defined and reused directly.

• Stronger structured-output validation
  Existing structuredContent responses can be validated against their declared output schemas before crossing the protocol boundary, making malformed tool results easier to catch at their source.

• Less low-level server plumbing in tool handlers
  Request-scoped context can provide logging, notifications, cancellation signals, and client information without passing internal server objects into tool implementations or reaching through private server properties.

• More robust stdio behavior
  The modern transport improves input buffering, closed-stream handling, shutdown behavior, and transport error handling.

• Clearer separation of server definition and transport
  Oracle’s tools and resources can be registered through a reusable server factory rather than being coupled directly to one transport startup path.

Existing Oracle behavior to preserve

The upgrade should preserve Oracle’s current MCP interface and execution behavior:

• consult
• chatgpt_image
• project_sources
• sessions
• oracle-session://{id}/{kind} resources

Tool names, descriptions, parameters, defaults, structured outputs, resource identifiers, dry-run behavior, and session behavior should remain equivalent after the migration.

Further improvements enabled by MCP v2

The migration would also make the following focused improvements possible in later work:

• Semantic progress events
  Report stages such as launching the browser, uploading attachments, selecting the model, waiting for the response, and downloading artifacts.

• Request cancellation
  Propagate the request-scoped abort signal into foreground browser and provider operations.

• Resource subscriptions
  Allow compatible clients to subscribe to session metadata, log, result, or artifact changes instead of repeatedly polling resources.

• In-band confirmations
  Represent approval-required operations as protocol interactions rather than special Boolean retry fields understood only by Oracle-aware callers.

• Interactive authentication flows
  Support resumable login, OTP, and manual-action-required states through structured protocol interactions.

• Cacheable tool discovery
  Allow compatible clients to cache Oracle’s largely static tool and resource catalog.

• Deterministic discovery responses
  Keep tool and resource definitions stable across connections, improving reproducibility and potential host-side prompt caching.

• Standard asynchronous tasks
  Evaluate the MCP Tasks extension for long-running consultations, standardized task status, cancellation, and result retrieval.

• Durable task handles
  Associate MCP task identifiers with Oracle sessions so results can be retrieved after the original request connection ends.

• Completion subscriptions
  Notify compatible clients when long-running tasks or session resources change state.

• Cleaner separation of logs and progress
  Keep detailed diagnostics in Oracle logs or stderr while exposing concise, structured progress through MCP.

• Modern HTTP transport
  Reuse the same MCP server definition for a future HTTP transport without duplicating Oracle’s tool-registration logic.

• Stateless hosted deployment
  Support future remote Oracle deployments where independent MCP requests can be routed across service instances.

• Per-request capability handling
  Adapt behavior using the identity and capabilities supplied with each request.

• Gateway-level routing and authorization
  Allow future HTTP deployments to route or authorize specific MCP methods using standard protocol metadata.

[clawsweeper]

Codex review: keeping this open for maintainer follow-up; there is still a little grit to resolve. Reviewed August 22, 2026, 5:20 AM ET / 09:20 UTC.

Summary
Keep open for a maintainer product decision: this is a broad protocol and compatibility migration, not a bounded defect repair. Likely related person: Peter Steinberger (high confidence from the current MCP implementation history).

Reproducibility: not applicable. this is a proposed migration, not a report of broken behavior; current source and tests establish an operating stdio MCP server.

Ways to help us reproduce this

• Add a screenshot or short recording showing the behavior.
• Add expected vs actual behavior.
• Share version, platform, channel/provider, and relevant config details.

Maintainer decision needed

Question	Recommendation
Should Oracle retain the released SDK 1.30 stdio baseline, or sponsor a phased newer-protocol migration with explicit legacy-client support and acceptance criteria?	Retain the current baseline: Keep the released MCP implementation unless a concrete client incompatibility or required capability establishes a migration need.

Why: Current main already uses the SDK’s high-level server and stdio abstractions, while the requested migration changes a public host compatibility contract and introduces broad future capability scope without a concrete failing client or required feature.

Next step
A maintainer must first choose the protocol/client compatibility policy; no safe bounded repair exists before that choice.

Review details

Best possible solution:

Choose the supported MCP client and protocol compatibility targets first, then implement a phased migration that preserves the documented tool/resource contracts and proves both legacy and selected modern-client interoperability.

Do we have a high-confidence way to reproduce the issue?

Not applicable: this is a proposed migration, not a report of broken behavior; current source and tests establish an operating stdio MCP server.

Is this the best way to solve the issue?

Unclear: a newer protocol may be valuable, but defining the client-compatibility promise and the concrete capability need is necessary before selecting a maintainable migration path.

AGENTS.md: found and applied where relevant.

Remaining risk / open question:

• A major SDK/protocol migration without an explicit supported-client matrix could break existing stdio hosts or change the documented tool/resource contracts despite preserving names.

Codex review notes: model internal, reasoning high; reviewed against 083bba7e61f4.

Label changes

Label justifications:

• P3: This is a speculative compatibility and maintainability upgrade with no current user-facing failure or required capability demonstrated.

Evidence reviewed

What I checked:

• Current SDK baseline: Current main declares @modelcontextprotocol/sdk ^1.30.0; the requested major/protocol change would alter a released integration baseline. (package.json:63, 083bba7e61f4)
• Current server architecture: The current server already uses the SDK’s high-level McpServer and StdioServerTransport, registers the established tools/resources, and waits for transport closure. (src/mcp/server.ts:5, 083bba7e61f4)
• Published compatibility surface: The MCP documentation defines the existing consult, chatgpt_image, sessions, project_sources, and oracle-session resource behavior that a migration must preserve. (docs/mcp.md:6, 083bba7e61f4)
• Existing contract coverage: Current tests verify object schemas, JSON-RPC-only stdio output, and resource reads, providing a starting compatibility suite but not a migration acceptance definition. (tests/mcp.schema.test.ts:46, 083bba7e61f4)
• Feature provenance and release: Available blame attributes the server’s current high-level MCP implementation to the v0.17.3 release commit; the current main release is tagged v0.18.0. (src/mcp/server.ts:15, 6b17e6db0cae)
• Maturity-label check unavailable: The required shortlist helper could not classify this issue because this checkout has no qa/maturity-scores.yaml; no maturity label is selected.

Likely related people:

• Peter Steinberger: Available blame assigns the current server definition to the v0.17.3 release commit, and he authored the current v0.18.0 release commit. (role: current MCP implementation origin and recent release author; confidence: high; commits: 6b17e6db0cae, 083bba7e61f4; files: src/mcp/server.ts, package.json, docs/mcp.md)

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.