MCP server for Oracle AI Database 26ai

Ask your Oracle data. Get a table, a chart, and the token bill.

OraViz is a minimal, visualization-first MCP server: seven read-oriented tools and a context contract on every result — preview caps with honest truncation markers, cells bounded at 500 characters, and charts rendered as MCP image content. Benchmarked against the official SQLcl MCP server on the same Oracle 26ai Free container before security hardening.

Measurements and PDFs are historical snapshots. Current deployment boundaries, authentication requirements, and limits are documented in SECURITY.md.

53.3%
fewer workflow tokens for the five-question run, schemas included
862
tokens of tool schemas, read once per session — vs 2,139
123
text tokens to answer the comparison question with a chart — plus one PNG
4 row(s) | columns: REGION, REVENUE

| REGION | REVENUE  |
|--------|----------|
| East   | 573932   |
| North  | 502897   |
| South  | 432190   |
| West   | 360759   |
context contract active · 25-row cap · cells ≤ 500 chars
Bar chart titled 'Total revenue by region (12 months)' rendered by the create_chart tool from live Oracle data, East leading with 573,932.
Rendered by create_chart from the query below — returned as an image content block plus a short text preview.

01 — The demo

One query, end to end

Every step below is a real exchange between an MCP client and OraViz against an Oracle AI Database 26ai Free container: the SQL the agent wrote, the result it received, and the chart it rendered.

01

Ask in SQL

The agent composes one SELECT/WITH. A conservative allowlist rejects unreviewed function calls with parentheses, but bare parameterless routines and routines inside views/synonyms can evade it. Use a dedicated account with object-level READ grants and review inherited/PUBLIC execution privileges. The default timeout is 60 seconds per database round trip, not per statement or tool call.

SELECT region, SUM(revenue) AS total_revenue
FROM oraviz.sales_demo
GROUP BY region
ORDER BY total_revenue DESC;
02

Read a bounded result

One metadata line, one header, four rows. The preview cap and cell limit mean the cost of this result is the same whether the table holds 96 rows or 96 million.

4 row(s) | columns: REGION, REVENUE

| REGION | REVENUE |
|--------|---------|
| East   | 573932  |
| North  | 502897  |
| South  | 432190  |
| West   | 360759  |
03

See the answer

create_chart runs the same query and returns the PNG as image content together with a five-row preview, so text-only clients still receive the essentials.

The same revenue query rendered as a bar chart: East 573,932; North 502,897; South 432,190; West 360,759.
04

Project embeddings

A vector chart sends the first VECTOR column through PCA and returns a 2D scatter, so 26ai embeddings can be explored without leaving SQL.

Six product embeddings projected to two PCA dimensions: footwear clusters left, outerwear at the bottom, camping at the right.

02 — The measurements

53.3% fewer tokens than the official MCP server

Identical questions to OraViz and to the official Oracle SQLcl 26.1 MCP server (sql -mcp), same database, same data. Counted with tiktoken: tool schemas read once per session, plus every tool result needed to answer.

Historical results, unchanged since the original experiment. Current schemas, limits, and LOB behavior differ; these values have not been recomputed for the hardened server.

2,337 workflow tokens, against 5,006 for SQLcl

The savings concentrate where context would otherwise grow: tool schemas (−59.7%), schema discovery (−80.5%), and an unaggregated 96-row dump (−61.4%).

  • −80.5% listing schema objects: 69 vs 354 tokens
  • −61.4% full 96-row dump: 825 vs 2,136 tokens
  • −59.7% tool schemas: 862 vs 2,139 tokens
  • +55% ten-row sample framing — bounded by design, not by data
  • 123 tok chart path: aggregate rendered to PNG, no SQLcl equivalent
Horizontal bar chart comparing tokens per question: OraViz wins list objects, loses describe, aggregate and sample slightly, and wins the 96-row dump by a wide margin.
Per-question tokens. Small result sets pay a bounded markdown framing premium; wide results and discovery win by large margins.
Grouped bar chart of the workflow budget: tool schemas 862 vs 2,139 tokens, tool results 2,337 vs 5,004, total 2,337 vs 5,006.
The workflow budget by stage. The full methodology, per-step numbers, and the harness live in benchmarks/.

03 — The surface

Seven tools, each with one job

Small schemas are a per-session cost every agent pays. OraViz keeps them short and pushes the aggregation to SQL, where the database already operates.

04 — Run it

Point any MCP client at it

Thin-mode python-oracledb means no Oracle client libraries to install. Works with Claude Code, Crush, Cursor, or any compliant client over stdio or HTTP.

Run the server

uvx --from git+https://github.com/jasperan/oraviz-mcp@REVIEWED_COMMIT_SHA oraviz-mcp

Replace the commit placeholder with a reviewed revision. Use a dedicated reader account; inject ORACLE_PASSWORD into the MCP host's protected runtime environment. Stdio uses local OS trust. All HTTP/SSE entry paths require configured JWT authentication, including loopback; deployments also need TLS and private networking.

Register it with your client

{
  "mcpServers": {
    "oraviz": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/jasperan/oraviz-mcp@REVIEWED_COMMIT_SHA", "oraviz-mcp"],
      "env": {
        "ORACLE_USER": "oraviz_reader",
        "ORACLE_DSN": "localhost:1530/FREEPDB1"
      }
    }
  }
}

Docker image, demo schema, and the full environment reference live in the README. Current security controls and operator responsibilities are in SECURITY.md. The historical paper is here (PDF), and the deck summarizing its results is in slides/.