mcp-oracle-claude desktop

A local MCP (Model Context Protocol) server that exposes customer data as queryable tools, so Claude can answer natural language questions about customers by calling this server directly.

Right now the data is mocked locally (data/customers.json, 28 fake customer records with order history). Later, the mock data layer can be swapped for a real connection to Oracle AI Agent Studio without touching any of the MCP tool code — see Swapping in Oracle AI Agent Studio below.

What this project does

It's a stdio-based MCP server with five tools:

Once registered in Claude Desktop as a custom connector, Claude can call these tools on its own to answer questions like "which customers have churned?" or "what has John Smith ordered?"

Project structure

/mcp-oracle-demo
  /data
    customers.json          # mock customer + order data
  /src
    data_source.ts          # ONLY file that touches raw data — the Oracle swap point
    server.ts                # MCP server entry point, registers all tools
    tools/
      search_customers.ts
      get_customer_details.ts
      get_customer_orders.ts
      list_customers_by_status.ts
      get_customer_stats.ts
  /test
    test_data_source.ts     # manual test walkthrough (npm test)
  package.json
  tsconfig.json
  README.md

Install and run locally

Requires Node.js 18+.

cd mcp-oracle-demo
npm install
npm run build      # compiles src/ -> dist/
npm start           # runs the compiled server over stdio

For local development without a build step:

npm run dev          # runs src/server.ts directly via tsx

To verify everything works before wiring it into Claude Desktop, run the test walkthrough, which exercises the data access layer and every tool handler and prints PASS/FAIL for each check:

npm test

A stdio MCP server doesn't print anything to stdout on its own (stdout is reserved for the protocol stream) — you'll see a customer-data-mcp server running on stdio line on stderr once it starts, and it will then wait for a client (like Claude Desktop) to connect.

Register it in Claude Desktop

Add an entry to your claude_desktop_config.json (Claude Desktop menu → Settings → Developer → Edit Config), pointing at the compiled server:

{
  "mcpServers": {
    "customer-data": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-oracle-demo/dist/server.js"]
    }
  }
}

Use an absolute path — Claude Desktop launches the process from its own working directory, not this project's folder. Restart Claude Desktop after saving the config, and you should see "customer-data" listed as a connected tool source (look for the 🔌 / tools icon in a new chat).

Example questions to try once connected

• "Show me all active customers."

• "What has [customer name] ordered?"

• "Which customers have churned?"

• "How much has customer CUST-0012 spent with us, and what's their average order value?"

• "Find any customers at Acme Co."

Swapping in Oracle AI Agent Studio

src/data_source.ts is the only file that touches raw customer data. Every MCP tool calls into its exported functions (getCustomerById, searchCustomers, getCustomerOrders, getCustomersByStatus, getCustomerStats) rather than reading the JSON file directly — so connecting to the real backend later means editing this one file, not the tool definitions or the server.

What would need to change inside data_source.ts:

1. Auth handling — add a token flow (e.g. OAuth client credentials or API key) for Oracle AI Agent Studio's API, likely reading credentials from environment variables instead of anything hardcoded, plus a short-lived token cache so we're not re-authenticating on every call.

2. Replace the local JSON read (loadCustomers()) with authenticated REST calls to Oracle's endpoints — e.g. GET /customers/{id}, GET /customers/search?q=..., GET /customers?status=... — and map Oracle's response shape onto the Customer / Order TypeScript interfaces already defined in that file (or adjust the interfaces if Oracle's schema differs).

3. Error handling — a real API can time out, rate-limit, or error in ways a local file read never does, so add try/catch and clear error messages the tools can surface back to Claude.

4. Caching — the current in-memory cache assumes static data; against a live backend this should either be removed or given a short TTL.

The full detail on each of these points is also commented directly at the bottom of src/data_source.ts.

Testing

npm test runs test/test_data_source.ts, which:

• Calls every data_source.ts function directly and checks results against known properties of the mock data (e.g. a known customer ID resolves, an unknown one returns null, search is case-insensitive).

• Calls every tool's handler function directly (bypassing the MCP transport) and checks the JSON it returns is well-formed and matches the underlying data.

This is a plain script (no test framework) so it's easy to read and explain line-by-line in a screen-share demo.