Chat-Kisum-MCP-Node (AI agent + MCP)

Related documentation: Backend modules overview · Kisum System · Data ownership. Contrast: workspace repo Backend-MCP-Kisum (Go) is separate MCP tooling; do not confuse it with this Node stack.

Canonical implementation detail: repository Chat-Kisum-MCP-Node — start with README.md, then MCP.md for full diagrams, Compose samples, env matrix, tool I/O schemas, and security rules.

Upstream repo name: the implementation README sometimes refers to the GitHub repo as Chat-MCP-Node; this workspace folder is Chat-Kisum-MCP-Node.

Purpose

In one sentence (from MCP.md):

An AI agent can reason, decide, and use tools via MCP to answer questions using Kisum-linked data and external APIs.

Platform role:

Chat-Kisum-MCP-Node is an adjunct Node/TypeScript stack: Docker Compose orchestrates ai-agent-chat (Fastify brain + LangChain agent + MCP client) plus MCP HTTP microservices (mcp-kisum-data, mcp-search, mcp-rag, mcp-prediction, mcp-date), optional ai-memory-postgres for conversational persistence, and private access to MongoDB / third-party APIs as configured.

This page records cross-service positioning for Kisum docs. Tool payloads, Swagger, and Compose ports evolve in-repo — treat MCP.md as the living reference.

Mental model

User / client → ai-agent-chat (brain) → MCP containers (tools) → APIs / databases → answer JSON

The agent chooses which MCP tools run, in what order, and how outputs merge into the reply (vs a fixed DAG like n8n alone).
MCP servers are intentionally small, separate deployables: independent scaling, narrow credentials per tool surface, easier debugging (MCP.md rationale).

Target architecture (containers & data flows)

Adapted from MCP.md. Paths like /chat are logical; the running ai-agent-chat app mounts LangChain+MCP primarily at POST / unless an edge gateway rewrites paths (see HTTP chat contract).

flowchart TD
    USER[User / Frontend / BFF]
    EDGE[Reverse proxy optional]
    USER --> EDGE
    EDGE --> CHAT[ai-agent-chat]

    CHAT --> MEMORY[(ai-memory-postgres)]

    CHAT --> MCPKISUM[mcp-kisum-data]
    CHAT --> MCPSEARCH[mcp-search]
    CHAT --> MCPPREDICT[mcp-prediction]
    CHAT --> MCPRAG[mcp-rag]
    CHAT --> MCPDATE[mcp-date]

    MCPKISUM --> MONGO[(MongoDB artist read models)]
    MCPSEARCH --> BANDS[BandsInTown API]
    MCPSEARCH --> GOOGLE[Google Custom Search API]
    MCPPREDICT --> PREDICTAPI[Prediction HTTP backends / n8n / internal APIs]
    MCPRAG --> RAGAPI[Kisum RAG HTTP API]

Deployment / trust zones (Compose view)

Shows public vs private Docker network: only the agent ingress should publish host ports; MCP + Postgres stay on expose / internal DNS.

flowchart LR
    subgraph Public
        CLIENT[Caller]
        API[ai-agent-chat]
    end

    subgraph Private Docker network
        DB[(PostgreSQL memory)]
        MCP1[mcp-kisum-data]
        MCP2[mcp-search]
        MCP3[mcp-rag]
        MCP4[mcp-prediction]
        MCP5[mcp-date]
    end

    subgraph External deps
        MONGO[(MongoDB)]
        GOOGLE_EXT[Google CSE]
        BANDS_EXT[BandsInTown]
        RAG_EXT[Kisum RAG]
        PRED_EXT[Prediction services]
    end

    CLIENT --> API
    API --> DB
    API --> MCP1
    API --> MCP2
    API --> MCP3
    API --> MCP4
    API --> MCP5

    MCP1 --> MONGO
    MCP2 --> GOOGLE_EXT
    MCP2 --> BANDS_EXT
    MCP3 --> RAG_EXT
    MCP4 --> PRED_EXT

Main request lifecycle (happy path)

From MCP.md sequence diagram (JWKS verification + Postgres memory + MCP tool rounds).

sequenceDiagram
    participant U as Caller
    participant API as ai-agent-chat
    participant AUTH as JWKS
    participant MEM as PostgreSQL memory (optional)
    participant AGENT as LangChain agent
    participant MCP as MCP tool HTTP services

    U->>API: POST LangChain endpoint (typically / )
    API->>AUTH: Verify Bearer JWT or internal API key policy
    API->>MEM: Load thread history when sessionId + POSTGRES_URI
    API->>AGENT: User message (+ memory context + tools)
    AGENT->>MCP: Call tools as needed
    MCP-->>AGENT: Structured tool payloads
    AGENT->>MEM: Persist turn when configured
    AGENT-->>API: Final model output
    API-->>U: JSON response

Ownership (source of truth)

Concern	Owner
Users, memberships, sessions, JWT issuance	Auth
Company / BU master, entitlements	Core
Thread / conversational rows for this agent (`POSTGRES_URI` + request `sessionId`)	`ai-memory-postgres` / `ai-agent-chat` config — operational; not tenant master
Artist read paths used by `mcp-kisum-data`	Existing Kisum / Base semantics consumed via URIs — MCP must not redefine Auth/Core/Base ownership

Rule: Chat-Kisum-MCP-Node is AI tooling + orchestration. It must not become a second writer of companies, memberships, or commercial entitlements.

HTTP chat contract (`ai-agent-chat`)

Aligned with Swagger in Chat-Kisum-MCP-Node/ai-agent-chat and summarized in MCP.md §9 — with implementation path clarification:

Item	Detail
LangChain + MCP pipeline	`POST /` on the `ai-agent-chat` HTTP server — primary entry used with MCP tools.
Direct model shortcuts	`POST /gemini`, `POST /openai` — bypass the LangChain+MCP orchestration unless you route through `/`.
Logical aliases	Docs and gateways may expose the same payload as `POST /chat` or `POST .../webhook/chat` depending on Amplify/Lambda/API Gateway mappings — normalize at the proxy.

Request headers (tenant + auth)

Authorization: Bearer <JWT> — verified against configured JWKS (see repo env).
x-org: <company_uuid> — forward when callers need downstream tools or audit to respect Kisum tenancy ( MCP.md, README.md).
Service-to-service: optional X-Internal-API-Key when AUTH_INTERNAL_API_KEY is configured (see ai-agent-chat auth middleware) — follows internal-route patterns elsewhere in the workspace; browsers should still prefer JWT + canonical org context from the platform BFF, not leaked internal keys.

JSON body

Language route (POST /) — message is required.

{
  "message": "Can we do Dua Lipa in Singapore?",
  "sessionId": "stable-thread-id-optional"
}

sessionId — optional stable chat thread id (trimmed, ≤ 128 chars in ai-agent-chat). When present and Postgres chat memory (POSTGRES_URI / related config) is enabled, the service loads capped history (CHAT_MEMORY_MAX_MESSAGES per ai-agent-chat README / MEMORY). Omit for stateless turns. Reuse the same sessionId for every message in a thread so memory and caches stay aligned.

Successful responses include sessionId when the client sent a valid (non-empty, length-capped) sessionId — see ai-agent-chat chat-langchain.ts. Typical shape (MCP.md §9; fields may evolve):

{
  "model": "gemini-2.0-flash",
  "response": "…assistant text…",
  "usage": { "promptTokens": 0, "completionTokens": 0, "totalTokens": 0 },
  "cached": false,
  "sessionId": "same-stable-thread-id-if-sent"
}

Note: This is not Auth JWT sessionId (revocable login session). Here it identifies the AI chat thread only. market_prediction and similar tools may receive a correlated session_id derived from chat context (MCP.md §7).

MCP tool catalogue (high level)

Condensed from MCP.md §6–7. Detailed argument JSON and examples live in-repo.

Concern	MCP package	MCP tool names
Kisum Mongo artist lookup	`mcp-kisum-data`	`find_artist`, `get_artist_platforms` (plus `get_artist_by_id` where implemented)
External search	`mcp-search`	`bandsintown_events`, `google_search`
Predictions / feasibility	`mcp-prediction`	`artist_market_prediction`, `market_prediction`
Internal RAG	`mcp-rag`	`rag_search`
Utilities	`mcp-date`	`today_date`

Prediction tools call configured HTTP backends; market_prediction accepts a session_id field for correlated calls (MCP.md §7).

Components (repos paths)

Path	Role
`ai-agent-chat/`	Fastify + JWT middleware + LangChain `createAgent` + `MultiServerMCPClient`; Redis cache hooks; Postgres thread memory optional.
`ai-memory-postgres/`	Postgres volume for conversational tables when Compose runs memory.
`mcp-kisum-data/`	Streamable HTTP MCP → Mongo artist tools.
`mcp-search/`	Streamable HTTP MCP → BandsInTown + Google CSE.
`mcp-rag/`	Streamable HTTP MCP → Kisum RAG URL (default example in `MCP.md`).
`mcp-prediction/`	Streamable HTTP MCP → artist/market prediction webhooks/APIs (`PREDICTION_INTERNAL_API_KEY` / org headers per service env).
`mcp-date/`	Lightweight date MCP.
`docker-compose.yml`	Pins in-network MCP URLs (`MCP__URL`), agent port (`3000:3000`* in current Compose example), `expose` for MCP listeners — never publish MCP ports publicly.

Compose YAML sample with env wiring (alternative port 8787 in MCP.md draft) belongs in MCP.md; keep this Starlight page high-level unless platform wiring changes materially.

Security rules (summary)

From MCP.md §10 — enforce in every environment:

Public ingress: ai-agent-chat only (host ports map).
Private: all mcp-* services + Postgres + Mongo — use Docker expose, not ports, toward the Internet.
Secrets: per-service env_file (.gitignore); never embed keys in repo docs.

n8n → MCP mapping (migration lens)

Historical reference (MCP.md §6): each old n8n “tool node” maps to one MCP or inner agent concern.

n8n-era concept	MCP / runtime
Find Artist	`mcp-kisum-data` → `find_artist`
BandsInTown / Google HTTP tools	`mcp-search`
Prediction workflow	`mcp-prediction`
RAG HTTP	`mcp-rag`
Simple Memory	Postgres memory in `ai-agent-chat`
JWT verify code step	`ai-agent-chat` middleware

Backend-MCP-Kisum — Go MCP / platform integration (different codebase; complementary).
Chat-Kisum-MCP-Node — Node Compose stack documented here.

When behavior, URLs, authentication, or tool contracts change materially, update repository CHANGELOG.md / MEMORY.md and this page (or defer detail to MCP.md and link only).