How do I use customer-data-mcp?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@customer-data-mcp Which customers have churned?" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

de en es ja ko ru zh

customer-data-mcp

by Haseeb-Ahmed-AI

Overview Schema Source Related Servers Discussions Admin

TypeScript

Local

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:

Tool	What it does
`search_customers`	Search by name, email, or company (partial match)
`get_customer_details`	Full profile for one customer, by exact ID
`get_customer_orders`	Order history for one customer
`list_customers_by_status`	Filter customers by status: active / inactive / churned
`get_customer_stats`	Total spend, order count, avg order value for one customer

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?"

Related MCP server: CRM MCP Server

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:

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.
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).
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.
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.

Available Tools

5 tools

get_customer_detailsA

Get the full profile for a single customer by their exact customer ID (e.g. 'CUST-0007'). Returns name, contact info, company, signup date, status, and order summary. If you only have a name or email, use search_customers first to find the customer ID.

ParametersJSON Schema

Name	Required	Description	Default
`customer_id`	Yes	The exact customer ID, e.g. 'CUST-0007'.

TDQS

A4.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It states that it returns a profile with specific fields, implying a read-only operation, but it doesn't explicitly confirm read-only behavior, error handling (e.g., not found), or any side effects. While adequate for a simple get, it could be more explicit about the safety and failure modes.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences with no filler. The core purpose is front-loaded, and the alternative usage is stated concisely. Every sentence contributes information, and there is no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter tool with no output schema and no annotations, the description covers the essential context: what it does, what it accepts, what it returns, and how to route when the ID is unavailable. It does not detail return structure or error cases, but given the tool's simplicity, this is reasonably complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% for the single parameter, so baseline is 3. The description adds value by giving an example format ('CUST-0007') and emphasizing 'exact customer ID', which clarifies that the value must match precisely. This goes beyond the schema's description to reduce ambiguity.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb 'Get' and a specific resource 'full profile for a single customer', and identifies the key identifier (customer ID). It distinguishes from the sibling search_customers by explicitly stating when to use that alternative, and it lists the returned fields, making the tool's purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says 'If you only have a name or email, use search_customers first', giving clear guidance on when to prefer an alternative. However, it does not address other siblings like get_customer_orders or list_customers_by_status, though the mention of 'order summary' hinted at potential overlap. The guidance is helpful but not exhaustive.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_customer_ordersA

Get the full order history for a single customer by their exact customer ID (e.g. 'CUST-0007'). Returns a list of orders, each with an order ID, date, product, amount, and order status. If you only have a name or email, use search_customers first to find the customer ID.

ParametersJSON Schema

Name	Required	Description	Default
`customer_id`	Yes	The exact customer ID, e.g. 'CUST-0007'.

TDQS

A4.1/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It implies read-only behavior via 'Get' but does not explicitly state non-mutating or any error/edge-case behavior. It does describe the return structure (list with fields), which adds some value, but lacks disclosure on empty results, pagination, or access requirements. For a simple read operation this is adequate but not rich.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the primary action and example. The second sentence adds return details and a redirect to search_customers. Zero waste, every clause earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter read tool with no output schema, the description fully explains what it returns (list with order fields) and provides an alternative when prerequisites are unmet. There is no missing information an agent needs to invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the schema itself documents customer_id with the same example and description. The description adds the qualifier 'exact' and repeats the example, but this is marginal beyond the schema. Baseline 3 is appropriate since the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool gets the full order history for a single customer by exact customer ID, with the example 'CUST-0007'. It also specifies return fields, making the purpose unambiguous. It does not explicitly contrast with every sibling, but it does name search_customers as an alternative, which helps differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear usage context: use when you have the exact customer ID, and if you only have a name/email, use search_customers first. This explicitly sets a condition for when not to use this tool. However, it does not mention other siblings like get_customer_details or get_customer_stats, so coverage of alternatives is incomplete but sufficient for basic routing.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_customer_statsA

Get summary spend statistics for a single customer by their exact customer ID (e.g. 'CUST-0007'): total order count, total spend (excluding cancelled/refunded orders), average order value, and lifetime value. Use this for questions about how much a specific customer has spent, rather than their raw order list.

ParametersJSON Schema

Name	Required	Description	Default
`customer_id`	Yes	The exact customer ID, e.g. 'CUST-0007'.

TDQS

A4.1/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It discloses a key behavioral detail—total spend excludes cancelled/refunded orders—which is essential to interpret the output. However, it does not cover edge cases like nonexistent customer IDs or permission requirements, but for a read-only summary tool this is acceptable.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences: the first lists the purpose and metrics, the second gives usage guidance. The phrase 'e.g. CUST-0007' repeats the schema example, but the description is otherwise efficient and front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter read tool with no output schema, the description adequately covers the return values (metrics listed), a hidden behavioral detail (exclusion of cancelled/refunded), and clear usage context. No critical information is missing for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%; the schema already describes customer_id with an example. The description reinforces 'exact' and repeats the same example, adding no new semantic information. It meets the baseline for high schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb ('Get'), the resource ('summary spend statistics for a single customer'), and specifies the exact metrics returned (total order count, total spend, average order value, lifetime value). It also explicitly differentiates from raw order lists via the phrase 'rather than their raw order list,' distinguishing it from the sibling get_customer_orders.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides an explicit when: 'Use this for questions about how much a specific customer has spent,' and a when-not with an alternative: 'rather than their raw order list.' This gives clear guidance without ambiguity.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_customers_by_statusA

List all customers with a given status. Valid statuses are 'active', 'inactive', or 'churned'. Returns each matching customer's basic profile info. Use this for questions like 'show me all active customers' or 'which customers have churned?'

ParametersJSON Schema

Name	Required	Description	Default
`status`	Yes	The customer status to filter by.

TDQS

A4.2/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are present, so the description bears full responsibility for behavioral disclosure. It states that the tool returns 'basic profile info', implying a read-only operation and summarizing the output. It does not mention pagination, ordering, or potential limitations, but for a simple list-by-status tool this is sufficient. The description is honest and does not contradict any annotations (there are none).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two concise sentences: the first delivers the core action and valid values, the second states the return type and provides query examples. It is front-loaded with the essential purpose and contains zero filler, making it easy for an agent to parse quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter tool with no output schema and no annotations, the description covers the essential context: what it does, valid inputs, return nature, and usage examples. It does not mention pagination or any edge cases, but given the simplicity of the operation, this is adequate. A 5 would require addressing potential limitations or more specific return details, which are not critical here.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% — the single 'status' parameter already has an enum and a clear description. The description repeats the valid statuses and gives usage examples, which adds a little context but does not provide new semantic meaning beyond what the schema declares. This matches the baseline of 3 for full schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('List'), the resource ('all customers'), and the specific filter ('with a given status'). It also gives concrete example queries, which makes the purpose unambiguous. The verb 'list' distinguishes it from sibling tools like search_customers (search) and get_customer_details (single customer), so an agent can easily tell them apart.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit usage context with example questions ('show me all active customers', 'which customers have churned?'), telling the agent when to invoke this tool. However, it does not mention when not to use it or explicitly contrast with alternatives like search_customers or get_customer_details, so it stops short of the full 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_customersA

Search for customers by name, email, or company name. Performs a case-insensitive partial match, so 'smith' will match 'John Smith' and 'jane.smith@...'. Returns a list of matching customers with their basic profile info (does not include full order history — use get_customer_details or get_customer_orders for that). Use this when the user gives a name, email, or company rather than an exact customer ID.

ParametersJSON Schema

Name	Required	Description	Default
`query`	Yes	Search text to match against customer name, email, or company (partial match, case-insensitive). Example: 'smith', 'acme', 'john@example.com'.

TDQS

A4.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the behavioral burden. It discloses case-insensitive partial matching, indicates the return content ('basic profile info'), and explicitly excludes full order history, directing to other tools. It does not mention pagination or error behavior, but for a read-only search these are minor gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with the core purpose, each earning its place. No redundancy, and the secondary alternatives are mentioned succinctly without digressing.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple one-parameter search tool, it covers the essential context: what it matches, what it returns (basic profile), what it excludes (order history), and when to use it. It could elaborate on what 'basic profile info' includes, but given the single parameter and no output schema, this is adequate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema already fully documents the query parameter with description and example, covering the matching behavior (partial, case-insensitive). The tool description restates the same info but adds no new semantic detail beyond the schema, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description states a specific verb ('Search for customers'), identifies the resource ('customers'), and enumerates searchable fields (name, email, company). It also distinguishes from siblings by noting it's for partial text matches rather than exact IDs and mentions get_customer_details/get_customer_orders for order history, making it clear what this tool is for.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use: 'Use this when the user gives a name, email, or company rather than an exact customer ID.' It also guides toward alternatives for order history, providing clear when-to-use and when-not-to-use guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

5 tool updatesv1.0.0Aug 24, 2026
- First observedget_customer_details
- First observedget_customer_orders
- First observedget_customer_stats
- First observedlist_customers_by_status
- First observedsearch_customers

Deploy Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.4/5.0

Scored 2026-08-24 00:15 across 5 tools

Disambiguation5/5

Each tool has a clearly distinct purpose: search by name/email/company, get details by ID, get orders by ID, list by status, and get stats by ID. There is no overlap; the descriptions explicitly clarify when to use each (e.g., search_customers vs. get_customer_details).

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern using snake_case: search_customers, get_customer_details, get_customer_orders, list_customers_by_status, get_customer_stats. The verbs (search, get, list, get) and nouns are uniform and predictable.

Tool Count5/5

5 tools is well-scoped for a customer data server, sitting comfortably within the ideal 3-15 range. Each tool addresses a distinct query type without redundancy, making the surface concise and maintainable.

Completeness4/5

The tool set covers the core read-oriented workflows: search, details, orders, status-based listing, and stats. The only minor gap is a lack of a way to list all customers regardless of status (e.g., a list_customers tool), but list_customers_by_status can approximate this with a single status, and the domain appears read-only by design.

Maintenance

ActivityMaintained

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

StudioMeyer CrewOAuth
io.studiomeyer
Agent personas for Claude. 16 tools, 13 personas, 3 workflows. Zero extra API cost. Free.
Autonomous Agents Agent Orchestration
2
LeadFoxConnectOAuth
io.github.LeadFox-Shay
Marketo MCP server for AI. 130 tools to operate Marketo from Claude, Cursor, or ChatGPT.
Marketing CRM
2
Chat ThingOAuth
ai.chatthing
Build and manage AI-native customer support agents from Claude or any MCP client.
Customer Support Autonomous Agents AI & Machine Learning
2
AurentiaOAuth
fr.aurentia
Your Aurentia workspace — projects, CRM, tasks, deliverables — in Claude, Cursor or any MCP client.
CRM Project Management Workplace & Productivity
1

Related MCP Servers

Patient Data MCP Server
Biology & Medicine Databases
asanm11611622ubca006
F
license
A
quality
D
maintenance
Enables querying a synthetic patient dataset with tools to look up patients by ID, age, disease, name, and get statistics, connecting Claude Desktop to local data.
Updated 6 months ago (2026-03-12 06:45 UTC)
6
-
CRM MCP Server
CRM Databases
Cerennly
F
license
Not graded
quality
D
maintenance
Enables querying and managing a CRM database through natural language conversations with Claude Desktop.
Updated 6 months ago (2026-03-07 01:26 UTC)
-
visdemo-fusion-mcp
ERP Systems Finance
yedla26
F
license
Not graded
quality
B
maintenance
MCP server that connects Claude Desktop to an Oracle Fusion Cloud instance. It exposes suppliers, purchase orders, invoices, and project costs as callable tools.
Updated 2 months ago (2026-07-03 01:14 UTC)
-
MHTL Warehouse MCP Server
Databases Research & Data
SirojWongpitakroj
F
license
A
quality
C
maintenance
Enables Claude to query a local DuckDB warehouse containing mock motorcycle-loan data, with tools for customer search, insights, and read-only SQL queries.
Updated 2 months ago (2026-07-11 17:29 UTC)
5
-

mcp-oracle-claude desktop

What this project does

Project structure

Install and run locally

Register it in Claude Desktop

Example questions to try once connected

Swapping in Oracle AI Agent Studio

Testing

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

Available Tools

Tool Schema Changelog

Maintenance

Resources

Related MCP Connectors

Related MCP Servers