Acme Enterprise Capability Hub

A runnable teaching project for Model Context Protocol (MCP) in a realistic, polyglot enterprise environment.

The one idea it exists to demonstrate:

Claude/LLM sees BUSINESS CAPABILITIES, not underlying technologies. Claude asks for check_device_eligibility. MCP decides that answering it means calling a Java service, PostgreSQL, a Python library, a Node.js service, and a Java pricing library, in that order, and merging the results. Claude never sees any of that.

Read architecture.md for the full design (with diagrams). This README is the "how do I actually run it" doc.

What's actually running under the hood

A note on pragmatic tech choices: the Java services are plain-JDK (com.sun.net.httpserver), not Spring Boot, so the whole demo runs with just javac/java — no Maven, no internet access to a Maven repo required. They're genuinely Java, genuinely compiled, genuinely a separate process communicating over HTTP; they're just not wearing a framework. See architecture.md for the reasoning.

Related MCP server: Company API MCP Server

Prerequisites

• Python 3.11+

• Node.js 18+

• A JDK (8+) — javac and java on your PATH

• Docker Desktop (for PostgreSQL / MongoDB / Elasticsearch / Qdrant / MinIO)

1. Install dependencies

python -m venv .venv
make install

(make install runs pip install -r requirements.txt into .venv and npm install in both Node services. No make? See the equivalent raw commands in each Makefile target — they're two or three lines each.)

2. Start the data stores

make db-up      # docker compose up -d: Postgres, MongoDB, Elasticsearch, Qdrant, MinIO
make seed       # seeds MongoDB, Elasticsearch, Qdrant, MinIO with demo data
                 # (Postgres seeds itself on first boot via database/postgres/init.sql)

Port note: Postgres is published on host port 55432, not 5432 — many dev machines already have a local PostgreSQL install on 5432 (or even 5433 if you have two versions installed). Check docker compose ps and .env.example if you ever need to confirm the mapping.

3. Build the Java pieces and start the mock services

make build-java     # javac --release 8, plain JDK, no Maven
make run-services   # starts java-customer-service, node-inventory-service,
                     # graphql-service, grpc-network-service, soap-legacy-service,
                     # mock-crm, event-bus-service - logs to logs/*.log

Verify everything is up:

curl http://localhost:8081/health   # java-customer-service
curl http://localhost:3000/health   # node-inventory-service
curl http://localhost:4000/health   # graphql-service
curl http://localhost:8083/health   # soap-legacy-service
curl http://localhost:8090/health   # mock-crm
curl http://localhost:8095/health   # event-bus-service

4. Register the MCP server with Claude Code

This project ships a project-level .mcp.json already pointing at .venv/Scripts/python.exe mcp_server/server.py with every backend URL wired up. Just open this folder in Claude Code — it will pick up .mcp.json automatically. To use Claude Desktop instead, copy claude_desktop_config.json.example into your Claude Desktop config and replace the example paths with your actual clone location (Claude Desktop requires absolute paths).

5. Try it

Ask Claude Code things like:

• "What MCP tools does the acme-enterprise-capabilities server expose?"

• "Is customer C123 eligible for an iPhone 17 Pro?"

• "Show me overdue invoices for customer C123, then explain what happened internally."

See Demo scenarios below for a full script, and Claude Code experience for how to ask Claude to explain the plumbing without it ever appearing in the tool descriptions themselves.

Demo data

Three seeded customers to experiment with:

Devices: iphone-17-pro (in stock), iphone-17 (in stock), galaxy-s26-ultra (out of stock), pixel-10-pro (low stock).

Demo scenarios

Each of these is a real prompt you can give Claude Code once the server and mock services are running. "Expected" describes what you should see in the server logs (make logs) as well as Claude's answer.

1. "Create a customer named John Smith with email john@example.com." create_customer → Java REST customer service.

2. "Show me all overdue invoices for customer C123." find_overdue_invoices → PostgreSQL. Returns 2 overdue invoices.

3. "Check the credit status of C123." check_customer_credit_status → PostgreSQL (inputs) + Python credit-risk library. Returns FAIR (tenure is good, but 2 overdue invoices drag it down).

4. "Is customer C123 eligible for an iPhone 17 Pro?" check_device_eligibility → Java → PostgreSQL → Python → Node.js → Java pricing library. Returns eligible: true, discount: 112.5.

5. "Find contracts mentioning international roaming." search_customer_contracts → Elasticsearch full-text search.

6. "What are the eligibility rules for the Premium 5G plan?" search_product_knowledge → Qdrant semantic search over the knowledge base.

7. "Get the latest contract document for C123." retrieve_customer_document → MinIO/S3.

8. "Create a support ticket for C123 because they can't make international calls." create_support_case → mock CRM.

9. "Check whether C123 passes compliance." run_compliance_check → Java → PostgreSQL → SOAP → Python. Returns compliant: false, flag MULTIPLE_OVERDUE_INVOICES (try C789 for a fraud-flag failure instead).

Bonus — the "bad vs good" lesson, in one prompt: "Would you ever expose a tool called execute_sql to me? Why does this server use find_overdue_invoices instead?" Claude can answer this directly from the tool descriptions it's been given — none of which mention SQL.

Claude Code experience

Useful things to ask once the server is registered:

• "What MCP tools are available?" — lists all 21 business-capability tools, with zero mention of Java/Postgres/gRPC/etc.

• "What tool would you use to check device eligibility?" — Claude should answer check_device_eligibility from the tool description alone.

• "Call the device eligibility capability for C123 and the iPhone 17 Pro." — invokes the real 5-adapter orchestration.

• "Explain what happened internally." — this is the interesting one. Claude can only answer from the JSON result it got back (customer name, credit status, discount, etc.) — it has no visibility into which adapters ran, in what order, or what the raw Postgres/HTTP calls looked like, because that's deliberately never exposed through MCP. You get that story by reading the server logs (make logs) or the walkthroughs in architecture.md §7 and §9 — which is the whole point: the capability boundary is real, not just a naming convention.

Running the tests

make test
# or directly:
.venv/Scripts/python.exe -m pytest tests/ -v

The suite has two layers:

• Unit tests (tests/adapters/, tests/capabilities/, tests/test_models.py, tests/test_server.py) — HTTP-mocked (via respx) or subprocess-mocked, run anywhere, no Docker or mock services required. Cover adapter success paths, NOT_FOUND/timeout/backend-unavailable failure paths, Pydantic validation rejection, and — for the two flagship capabilities — that every expected adapter actually gets called (and that the Java pricing subprocess is skipped when the customer isn't eligible).

• Integration tests (tests/integration/) — hit the real docker-compose stack and real mock services. Each self-skips via a requires_backend marker if its backend isn't reachable, so pytest stays green even before you've run make db-up. Run make db-up && make seed && make build-java && make run-services first to exercise all of them, including a real-subprocess, real-HTTP, real-SQL run of check_device_eligibility.

Viewing logs

make logs                     # tails logs/*.log for all mock services
docker compose logs -f        # data store logs

The MCP server itself logs to stderr with the [MCP TOOL] / [CAPABILITY] / [ADAPTER] / [CALL] / [ADAPTER RESULT] structure described in architecture.md §9 — when Claude Code launches it, that output shows up in Claude Code's MCP server log viewer; when you run make run-mcp directly, it prints straight to your terminal.

Inspecting tools directly (no Claude needed)

make tools

Prints every registered tool name and the first line of its description — useful for confirming the "Claude sees capabilities, not technology" claim for yourself.

Stopping everything

make stop-services   # kills the 7 mock service processes
make db-down          # docker compose down (add -v to also drop volumes/data)

Project structure

acme-enterprise-mcp/
├── mcp_server/
│   ├── server.py              MCP tool definitions (the only file Claude talks to)
│   ├── models.py               Pydantic request models + structured error types
│   ├── config.py                Environment-driven settings (every backend URL)
│   ├── observability.py         Correlation-ID logging ([MCP TOOL]/[CAPABILITY]/[ADAPTER]/...)
│   ├── adapters/                One class per technology (15 adapters)
│   └── capabilities/             Business logic + orchestration (6 files)
├── services/                    Mock backend services (Java, Node, Python)
├── libraries/                   Java pricing "library" + Python credit-risk library
├── database/                    Postgres schema+seed, Mongo seed
├── documents/                   Sample contracts (for Elasticsearch) + knowledge base (for Qdrant)
├── scripts/                     Seed scripts + the internal billing-report CLI utility
├── tests/                       Unit + integration tests
├── docker-compose.yml            Postgres / MongoDB / Elasticsearch / Qdrant / MinIO
├── capability-registry.yaml      Documentation: capability -> adapters -> technology map
├── architecture.md               Full design doc with diagrams
├── .mcp.json                     Claude Code MCP server config (this project)
└── claude_desktop_config.json.example

Environment variables

See .env.example for the full list (every backend URL, credential, and timeout). Copy it to .env if you want to override anything — mcp_server/config.py loads it via python-dotenv. Docker Compose reads plain values baked into docker-compose.yml directly (this is a local demo; there are no real secrets anywhere in this repo).