Giving an AI assistant database access is easy. Making that access controlled, inspectable, and repeatable is the hard part. Here is the Cursor CLI and Oracle AI Database workflow that does it.
Companion notebook: Cursor MCP with Oracle AI Database Workflow
Key Takeaways
- MCP turns AI-to-database access into an explicit tool contract instead of implicit system access.
- Oracle SQLcl in MCP mode, sql -mcp, is a practical way to connect Cursor CLI to Oracle AI Database through a local MCP server.
- Oracle AI Database provides the persistent storage and vector search layer for memory workloads, while Oracle AI Agent Memory gives teams a Python API for threads, durable memories, scoped retrieval, and context assembly on top of it.
- LangChain can provide application-side wrappers and orchestration after the Oracle-backed memory and retrieval path is in place.
- A strong default is hybrid: Cursor CLI plus MCP for interactive database work, Oracle AI Database plus Oracle AI Agent Memory for durable memory, and LangChain only when the application needs reusable retrieval orchestration.
Here is how those components connect in this pattern. The important visual point is that Cursor does not connect directly to Oracle AI Database. Cursor calls SQLcl MCP tools, SQLcl uses a saved Oracle connection, and Oracle AI Database remains the durable store for memory records, retrieval evidence, vectors, and tool traces. Oracle AI Agent Memory and LangChain sit in the application layer after that database-backed path is in place.
Production success depends less on clever prompting and more on boundaries, privileges, logging, scoped retrieval, and repeatable runbooks.
This guide is for developers who want Cursor CLI to work with Oracle AI Database through explicit tools, durable memory, and reviewable retrieval evidence.
The developer path through this guide is simple:
- Start with one approved Oracle connection and a read-only validation query.
- Put SQLcl MCP in front of that connection so Cursor sees tools, not raw database credentials.
- Check the audit and activity trail before adding more tool access.
- Add Oracle AI Agent Memory when the workflow needs durable thread context, scoped recall, or reusable context cards.
- Add LangChain only when you need application-side retrieval orchestration beyond the MCP interaction loop.
Why This Architecture Is Useful for Developers
Giving an AI assistant database access is easy. Making that access controlled, inspectable, and repeatable is the hard part.
Cursor is useful because it sits close to the developer's actual work: code, terminal commands, notebooks, configuration, and implementation details. A developer can move from "why is this failing?" to "inspect the database state" inside the same working loop. That closeness is powerful, but it also makes the database boundary more sensitive.
The question is not whether Cursor can produce SQL-shaped text. The question is whether the database path is approved, observable, and easy to debug later. A useful workflow needs to preserve the request, the tool call, the database identity, the retrieved context, and the reason a risky action was allowed or blocked.
By the end of this guide, you should know how to connect Cursor CLI to Oracle AI Database through a controlled MCP boundary, when Cursor context is enough and when Oracle-backed memory is needed, and how to build a retrieval path that can be queried, audited, and scaled.
The companion notebook is intentionally practical. It validates SQLcl and Java discovery, writes a sanitized Cursor MCP config preview, checks the saved SQLcl connection alias, creates memory tables, inserts simulated Cursor/MCP teaching traces, tests lexical, vector, and hybrid retrieval, initializes Oracle AI Agent Memory with the current 26.6 configuration shape, and finishes with a validation snapshot.
The workflow has four layers. Cursor CLI is the developer-facing agent interface. SQLcl MCP is the tool boundary. Oracle AI Database is the durable substrate for memory, traces, and retrieval. The notebook is the build-and-validation harness that proves the pieces are wired correctly before the workflow is handed to Cursor.
| Layer | Responsibility |
| Cursor CLI | Developer-facing MCP client and agent interface. |
| SQLcl MCP | Exposes declared Oracle tools to Cursor; it is the tool boundary. |
| Oracle AI Database | Stores durable data, retrieval evidence, vectors, metadata, traces, and enforces database privileges. |
| Oracle AI Agent Memory | Provides application APIs for users, agents, threads, durable memories, scoped retrieval, and context assembly. |
| LangChain | Wraps Oracle-backed retrieval results as Document objects and supports application-side orchestration. |
The Two Execution Loops
Building on that split between tool boundary and durable store, the system naturally forms two execution loops:
- Loop A is the operational interaction loop: Cursor CLI works with MCP to discover tools, inspect data, run bounded read-only queries, and return results immediately.
- Loop B is the durable memory and retrieval loop: application code writes history, tool logs, memory records, chunks, and embeddings to Oracle AI Database, then retrieves context before a later answer or workflow step.
SQLcl MCP handles live tool use. Oracle AI Agent Memory handles durable memory and scoped recall. Most production setups need both loops, but they solve different problems.
Reproducing the SQLcl MCP and Cursor CLI Workflow
The setup should be reproducible. SQLcl runs in MCP mode with sql -mcp. Cursor CLI launches it as an MCP server and talks to Oracle through declared tools, not through direct access. Connections come from saved SQLcl profiles that you create and test before Cursor uses them.
Cursor does not invent them at runtime; it reuses profiles you have already created and validated.
Prerequisites before you connect Cursor CLI:
- Oracle SQLcl 25.2.0 or higher.
- Oracle JRE 17 or 21.
- Cursor IDE or Cursor CLI if you want to use the generated MCP configuration outside the notebook.
- At least one saved SQLcl connection profile under
~/.dbtools, created with password persistence for MCP use.
- A database user with the minimum permissions required for the workflow. Start with read-only access and a sanitized development or replica environment where possible.
The notebook deliberately treats the saved SQLcl connection alias as a first-class artifact. In local development, that alias is what lets SQLcl MCP connect without forcing the agent to assemble credentials dynamically.
The notebook then generates a sanitized Cursor MCP config preview. The preview is intentionally safe: it shows the server command and arguments without exposing secrets. It does not overwrite your real Cursor MCP configuration.
For the saved connection itself, the important detail is -savepwd. MCP cannot stop and ask a human for the password every time Cursor invokes a database tool. The saved alias becomes the repeatable local path Cursor can use after you have reviewed it.
{
"mcpServers": {
"sqlcl": {
"command": "/absolute/path/to/sql",
"args": ["-mcp"]
}
}
} That small JSON block defines the connection between Cursor and SQLcl MCP Server. Cursor interacts with the database through the tools and permissions exposed by the MCP server, using the saved SQLcl connection profile you created and tested first. Save this configuration in .cursor/mcp.json for a project-scoped setup or ~/.cursor/mcp.json globally, restart Cursor or Cursor CLI, then run:
cursor-agent mcp list
cursor-agent mcp list-tools sqlclA useful first prompt is intentionally constrained:
Use SQLcl MCP to list available saved Oracle connections. Do not run DML or DDL. Validation checklist before expanding access: Run sql -mcp locally and confirm the server starts.
- Restart Cursor CLI and confirm the SQLcl tools are discoverable.
- Run one read-only query against an approved schema.
- Check database-side MCP activity logs and session metadata.
- Document the connection alias, database user, grant scope, restrict level, and troubleshooting owner.
Good first proof looks like this:
- The MCP server starts without a Java or path error.
- Cursor lists the SQLcl MCP tools after restart.
- A read-only query succeeds against the expected schema.
- The notebook audit trail records the expected tool interaction in
cursor_tool_logs.
- For live Cursor CLI + SQLcl MCP validation, confirm the database/session activity through your normal Oracle monitoring path.
- A denied query fails because of the database role, not because a prompt asked nicely.
A useful MCP boundary is more than tool discovery. The notebook models read-only defaults, confirmation requirements, scope checks, and controlled failure examples so denied and warning states are visible.
- Read-only default: start with inspection and diagnostics before allowing changes.
- Confirmation gate: require explicit approval for medium-risk, write-like, or destructive actions.
- Scope control: keep user, tenant, and schema filters close to the database query.
- Failure trace: store denied calls and warnings as evidence instead of hiding them.
What a Successful Notebook Run Shows
The notebook is not just setup prose. It produces concrete checkpoints that make the workflow inspectable.
The first useful result is a deterministic Cursor/MCP timeline. The sample data uses explicit event sequence values and simulated event timestamps so the workflow order is stable every time the notebook is rerun:
step event_kind actor result
1 CONVERSATION user initial support-job request
2 CONVERSATION assistant SQLcl MCP read-only plan
3 MCP_TOOL sqlcl.connections/list_connections SUCCESS
4 MCP_TOOL sqlcl.sql/query SUCCESS
5 MCP_TOOL sqlcl.sql/query DENIED / PRIVILEGE_SCOPE
6 CONVERSATION assistant grounded summaryThat ordering matters because operational memory is only useful if the answer can be traced back to the request, the tool calls, and the permission boundary that shaped the result.
The grounding package also returns visible evidence before the assistant answer is assembled:
Status: READY
Top evidence:
- Saved SQLcl connections for MCP
- SQLcl MCP execution boundary
- Tool logging baseline
- LangChain as orchestration glueIf retrieval is empty or too weak, the notebook returns INSUFFICIENT_CONTEXT and displays a safe empty-result message instead of trying to select columns from a missing evidence table.
The final snapshot should show every local layer that is ready:
Cursor MCP config generated
SQLcl MCP runtime ready
SQLcl saved connection ready
Oracle AI Database memory ready
Oracle AI Agent Memory package ready
Lexical search ready
Native VECTOR execution path ready
Demo embeddings demo ready
Hybrid retrieval ready
LangChain wrapper ready
validation_action_needed 0That is the practical bar for this demo: Cursor setup artifacts are generated, SQLcl MCP prerequisites are validated, Oracle memory tables are populated, retrieval works, Agent Memory initializes, and the notebook separates native VECTOR readiness from deterministic demo embeddings.
Simulated Teaching Data, Not Live Cursor Telemetry
One important boundary in the companion notebook is that the operational records are simulated teaching data. The notebook inserts sample conversation rows and sample tool-log rows to show what a production workflow should preserve: the user's request, Cursor's plan, tool calls, outcomes, controlled failures, and retrieval evidence.
Those rows are not live telemetry captured from Cursor CLI, and the notebook does not automatically observe, scrape, or stream Cursor CLI activity. Live Cursor validation still happens through Cursor's MCP configuration and the SQLcl MCP server. The notebook proves the database-backed memory, retrieval, and validation pattern around that workflow so the pieces are inspectable and repeatable.
Why Put Application Memory Records in Oracle AI Database, Not Just Outputs
Once the first MCP tool calls work, the next challenge is continuity. This is where long-term memory for AI agents becomes different from short-lived chat context.
If memory lives only in chat context, the system is fragile. If memory is scattered across files without structure, retrieval and auditing become expensive over time.
A database-backed memory model is usually cleaner and more scalable. The companion notebook builds this memory layer from scratch so the mechanics are visible, then shows how Oracle AI Agent Memory sits on top of it once the substrate is working.
Memory categories that matter in practice:
- Conversation memory keeps the important user and assistant turns that future sessions may need.
- Operational memory keeps tool calls, outcomes, warnings, and failures so a team can debug what happened.
- Semantic memory adds embeddings so the system can find relevant context even when the user asks in different words.
In practice, hybrid retrieval for agent memory usually combines exact operational terms, such as sql -mcp or cursor_mcp, with semantic search over memory records.
The notebook shows the lower-level mechanics first so the storage and retrieval path is visible. This is also a context engineering problem: the application has to decide which memories, tool traces, and retrieval results should be assembled before Cursor or another assistant answers. Oracle AI Agent Memory then gives application code a cleaner package API over that same database-backed idea.
Where Oracle AI Agent Memory Fits
Oracle AI Agent Memory sits between your application code and Oracle AI Database. The package manages conversation threads, durable memory records, scoped retrieval, and context assembly while Oracle AI Database remains the storage layer underneath.
The notebook includes an abbreviated package-backed memory pattern. It initializes OracleAgentMemory with a database connection pool and a custom local deterministic embedder. LocalCursorEmbedder is notebook code, not a built-in Oracle AI Agent Memory embedder.
The local embedder is intentionally billing-free, which makes the notebook runnable for people who do not want to attach paid model usage to a tutorial.
In Oracle AI Agent Memory 26.6, use MemoryExtractionConfig(extract_memories=False) instead of the older inline extract_memories=False parameter, and use memory_store_id instead of table_name_prefix.
from oracleagentmemory.apis.searchscope import SearchScope
from oracleagentmemory.core import MemoryExtractionConfig
from oracleagentmemory.core.oracleagentmemory import OracleAgentMemory
db_pool = oracledb.SessionPool(
user=CONFIG["ORACLE_USER"],
password=CONFIG["ORACLE_PASSWORD"],
dsn=CONFIG["ORACLE_DSN"],
min=1,
max=4,
increment=1,
)
agent_memory = OracleAgentMemory(
connection=db_pool,
embedder=LocalCursorEmbedder(dimensions=32),
llm=None,
memory_extraction_config=MemoryExtractionConfig(extract_memories=False),
schema_policy="create_if_necessary",
memory_store_id="cursor_oam_local",
)
Use oracleagentmemory from your application layer when you need package-managed users, agents, memories, threads, scoped retrieval, and context assembly. Keep systems of record separate from memory records: memory helps provide context, but application logic and authoritative data sources should still decide what is true, allowed, and final.
Implementation note: use a schema whose default tablespace supports the JSON objects created by Agent Memory. If a local SYSTEM schema sits on a tablespace that rejects JSON object creation, the better production answer is a dedicated application schema.
Production note: the package-managed expired-record purge job needs CREATE JOB or an equivalent scheduler-job privilege, or a managed schema setup flow. Without that privilege, expired messages and memories will not be purged automatically. For a local notebook demo, this is acceptable as long as the limitation is visible.
Store and Search: What a Realistic Memory Looks Like
A realistic Cursor memory is not generic trivia about a user. For this workflow, memory should capture how a developer actually works: the connection name they used, the SQLcl path that succeeded, the MCP config location, the failed privilege boundary, the retrieval query that helped, and the final fix that should be reused later.
thread = agent_memory.create_thread(
user_id=AGENT_MEMORY_USER_ID,
agent_id=AGENT_MEMORY_AGENT_ID,
)
thread.add_memory(
"Developer validated Cursor CLI with SQLcl MCP alias cursor_mcp "
"against local Oracle AI Database service FREEPDB1."
)
results = agent_memory.search(
query="Cursor SQLcl MCP alias validation and Agent Memory setup",
scope=SearchScope(user_id=AGENT_MEMORY_USER_ID, agent_id=AGENT_MEMORY_AGENT_ID),
) That kind of memory pays off because it is operational. It can help Cursor answer the next question with context from the previous debugging session, but it is still scoped and retrievable through a database-backed API.
Vector Search, Native VECTOR, and Demo Embeddings
Vector search is part of the Oracle AI Database memory story. In a real application, embeddings usually come from a model and are indexed with Oracle AI Database vector capabilities.
The notebook separates two ideas that are easy to accidentally blur:
- Native VECTOR readiness means the database can store and search vectors through the Oracle AI Database vector path.
- Deterministic demo embeddings are local, repeatable vectors used so the notebook can run without external model billing.
The deterministic embeddings are useful for portability and inspection, but they should not be described as productionsemantic embeddings. For production, replace the notebook's demo_embed() or LocalCursorEmbedder with a supported embedding model after cost, latency, privacy, and retrieval-quality review.
The final notebook snapshot makes this separation explicit with two rows: Native VECTOR execution path and Demo embeddings.
Where LangChain Adds Value
LangChain should not be treated as the source of truth. Cursor CLI does not call LangChain directly in this architecture, and LangChain is not the permission boundary, memory store, or audit layer.
In this notebook, LangChain is used as a compatibility layer. The custom Oracle-backed hybrid_search() path performs retrieval, then the results are wrapped as LangChain Document objects so applications that already expect LangChain interfaces can consume them.
By the time LangChain is introduced, the database tables, package memory, retrieval scores, and validation snapshot already exist. LangChain becomes a wrapper around evidence, not a substitute for evidence.
Use it when the consuming application already expects retrievers, documents, chains, or tool orchestration. If the application only needs direct SQL, package-backed Agent Memory search, or a simple evidence table, the extra abstraction can make debugging harder.
How to Move This from Demo to Production
The difference between demo success and production success is disciplined operations. In this workflow, the first failures to check are usually integration issues: SQLcl discovery, Java runtime, saved connection aliases, database permissions, and retrieval configuration. A local notebook can prove the wiring. A production workflow needs smaller database roles, managed secrets, clear MCP approval policy, repeatable environment setup, and monitoring aroundmemory writes and tool calls.
Access and privilege model:
- Use a dedicated application schema where possible, then tighten grants with least-privilege roles and quotas.
- Keep saved SQLcl aliases separate by role and environment instead of sharing one broad connection.
- Start read-only wherever possible and gate write operations with explicit confirmation workflows.
- Use schema allowlists and separate accounts for development, test, and production.
Observability model:
- Log tool name, thread ID, timestamp, status, and sanitized inputs and outputs.
- Classify failures into runtime, discovery, connection, permission, query, and retrieval categories.
- Keep a troubleshooting playbook in the repo so setup issues do not become tribal knowledge.
- Check whether retrieval quality changes as more data and memory records are added.
Reliability model:
- Prefer deterministic SQL patterns with bounded result sets.
- Use retrieval-first context assembly for memory-heavy tasks.
- Avoid giant context stuffing as a substitute for memory design.
- Review and prune tool surfaces periodically.
- Move from the local deterministic embedder to a supported embedding model after cost, latency, and privacy review.
What to Check When the Workflow Fails
When this workflow fails, start with the integration points below.
- Runtime failure: sql -mcp does not start.
Check the absolute SQLcl path, confirm Java is available, and run sql -mcp outside Cursor first. Resolve runtime issues before checking assistant behavior.
- Discovery failure: Cursor does not see tools.
Check the Cursor MCP configuration, confirm the configured command points to the SQLcl executable, and restart or reload Cursor CLI after edits.
- Connection failure: tools are present but queries fail immediately.
Check the saved SQLcl connection alias, confirm the profile lives under the expected SQLcl connection store, and verify password persistence for the MCP workflow. Then test the same connection outside Cursor.
- Permission failure: queries execute selectively and fail on specific objects.
Check the database role first. A selective failure can be the right outcome when least privilege is working. Add grants intentionally and keep read-write access separate from the initial validation path.
- Retrieval quality failure: answers are fluent but weakly grounded.
Inspect the retrieved records before blaming the model. Check chunk size, metadata filters, embedding choice, top-k settings, and whether the query is asking for exact history, semantic similarity, or operational logs. The notebook's grounding package includes an INSUFFICIENT_CONTEXT path and guards empty evidence before displaying result columns.
Why the Hybrid Model Is Usually the Best Long-Term Design
No single layer handles both execution and memory well. Trying to force everything into Cursor context gets messy fast: you either lose control over execution, or you stuff too much state into prompts just to keep things working. On the other side, if you only build backend memory systems, you lose the speed and usability that makes an assistant useful during development.
The hybrid approach works because it does not force one layer to do everything. MCP handles live tool execution, Oracle AI Database keeps durable evidence, Oracle AI Agent Memory provides the memory API, and LangChain is added only when the application needs that shape.
In real teams this usually evolves over time. Start with Cursor CLI, SQLcl MCP, read-only access, and strong logging. Once people rely on the workflow, the gaps become visible: lost context, weak traceability, repeated setup work, or retrieval that is hard to explain. That is when database-backed memory and structured retrieval become worth adding.
For Cursor specifically, the value is that the assistant can stay in the developer loop without becoming an unreviewed database actor. Cursor can help plan, inspect, and explain. SQLcl MCP exposes the database path as tools. Oracle AI Database keeps the durable evidence. That is the combination that makes the workflow useful after the demo.
Conclusion
A Cursor and SQLcl MCP workflow becomes useful when it is treated as an engineering pattern, not just a setup trick. Cursor keeps the developer moving, SQLcl MCP keeps database access explicit, and Oracle AI Database keeps the evidence durable enough to inspect later.
The result is a workflow a team can inspect. You can see what Cursor asked for, which tool path ran, what the database allowed, which memory records were retrieved, and how the final answer was assembled.
That is the shift that matters: from assistant access that is implicit and hard to audit, to explicit boundaries, durable memory, and evidence a developer can actually debug. For database-connected development, that is what turns Cursor from a helpful local assistant into part of a controlled engineering workflow.
Frequently Asked Questions
What is MCP in this context?
MCP is the protocol boundary that lets Cursor call explicit tools exposed by a server instead of accessing systems implicitly.
What does MCP protect, and what does it not protect?
MCP makes the tool interface explicit and reviewable: Cursor can call only the tools exposed by the server. It does not replace database security. The saved SQLcl connection profile, database user, grants, roles, network controls, and database policies determine what those tools can actually access or change.
Why use SQLcl for Oracle MCP?
SQLcl already understands Oracle workflows and can run as the Oracle SQLcl MCP server with sql -mcp, making the Oracle integration practical and direct.
Is this Cursor IDE or Cursor CLI?
The workflow is Cursor CLI oriented because the notebook validates the SQLcl MCP path using a local MCP serverdefinition and manual Cursor CLI checks. The same MCP server can be configured in project-scoped .cursor/mcp.json or global ~/.cursor/mcp.json, depending on how your team uses Cursor.
Why include Oracle AI Database if MCP already works?
MCP handles the execution boundary. Oracle AI Database handles durable memory, retrieval, vector search, concurrency, observability, and governance.
Do I need an OpenAI API key?
An external model-provider API key is only needed if you change the notebook to use a provider-backed embedding or LLM service. The default notebook path uses a local deterministic embedder so people can run the Agent Memory package section without adding billing details.
Why include LangChain if Oracle already stores memory?
Because many teams already use LangChain-shaped retrievers and chains. The notebook shows how Oracle-backed retrieval can fit that interface.
Is this RAG vs agent memory?
Not exactly. RAG retrieves external knowledge for a response, while agent memory preserves useful context, decisions, tool traces, and workflow state across sessions. In practice, production systems often use both.
What is the minimum viable setup?
SQLcl MCP configured in Cursor CLI, one safe saved Oracle connection, and a read-only validation flow.
Should production start with read-write permissions?
Usually no. Start read-only, log everything important, and add write scopes gradually with explicit approvals.
What is the best rollout strategy?
Pilot in development with read-only access and strong logging, then expand capabilities in controlled phases as the team learns which memory and tool paths are actually useful.
Companion Troubleshooting Appendix
Minimum viable setup: SQLcl MCP configured in Cursor CLI, one approved Oracle connection, read-only validation, and database-side activity logging.
First checks: confirm sql -mcp starts, Cursor sees the tools after restart, and the saved SQLcl connection alias resolves.
Environment model: use separate credentials and policies for dev, test, and prod, with stricter controls as capability expands.
Logging model: capture tool name, timestamp, thread ID, status, sanitized input/output summaries, and relevant SQLcl MCP log records.
Retrieval quality: tune chunk size, enrich metadata, review embedding choice, and evaluate retrieval against representative queries.
Common anti-pattern: expanding tool surfaces before ownership, logging standards, and runbooks are in place.
Rollout path: pilot in dev with read-only access and strong logging, then expand capabilities in controlled phases.
Schema: Agent Memory package tables need a schema and tablespace that can create the package's JSON-backed objects.
Scheduler job: package-managed expiry purge needs scheduler-job privilege or managed setup for production.
Model calls: an API key can be present but still fail if the model provider account has no quota.
