How to Connect an MCP Server to Oracle Database
Choose the right Oracle MCP route—SQLcl, ORDS, or OCI Database Tools—and configure access, authentication, security, and troubleshooting.
Direct answer: choose the Oracle MCP implementation that matches where your database and MCP client run. Use SQLcl MCP Server when you want a locally managed process backed by named or saved SQLcl connections. Use ORDS MCP when Oracle REST Data Services already fronts your database and an administrator can expose its authenticated /mcp endpoint. Use OCI Database Tools MCP Server when a supported Oracle cloud database can use Oracle’s managed remote MCP service over Streamable HTTP.
These routes have different hosting, authentication, transport, and administration models. Keep database privileges, exposed schemas, targets, and tools narrowly scoped in every deployment.
Choose the right Oracle MCP route
| Route | Best fit | Connection model | Who operates it |
|---|---|---|---|
| SQLcl MCP Server | Local development or a team already using SQLcl | MCP server uses named or saved SQLcl connections | Developer or team configures SQLcl and the MCP client |
| ORDS MCP | Oracle REST Data Services environments | Authenticated /mcp endpoint exposes authorized direct database pools |
ORDS administrator configures pools, endpoint, and privileges |
| OCI Database Tools MCP Server | Supported Oracle cloud databases where a managed service is preferred | Remote Streamable HTTP with OCI IAM Identity Domains integration | OCI administrator creates the service and access roles |
Check the current product documentation before implementation: Oracle SQLcl MCP documentation, Oracle ORDS MCP documentation, and OCI Database Tools MCP documentation.
Before you connect: access and network checklist
- Identify the database deployment, version, network location, and whether the MCP client can reach it.
- Choose SQLcl, ORDS, or OCI Database Tools before copying configuration.
- Create a database identity with only the privileges required for the intended tasks.
- List the schemas, tables, procedures, and operations the agent actually needs.
- Decide how credentials, OAuth tokens, and network access will be protected and audited.
- Start with a non-production database and a restricted account.
Natural-language access is not automatically read-only. Depending on the implementation and granted privileges, tools may execute SQL, call PL/SQL, or perform other database operations.
Option A: connect SQLcl MCP Server
1. Create and verify a SQLcl connection
Install SQLcl and create a named or saved connection using the current SQLcl guide. The MCP server uses those existing SQLcl connection definitions; it does not require every MCP client to carry a separate JDBC configuration.
# Illustrative SQLcl session; use your site's approved connection method
sql /nolog
SQL> connect APP_MCP_USER@MY_DATABASE
SQL> select sys_context('USERENV','DB_NAME') from dual;
SQL> exitUse your organization’s wallet, password, network alias, or identity configuration as appropriate. Do not put a production password in a shared MCP configuration file.
2. Start SQLcl’s MCP server
SQLcl command names and client launch configuration can change by release. Follow the MCP section of the SQLcl documentation for the exact command for your installed version, then point your MCP client at that process. Do not assume a configuration JSON example for Claude, Cursor, or another client is interchangeable.
# Pseudoconfiguration: replace with the command documented for your SQLcl release
{
"mcpServers": {
"oracle-sqlcl": {
"command": "<path-to-sql>",
"args": ["<documented-mcp-server-arguments>"]
}
}
}3. Verify discovery and scope
- Restart or reload the MCP client.
- Confirm that the SQLcl MCP tools are listed.
- Run a harmless identity query such as the current database name and user.
- Confirm that an account outside the intended schema cannot be queried.
- Review SQLcl and database audit logs for the connection.
Option B: connect to ORDS MCP
What the administrator must configure
ORDS MCP is a server-side feature. An ORDS administrator enables and configures the MCP endpoint, maps authorized database targets to ORDS direct database pools, and grants the connection pool only the required privileges.
1. Obtain the endpoint and authentication details
Ask the administrator for the complete ORDS base URL, the authenticated /mcp endpoint, the permitted database target, and the authentication method supported by your MCP client.
2. Check reachability
# Replace the host and path with the endpoint supplied by your ORDS administrator
curl -i https://ords.example.com/ords/mcpA response that requests authentication can still prove that routing works. A DNS, TLS, proxy, or timeout error must be fixed before MCP configuration.
3. Configure the MCP client
Use the client’s remote MCP or Streamable HTTP configuration and the authentication method your administrator selected. Keep tokens in the client’s secret store or environment mechanism, never in source control. The exact JSON differs between clients, so copy the syntax from that client’s current documentation.
4. Validate targets and tools
- Connect and list the tools.
- Confirm that only the intended ORDS database target appears.
- Run a read-only smoke test.
- Review pool privileges and database auditing before allowing write operations.
Option C: OCI Database Tools MCP Server
1. Create the managed MCP server
In OCI Console, open Developer Services and the Database Tools area, then select Model Context Protocol Servers. Create a server and choose the database connection and authentication configuration required by your tenancy.
2. Configure identity and optional services
Oracle documents password-based and token-based database connection choices, OAuth 2.0 integration with OCI IAM Identity Domains, and user or group application roles. Decide whether Object Storage support is needed for asynchronous operations.
3. Connect remotely
Point an MCP client that supports the configured remote transport at the server’s Streamable HTTP endpoint. Supply the selected OAuth flow or access token. OCI tenancy, region, role, and client requirements can change, so verify them in the current OCI guide.
4. Verify database and role boundaries
- Confirm the service can reach the selected database.
- List the tools visible to the assigned role.
- Test with a restricted identity and non-production data.
- Check that users and groups cannot reach unrelated databases or schemas.
Security design for every route
- Least privilege: use a dedicated account with only required object and operation privileges.
- Target scoping: expose only approved databases, pools, schemas, and tools.
- Credential hygiene: keep passwords, wallets, OAuth secrets, and tokens out of repositories and shared chat.
- Network controls: restrict inbound access to ORDS or OCI endpoints and require TLS.
- Auditing: retain MCP, ORDS, OCI IAM, and database audit records according to your policy.
- Write protection: require explicit approval for DDL, DML, privilege changes, and PL/SQL calls.
Oracle’s ORDS guidance states: Granting a large language model (LLM) access to your database can expose sensitive data if the LLM is configured with excessive privileges.
Common errors and fixes
| Symptom | Likely cause | Fix |
|---|---|---|
| No tools appear | The client started the wrong process, used incompatible transport, or failed authentication. | Check the client log, verify the SQLcl command or remote endpoint, and confirm the client’s MCP transport support. |
| SQLcl cannot connect | The named or saved SQLcl connection is missing, invalid, or unreachable. | Connect interactively with SQLcl first; verify the alias, wallet, credentials, listener, and firewall. |
| ORDS returns 401 or 403 | Missing or invalid credentials, or the identity is not authorized for the pool. | Ask the ORDS administrator to verify authentication, roles, pool mapping, and endpoint policy. |
| ORDS endpoint times out | DNS, TLS, proxy, firewall, or private-network routing problem. | Test DNS and TLS from the MCP client’s network and confirm the route to /mcp. |
| OCI server is reachable but database calls fail | Incorrect connection configuration, IAM role, token, region, or database permissions. | Recheck the OCI resource, identity-domain application roles, selected connection, token validity, and database grants. |
| Queries expose unexpected data | The database identity or exposed target is broader than intended. | Reduce grants, schemas, pools, and tools; retest with a fresh restricted account. |
| Writes fail | The account is intentionally read-only or a required object privilege is absent. | Decide whether the operation is necessary, then grant the smallest specific privilege and audit it. |
Performance, reliability, and cost considerations
- Latency: remote OCI and ORDS paths add network, authentication, and proxy latency; SQLcl avoids a remote MCP hop when run beside the client but still depends on database response time.
- Connection reuse: use the implementation’s configured pools or saved connections instead of opening a new database session for every prompt.
- Timeouts: set client, proxy, ORDS, and database timeouts consistently so long queries fail predictably.
- Retries: retry only idempotent discovery or read operations. Do not blindly retry inserts, updates, DDL, or procedures with side effects.
- Observability: correlate MCP requests with ORDS/OCI logs and database session or audit identifiers.
- Cost: SQLcl and ORDS use your existing infrastructure and Oracle licensing arrangements. OCI Database Tools consumption, networking, and database costs depend on your OCI configuration; check current OCI pricing and tenancy terms.
Reference implementations and scope boundaries
Oracle’s GitHub MCP repository contains reference implementations intended for exploration, prototyping, and learning. Treat those examples as separate from SQLcl MCP, ORDS MCP, and the managed OCI service. The Oracle Database Documentation MCP Server is also separate: it indexes Oracle documentation locally and serves documentation search; it does not connect an AI client to a live application database.
Or skip the browser setup
If your workflow also needs screenshots of Oracle dashboards, runbooks, or internal web tools, ScreenshotNeo provides a single HTTP request for a clean PNG, JPEG, WebP, or PDF. Its MCP server includes take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients.
Cookie banners, newsletter popups, and chat widgets are removed before the shot. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and response headers identify the page verdict and billing status.
See the ScreenshotNeo API documentation for all options.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpimport requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);ScreenshotNeo includes 1,000 screenshots a month free with no card; paid plans start at $5 for 3,000 shots. Create a free ScreenshotNeo account.
FAQ
Can one MCP configuration work for SQLcl, ORDS, and OCI?
No. They use different hosting and authentication models. Configure the client for the route you selected and its current transport requirements.
Does ORDS MCP run without an ORDS administrator?
No. ORDS MCP must be enabled and configured server-side, including pools, endpoint access, and database privileges.
Which route should a local developer start with?
SQLcl MCP is usually the most direct when SQLcl already connects to the target database. Confirm the current SQLcl release and client instructions first.
Is OCI Database Tools MCP limited to one Oracle Database release?
Oracle’s overview lists Oracle Database 19c and Oracle AI Database 26ai among supported underlying versions. Verify current service and region requirements before deployment.
Can an MCP server safely run write queries?
Only when the identity, exposed tools, approval process, and auditing deliberately allow them. Start read-only and expand privileges one operation at a time.
