agentic-mcp-gateway

Model Context Protocol (MCP)

tools into an agentic loop for operations work: retrieve policy from a local knowledge base (RAG), search mock payments, and open tickets — the same shape as production copilots that sit in front of core banking / ops APIs, without any proprietary code.

This repository is original demo software by Md Tanvir Alam. It uses generic payments, KYC, and interbank-messaging concepts only.

Architecture

flowchart LR
  subgraph Client
    Recruiter["CLI / curl / MCP client"]
  end

  subgraph HTTP["Optional FastAPI"]
    Chat["POST /chat"]
    Health["GET /health"]
  end

  subgraph Agent["Agent loop"]
    LLM["LLM or FakeLLM stub"]
    ReAct["ReAct planner"]
  end

  subgraph MCP["MCP server"]
    T1["retrieve_docs"]
    T2["search_payments"]
    T3["create_ticket"]
  end

  subgraph Data
    KB["Markdown KB + hash embeddings"]
    SQLite["SQLite mock ledger / tickets"]
  end

  Recruiter --> Chat
  Recruiter --> MCP
  Chat --> ReAct
  ReAct --> LLM
  ReAct --> T1 & T2 & T3
  MCP --> T1 & T2 & T3
  T1 --> KB
  T2 --> SQLite
  T3 --> SQLite

The MCP server and the HTTP agent share one tool registry. That is the production pattern: expose the same typed capabilities over stdio/SSE for IDE agents and over HTTP for a product UI.

Quick start

Python 3.11+ (3.12/3.13 fine). No API key required.

python3 -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.txt

# tests — FakeLLM, hash embeddings, in-memory SQLite
pytest -q

# HTTP demo
cp .env.example .env
PYTHONPATH=src python -m uvicorn agentic_mcp_gateway.http_app:app --port 8080

Try a session:

curl -s localhost:8080/health
curl -s localhost:8080/chat -H 'content-type: application/json' \
  -d '{"message":"Find payment PMT-1002 and open a ticket if it is stuck"}'

MCP stdio (for Claude Desktop / Cursor-style clients):

PYTHONPATH=src python -m agentic_mcp_gateway.mcp_server

Docker:

docker compose up --build
# then the same curl against localhost:8080

How MCP tools map to production

Demo tool	What a real platform would wrap	Guardrails you would add
retrieve_docs	Policy / product RAG over Confluence, runbooks, ISO 20022 notes	ACL per tenant, citation required, stale-doc TTL
search_payments	Read API over a payments bus or investigation store	Field-level masking, audit log, query cost limits
create_ticket	Case management / Jira / ServiceNow write path	Idempotency keys, maker-checker, PII scrubbing

The agent is a small ReAct loop: think → pick a tool → observe → repeat, then answer. With LLM_PROVIDER=fake the planner is deterministic so CI never needs OpenAI. Set LLM_PROVIDER=llm and OPENAI_API_KEY to swap in a real chat model; the tool contracts stay identical.

Embeddings default to hashed character n-grams (numpy cosine). That is a documented demo fallback — swap HashingEmbedder for a sentence-transformer or vendor embedding API without changing the retriever interface.

Project layout

src/agentic_mcp_gateway/   package
  tools/                   retrieve / payments / tickets
  agent.py                 ReAct + FakeLLM
  mcp_server.py            MCP stdio server
  http_app.py              FastAPI /chat
docs/kb/                   sample ops knowledge
tests/                     tool registry, RAG, mocked agent turn

Author

Md Tanvir Alam — github.com/tanvir-ux

MIT licensed. Not affiliated with any bank or core-banking vendor.