The Oracle Database MCP Toolkit — Enabling HTTPS in HTTP Streamable Mode

6 min readMay 15, 2026

Key Takeaways

The Oracle Database MCP Toolkit offers two transport modes: STDIO mode for local development and HTTP Streamable mode. STDIO transport mode is ideal for local development, while Streamable HTTPS mode supports remote and enterprise deployments with TLS encryption and OAuth 2.0 authentication for secure access control.
Streamable HTTP mode unlocks TLS/HTTPS encryption, OAuth 2.0 authentication (with token validation and integration to identity providers), and configurable authorization. These options are unavailable or limited in STDIO mode, providing secure access control essential for production or shared database environments.
The server can handle one or both transport modes simultaneously. Streamable HTTP mode provides a clear upgrade path from local experimentation with STDIO mode to robust, authenticated, network-accessible services.

Introduction

In my previous blog post, I introduced you to the Oracle Database MCP Toolkit — an open-source Model Context Protocol (MCP) server.

It allows LLMs to interact with Oracle Databases. We covered the core architecture and how to run it in STDIO mode, which is the standard for local integrations.

However, many enterprise scenarios require the toolkit to run as a persistent service accessible over the network. This is where the Streamable HTTP mode comes into play. By switching to HTTP mode, the toolkit transitions from a local process-to-process communication model to a robust, network-addressable service that uses HTTPS to stream data to AI agents.

This post builds on the first blog. I will assume you have already compiled the toolkit and have your environment ready on your Windows machine.

So without further ado, let’s get started!

Prerequisites

Oracle Database MCP Toolkit
JDK — Java Development Kit
Oracle AI Database 26ai Free Container Image
The curl CLI tool or your preferred HTTP client.
Oracle Database details, such as JDBC URL, DB_USERNAME, and DB_PASSWORD.

Configure the Oracle Database MCP Toolkit Server

The toolkit is designed to be transport-agnostic, meaning you can change the communication protocol via configuration rather than code.

Step 1: Reuse (or configure) your config.yaml file

To enable HTTP, you must modify your config.yaml file to include the server block. Open your config.yaml and update the mcp section as follows:

dataSources:
  prod-db:
    url: jdbc:oracle:thin:@localhost:1521/FREEPDB1
    user: ${DB_USERNAME}
    password: ${DB_PASSWORD}

tools:
  hello-mcp-toolkit:
    dataSource: prod-db
    description: Simple test tool to verify MCP connectivity with Oracle Database.
    parameters: []  # add this line to prevent a null pointer exception
    statement: |
      SELECT 'Hello MCP Toolkit' AS test_column FROM dual

Step 2: Generate a self-signed PKCS12 keystore on Windows

The toolkit natively runs a secure MCP server over HTTPS, so we need a local PKCS12 keystore file for development testing. We can generate one instantly using the JDK built-in keytool utility.

Start a Windows Command Prompt (CMD) session, and then run the following command to create a keystore inside your configuration directory:

cd C:\oracle-db-mcp-java-toolkit-configs
keytool -genkeypair -alias mcp-server -keyalg RSA -keysize 2048 -storetype PKCS12 -keystore C:\oracle-db-mcp-java-toolkit-configs\mcp-keystore.p12 -validity 365 -storepass changeit -dname "CN=localhost, OU=Development, O=LocalTest, L=Local, S=Local, C=US"

You will see a message similar to this one below:

Press enter or click to view image in full size

Keystore generation successful

It generated a file named mcp-keystore.p12 protected by the password changeit.

Run the Oracle Database MCP Toolkit Server in HTTP Streamable mode

Step 1: Running the Toolkit in Streamable HTTPS Mode

Now we can pass the transport settings, the secure port, and our new keystore properties straight to the execution string via JVM system properties. Once again, start a Windows Command Prompt (CMD) session and navigate to your project directory.

Next, as in my previous blog post, launch the server with your desired configuration, as shown below. Again, note that I used a specific local directory and the config.yaml file to store my different configuration setups.

cd C:\java-projects\mcp\src\oracle-db-mcp-java-toolkit
java -DconfigFile=C:\oracle-db-mcp-java-toolkit-configs\config.yaml -Dtransport=http -Dhttps.port=45450 -DcertificatePath=C:\oracle-db-mcp-java-toolkit-configs\mcp-keystore.p12 -DcertificatePassword=changeit -jar C:\java-projects\mcp\src\oracle-db-mcp-java-toolkit\target\oracle-db-mcp-toolkit-1.0.0.jar

Note the additional parameters, not present when running in STDIO mode:

-Dtransport=https: Toggles the engine from STDIO to the streamable network stack.
-Dhttps.port=45450: Specifies the encrypted network port.
-DcertificatePath & -DcertificatePassword: Points the container to our generated security credential, resolving the SSL initialization requirement.

Provided that your configuration is correct and that you executed all the steps above as explained, your server will start successfully as shown below:

MCP Server started in HTTPS Streamable mode

Step 2: Test your MCP server

The primary endpoint to be used by your MCP clients (like Claude Desktop or custom agents) will be available at https://localhost:45450/mcp

Nevertheless, to validate that your MCP server is running, you can use a simple curl command.

Note that the Model Context Protocol endpoint implements strict header enforcement, so your HTTP request must explicitly include an Accept header that text/event-stream or application/jsonas valid MIME types.

Start another Windows Command Prompt (CMD) session and run:

curl -k -v -H "Content-Type: application/json" -H "Accept: text/event-stream, application/json" -d "{\"jsonrpc\":\"2.0\",\"id\":\"1\",\"method\":\"initialize\",\"params\":{\"protocolVersion\":\"2024-11-05\",\"capabilities\":{},\"clientInfo\":{\"name\":\"curl-test-client\",\"version\":\"1.0\"}}}" https://localhost:45450/mcp

By inspecting the respective HTTP response, you should see:

If you see these results above, your Oracle Database MCP Toolkit is successfully serving requests over HTTP. You can now point any MCP-compatible client to this URL to start querying your Oracle Database!

Wrapping it up

That’s it! You have moved from the local process restrictions in STDIO mode to running your Oracle Database MCP Toolkit server in HTTP Streamable mode, allowing you to provide database access to remote AI agents or MCP clients.

With this configuration, you are no longer limited to a single local session — your Oracle Database is now a live, streamable resource that uses the Model Context Protocol!

I hope you found this blog post useful. Thanks for reading!

Frequently Asked Questions (FAQs)

What can the Oracle Database MCP Toolkit help me with?

It helps teams connect LLMs to Oracle Databases in a standardized way via MCP, so AI-assisted workflows such as troubleshooting performance logs, searching vector-embedded data, or reviewing SQL behavior could be enabled without building bespoke integrations for each use case.

How do I customize what the toolkit can do without changing code?

You define data sources and tools in a YAML config file. The server reads this on startup, registers built-in tools, and also exposes any custom SQL-backed tools you define in that configuration.

What should I know about security and deployment options?

The article starts with STDIO mode for local development, and notes that a follow-up will cover Streamable HTTP mode and security features. In HTTP/HTTPS scenarios, the toolkit can use TLS and OAuth 2.0 authentication to control and protect access.

References

Oracle Developers and Oracle OCI Free Tier

Join our Oracle Developers channel on Slack to discuss Java, GenAI, Agentic AI, JDK, JDBC, GraalVM, Micronaut, Spring Boot, Helidon, Quarkus, Reactive Streams, Cloud, DevOps, SRE, IaC, and other topics!

Build, test, and deploy your applications on Oracle Cloud — for free! Get access to OCI Cloud Free Tier!

Juarez Junior