Finn as an MCP tool

@riseanalytics/finn-mcp is an MCP server that exposes Finn as a single tool, ask_finn, to any MCP-compatible agent — Claude Desktop, Cursor, Claude Code, and others. It’s built on the Finn SDK: same connection, same streaming, wrapped as a tool.

Add it to your MCP client

Drop this into your MCP client’s server config (e.g. Claude Desktop’s claude_desktop_config.json or Cursor’s MCP settings):

{
  "mcpServers": {
    "finn": {
      "command": "npx",
      "args": ["-y", "@riseanalytics/finn-mcp"],
      "env": {
        "FINN_URL": "https://finn.example.com",
        "FINN_API_KEY": "your-api-key"
      }
    }
  }
}

Your agent now has an ask_finn tool.

Configuration

The server is configured entirely through environment variables.

Variable	Required	Default	Description
FINN_URL	yes	—	Base URL of the Finn backend.
FINN_API_KEY	yes	—	Your static API key.
FINN_SYSTEM_PROMPT	no	—	Finn’s persona for this server, applied to new conversations only.
FINN_TIMEOUT_MS	no	60000	Per-call ceiling (connect + full turn) before the tool returns a timeout.

If FINN_URL or FINN_API_KEY is missing, the server exits at startup with a clear error — so a misconfigured server fails fast instead of hanging.

The ask_finn tool

Input

Field	Type	Required	Description
question	string	yes	The question to ask Finn, in plain English.
conversationId	string	no	Continue a prior thread. Omit to start fresh.

Output — the synthesized answer as text, plus structured metadata your agent can thread:

{
  "conversationId": "conv-…",
  "messageId": "msg-…",
  "tokenUsage": { "input": 412, "output": 88, "total": 500 },
  "turnState": "idle"
}

To ask a follow-up in the same thread, pass the returned conversationId back on the next ask_finn call.

Note

The system prompt is set per server via FINN_SYSTEM_PROMPT, not per tool call — and like the SDK, it applies only when a new conversation is created.

How it relates to the SDK

	@riseanalytics/finn-sdk	@riseanalytics/finn-mcp
Caller	Your code	An AI agent
Interface	FinnClient API	ask_finn MCP tool
Streaming	Token-by-token	Final answer (agent-facing)
System prompt	Client option / per-call	FINN_SYSTEM_PROMPT env

Same Finn underneath. If you need fine-grained control or live token streaming, use the SDK; if you want an agent to call Finn as a tool, use the MCP server.