GoldenGate MCP Server

A production-grade Model Context Protocol server that exposes real-time banking data — replicated via Oracle GoldenGate CDC — as structured tools for AI agents and LLM clients.

The core banking system is treated as a black box. The server connects only to the downstream Oracle replica and optionally to Kafka topics, never to the source transactional system.

---

Tool Catalog

Read tools (read tier)

Tool	Description
get_entity	Fetch any entity (customer, account, transaction, alert) by type and ID
get_transaction_history	Paginated transaction history for an account (up to 365-day range)
get_realtime_events	Recent CDC change events from Kafka, with automatic Oracle fallback
get_gl_position	GL balance for a given account, currency, and value date
get_open_alerts	Query the alert queue by type and/or status

Score tools (score tier)

Tool	Description
score_event	LLM risk score (0–100) for any event — 180 ms hard timeout, never blocks
classify_alert	Fetch an alert and classify it as genuine or false positive
generate_report_draft	Draft a SAR / CTR / compliance summary — always includes human-review gate

Write tools (write tier)

Tool	Description
flag_entity	Flag, block, or unblock an entity via the configured write-back endpoint
post_adjustment	Post a GL correction, hold release, or workflow approval/rejection

Note: Write tools (flag_entity, post_adjustment) require WRITEBACK_BASE_URL to be configured. They are always registered but return a configuration error if called without it.

---

Architecture

AI Agent / LLM Client
        │  MCP protocol (stdio or HTTP)
        ▼
┌─────────────────────────────────────────┐
│         GoldenGate MCP Server           │
│                                         │
│  read_tools.py  score_tools.py          │
│  write_tools.py                         │
│       │               │                 │
│  OracleClient    AnthropicClient        │
│  KafkaConsumer   WritebackClient        │
│  SchemaMapper    CircuitBreaker         │
│  AuditLog                               │
└─────────────────────────────────────────┘
        │                    │
        ▼                    ▼
 Oracle GoldenGate     Kafka Topics
 replica (read-only)   (CDC events)

Key invariants:

• Schema mapping via schema_map.yaml — zero hardcoded column/table names in code
• All SQL in db/queries.py — zero inline SQL in tool logic
• Pydantic validation on every input before any DB or HTTP call
• Every tool call produces an immutable SHA-256-hashed audit log entry
• Every error message includes a suggested next step for the agent
• Prompt injection protection: user-controlled fields are always in separate structured content blocks, never interpolated into system prompts

---

Quick Start

1. Clone and install

git clone https://github.com/your-org/goldengate-mcp.git
cd goldengate-mcp
pip install -e ".[dev]"

Note: python-oracledb may not be on your corporate PyPI mirror. Install it separately:

pip install python-oracledb

2. Configure

Copy the example env file and fill in your values:

cp .env.example .env

Minimum required for read tools (real replica):

ORACLE_DSN=your-host:1521/ORCL
ORACLE_USER=mcp_reader
ORACLE_PASSWORD=your-password

Local testing without Oracle: leave ORACLE_PASSWORD empty (or omit it). The server starts and MCP tools still register; read/score tools that hit the database will error until you configure a working Oracle connection.

3. Run

# Streamable HTTP on http://127.0.0.1:8000/mcp (default when using Python directly — MCP Inspector)
python -m src.server

# stdio transport (Claude Desktop compatible) — requires fastmcp CLI on PATH
fastmcp run src/server.py

# Same HTTP as `python -m src.server` but via CLI (optional)
fastmcp run src/server.py --transport streamable-http --host 127.0.0.1 --port 8000

Direct python -m src.server uses Streamable HTTP bound to 127.0.0.1:8000. Connect the MCP Inspector to http://127.0.0.1:8000/mcp (transport: Streamable HTTP).

4. Docker

docker build -t goldengate-mcp .
docker run --env-file .env goldengate-mcp

---

Configuration Reference

All settings are loaded from environment variables (or .env file).

Variable	Default	Description
ORACLE_DSN	localhost:1521/ORCL	Oracle connection string
ORACLE_USER	mcp_reader	Oracle username
ORACLE_PASSWORD	(empty)	Non-empty = open replica pool at startup; empty = skip Oracle (local MCP testing)
ORACLE_POOL_MIN	2	Minimum pool connections
ORACLE_POOL_MAX	10	Maximum pool connections
ORACLE_QUERY_RETRY_ATTEMPTS	2	Retries on transient Oracle errors (0 = no retry)
ANTHROPIC_API_KEY	(optional)	Required for score tools
KAFKA_BROKERS	(optional)	Comma-separated brokers; leave empty to disable Kafka
KAFKA_CONSUMER_GROUP	goldengate-mcp	Kafka consumer group ID
WRITEBACK_BASE_URL	(optional)	REST endpoint for write tools; leave empty to disable
WRITEBACK_API_KEY	(optional)	Bearer token for write-back endpoint
WRITEBACK_TIMEOUT_SECONDS	10.0	HTTP timeout for write-back calls
CIRCUIT_BREAKER_WRITE_LIMIT	100	Max writes per minute before circuit trips
CIRCUIT_BREAKER_RESET_SECONDS	60	Circuit breaker window duration
RBAC_READ_ROLES	analyst,auditor,agent-read	Comma-separated roles for read tier
RBAC_SCORE_ROLES	analyst,agent-score	Comma-separated roles for score tier
RBAC_WRITE_ROLES	compliance-officer,agent-write	Comma-separated roles for write tier
RBAC_STRICT	false	Reject calls with no auth context
AUDIT_LOG_MODE	file	file or oracle — see docs/oracle_setup.sql for required DDL
AUDIT_LOG_FILE_PATH	audit.log	Path for file-mode audit log
SCHEMA_MAP_PATH	src/schema/schema_map.yaml	Path to schema mapping YAML

---

Schema Mapping

Physical Oracle table and column names live only in src/schema/schema_map.yaml. The server exposes logical names to agents.

Example — adding a new entity requires only a YAML edit:

entities:
  my_entity:
    table: BANKING.MY_TABLE
    columns:
      id: MY_PK_COL
      status: STATUS_CODE
      amount: TXN_AMOUNT

get_entity("my_entity", "123") works immediately — no code changes needed.

---

RBAC

Tools enforce role-based access via the MCP context metadata. Set the caller's role when configuring your MCP client:

{
  "mcpServers": {
    "goldengate": {
      "command": "fastmcp",
      "args": ["run", "/path/to/src/server.py"],
      "env": {
        "ORACLE_DSN": "host:1521/ORCL",
        "ORACLE_PASSWORD": "secret"
      }
    }
  }
}

Tier	Roles (default)	Tools
read	analyst, auditor, agent-read	All read tools
score	analyst, agent-score	All score tools
write	compliance-officer, agent-write	All write tools

Roles are configured via RBAC_*_ROLES env vars — no code changes needed to add roles.

---

Worked Example

Fraud triage loop — five tool calls to go from raw event to SAR draft:

1. get_realtime_events(topic="banking.transactions", lookback_minutes=5)
   → list of recent CDC events from Kafka (or Oracle fallback)

2. score_event(event=<event>, scoring_context={"account_type": "retail"})
   → { score: 87, decision: "review", reasoning: "...", confidence: 0.91 }

3. classify_alert(alert_id="A001", alert_type="fraud")
   → { is_false_positive: false, recommended_action: "escalate_to_compliance" }

4. flag_entity(entity_type="transaction", entity_id="T001",
               action="flag", reason="score 87/100, AML pattern match")
   → { status: "flagged", reference: "REF-2024-001" }

5. generate_report_draft(report_type="SAR", subject_id="C001",
                         evidence_ids=["A001", "T001"])
   → { draft_narrative: "...", HUMAN_REVIEW_REQUIRED: true }

---

Development

# Run tests (no Oracle, Kafka, or Anthropic account needed)
pytest

# Run with coverage
pytest --cov=src --cov-report=term-missing

# Lint
ruff check src tests

All 140 tests run against in-memory mocks — zero external dependencies required for development.

---

Supported Entities

Logical name	Oracle table	Used by
customer	BANKING.CUSTOMER_MASTER	get_entity, flag_entity
account	BANKING.ACCOUNT_MASTER	get_entity, get_transaction_history
transaction	BANKING.TRANSACTION_LOG	get_transaction_history, get_realtime_events
gl_entry	BANKING.GL_BALANCE	get_gl_position
alert	BANKING.ALERT_QUEUE	get_open_alerts, classify_alert

---

License

MIT