Developer Guide

Use the codebase MCP server in Claude Code.

A stdio MCP server that gives any Claude Code session grounded retrieval over the Finverity repositories (backend, frontend, infrastructure). It is a thin client over the running API, so your session and the web UI share the same indexing and search path.

Step 1

Prerequisites

The MCP server talks to the local API, so each developer needs the stack running on their own machine. Requires Node 22+.

# 1) Start the stack (API on :4000)
docker compose up -d
curl -s localhost:4000/api/health        # should return JSON

# 2) Install deps and build the MCP server
npm install
npm run build --workspace @finverity/codebase-chat-mcp

Step 2

Add it to Claude Code

Run claude from the repository root. This repo ships a committed .mcp.json, so Claude Code detects it and asks you to approve the finverity-chat server (project-scoped servers require approval). Approve once and every developer who clones the repo gets the same config.

{
  "mcpServers": {
    "finverity-chat": {
      "command": "node",
      "args": ["apps/mcp/dist/index.js"],
      "env": { "API_BASE_URL": "http://localhost:4000/api" }
    }
  }
}

Prefer the CLI? One command (same result):

# Shared with the team (writes .mcp.json) — run from the repo root:
claude mcp add finverity-chat --scope project \
  --env API_BASE_URL=http://localhost:4000/api \
  -- node apps/mcp/dist/index.js

# Verify:
claude mcp list
claude mcp get finverity-chat

Scopes: local = just you in this repo · project = committed .mcp.json, shared · user = all your projects (needs an absolute path). Inside a session, run /mcp to confirm the server is connected.

Reference

Tools

You don't call these by name — just ask, and Claude Code picks them up. They surface as mcp__finverity-chat__<tool>.

Tool	What it does	Arguments
`list_sources`	List the indexed repositories (id, label, root path).	`—`
`search_codebase`	Retrieve ranked, grounded citations for a question.	`query (required), sourceIds?, limit? (1–20)`
`sync_sources`	Trigger a reindex of one or more repositories.	`sourceIds?, dryRun?, force?`

Try it

Example prompts

Use finverity-chat to list the indexed repositories.
Search the codebase for where MFA calls the Vasco API in sso-service.
Find the backend routes for SSO settings — limit to 5 citations.
Reindex the backend source, then search for the instrument-funding worker flow.

Config & fixes

Configuration & troubleshooting

API host: set API_BASE_URL (default http://localhost:4000/api) if the API runs elsewhere. Keep the trailing /api.
✗ failed / ECONNREFUSED: the API isn't up — run docker compose up -d and check curl localhost:4000/api/health.
Cannot find dist/index.js: not built, or claudewasn't started from the repo root — run the build, launch from the root (or use an absolute path with --scope user).
Server doesn't appear: approve it when prompted, or re-trigger with claude mcp reset-project-choices; check claude mcp list.

Full write-up lives in apps/mcp/README.md and docs/mcp-surface.md in the repository.