mcp-chat

Summary of how to implement a Neo4j-based chatbot MCP server.

MCP Server Design Principles

Tool Design — Design the Model's Behavior, Not an API

• Do not mirror a REST API. Instead of one tool per endpoint, group them by the task the model will perform.

• Keep the number of tools small, and make descriptions long. The description is a document that includes when to use/when not to use, argument examples, and return format. The description is the prompt.

• Design output within the token budget. Format it in a model-readable way instead of dumping raw JSON, and include limit + pagination arguments for large results.

Structural Standard Patterns

• Separate transport — stdio for local, Streamable HTTP for remote. Separating server logic from transport makes it easy to support both.

• Input validation via schema — The TS SDK declares tool arguments with zod schemas. Do not write validation by hand.

• Return errors as isError: true results, not throws. Include the cause and solution in the message so the model can read the error message and retry.

• In stdio, stdout is the protocol channel. Logs must go to stderr. A single console.log can kill the server.

• Block dangerous operations with code, not prompts. For example, reject write statements in a read-only tool, or force-inject LIMIT.

Development Workflow

1. Manual testing with MCP Inspector — npx @modelcontextprotocol/inspector node dist/index.js

2. Validate tool selection scenarios with an actual model — if the model picks the wrong tool, fix the description, not the code.

3. Test business logic (query validators, formatters) with unit tests independent of MCP.

Related MCP server: Neo4j GraphRAG MCP Server

4 Implementation Approaches

1. Use the Official Neo4j MCP Server As-Is

A method of connecting using only configuration with the official MCP server provided by Neo4j.

• mcp-neo4j-cypher — Provides tools (get_schema, read_cypher, write_cypher) for the LLM to query the schema and generate and execute Cypher directly.

• mcp-neo4j-memory — A long-term memory server that stores entities/relationships from conversations as a knowledge graph.

2. Custom MCP Server Using the Text2Cypher Approach

Create your own MCP server, but keep the tool as a general-purpose structure of "natural language question → Cypher generation → execution." Similar to the official server, but you have direct control over:

• Injecting schema descriptions (providing graph structure in the prompt)

• Query validation (enforcing read-only, enforcing LIMIT)

• Result formatting

3. Domain-Specific Tool Approach

Instead of leaving Cypher to the LLM, pre-define tools tailored to the domain. Each tool internally executes only parameterized Cypher.

search_person(name)          → 파라미터화된 Cypher 실행
get_relationships(id, depth) → 파라미터화된 Cypher 실행
find_path(from, to)          → shortestPath 쿼리 실행

4. GraphRAG Approach

Expose a single retrieve(query) tool that performs similarity search using Neo4j's vector index, then expands the graph (neighbor nodes, relationships) from matched nodes to build context.

retrieve(query)
  1. query 임베딩 → 벡터 인덱스 유사도 검색
  2. 매칭된 노드에서 그래프 확장 (이웃 노드, 관계 수집)
  3. 수집된 서브그래프를 컨텍스트로 반환

Recommended Combination

In practice, a 2 + 3 hybrid is a common pattern. Handle frequently asked questions with domain-specific tools, and use read-only Text2Cypher as a fallback for the rest.

Stack Reference

• TypeScript — @modelcontextprotocol/sdk

• Python — FastMCP