equisense-research MCP server

Thin Node.js MCP wrapper that exposes the EquiSense AI equity-research engine as a single tool:

| Tool | Endpoint | What it does | |---|---|---| | ask_equisense | POST /api/v1/research/ask | Natural-language Q&A over Indian-listed companies. Returns answer, detected company, intent, follow-up suggestions. |

Same brain the WhatsApp chat uses, just over MCP instead of WhatsApp.

Published on npm: equisense-research-mcp

Quick start

1. Generate a token (self-serve)

Log in to the EquiSense web app and open Settings → Claude → Connect Claude. You get a research-scoped, individually-revocable token, shown once. Copy it (the web UI even pre-fills the full config block for you).

The token authenticates as Authorization: Bearer <token> and is limited to the research API — it cannot trade, change account settings, or mint further tokens. Revoke it any time from the same Settings page; revocation takes effect immediately.

The old admin endpoint POST /api/v1/admin/auth/mint-mcp-token is deprecated — it issued full-account session tokens with no per-token revocation. Use Settings → Claude instead.

2. Register the MCP with Claude Code

Recommended (npx, no install):

claude mcp add equisense-research --scope local \
  --env EQUISENSE_BASE_URL=https://equisense.ai \
  --env EQUISENSE_MCP_TOKEN='<token from Settings → Claude>' \
  -- npx -y equisense-research-mcp

Alternative (global install):

npm install -g equisense-research-mcp
claude mcp add equisense-research --scope local \
  --env EQUISENSE_BASE_URL=https://equisense.ai \
  --env EQUISENSE_MCP_TOKEN='<token>' \
  -- equisense-research-mcp

3. Verify

claude mcp list

Should show equisense-research - ✓ Connected.

4. Try it

In any Claude Code session:

Use ask_equisense: bull case for OLAELEC

You should get back { answer, companyName, isin, detectedIntent, followUpQuestions, responseTimeMs }.

Environment variables

| Var | Default | Purpose | |---|---|---| | EQUISENSE_BASE_URL | http://localhost:8080 | Backend root URL | | EQUISENSE_TIMEOUT_MS | 90000 | Per-request timeout (research queries can take 30–90s) | | EQUISENSE_MCP_TOKEN | required | Scoped bearer token from Settings → Claude. Treat like a password. |

Security notes

• The token is research-scoped — it can only call the research API (/api/v1/research/*), enforced by the backend registering its authenticator only on those paths. It cannot trade, change account settings, or mint further tokens.
• The token is individually revocable from Settings → Claude. Revocation is immediate: a revoked token gets a 401 on the next call, with no signature-only fallback.
• Tokens last 90 days. The wrapper also sends the token as a legacy Cookie: ES_AUTH header so older admin-minted session tokens keep working during migration; new scoped tokens authenticate via Authorization: Bearer.
• Never commit the token. Never log it. Never paste it into chat.
• Each ask_equisense call counts against the user's AI_EQUITY_RESEARCH daily quota — same metering as the web UI.

Contributing / running from source

git clone [email protected]:shivanshu-dixit/equity-sense.git
cd equity-sense/mcp-server/equisense-research
npm install
npm test

Tests:

• test/unit.test.js — TOOLS shape, fetch body, HTTP error mapping (401/402/403/429/5xx)
• test/integration.test.js — fail-fast on missing env, stdio handshake + tools/list RPC

Local registration against from-source code (instead of npm):

claude mcp add equisense-research --scope local \
  --env EQUISENSE_BASE_URL=http://localhost:8080 \
  --env EQUISENSE_MCP_TOKEN='<token>' \
  -- node /absolute/path/to/equity-sense/mcp-server/equisense-research/index.js

Why Node?

The Java app (Spring Boot 3.1) is too old for the Spring AI MCP server starter (needs 3.4+). All research logic, LLM routing, and feature metering stay server-side in Java; this wrapper just speaks MCP.

Troubleshooting

| Symptom | Likely cause | Fix | |---|---|---| | FATAL: EQUISENSE_MCP_TOKEN env var is required on startup | Env var unset or empty | Pass --env EQUISENSE_MCP_TOKEN=... to claude mcp add | | Auth failed (HTTP 401) | Token expired, revoked, or auth.token.secret rotated | Generate a fresh token in Settings → Claude and update the env | | AI_EQUITY_RESEARCH quota exhausted (HTTP 402) | Daily quota hit | Wait until tomorrow OR upgrade the user's plan | | Rate limited (HTTP 429) | Transient | Retry in a few seconds | | Forbidden (HTTP 403) | User doesn't have AI_EQUITY_RESEARCH feature | Check the user's license/plan | | Hangs > 90s with no response | Backend research query timed out | Bump EQUISENSE_TIMEOUT_MS; check backend logs |

License

MIT