finanal-mcp

A minimal, token-efficient MCP server that combines stock prices and fundamentals with the macro and micro narrative around them — so an AI agent can reason about why a stock moved, what people are thinking about it, and what probable scenarios lie ahead.

Why this project exists

Knowing a stock's PE ratio or current price is not enough. The interesting questions are: why did this stock dip today? What does the market narrative say about it? What are the macro tailwinds or headwinds? What could happen next?

Answering those questions requires combining three things simultaneously:

• Fundamentals and price data — earnings, ratios, revenue growth, institutional flows

• Real-time news and macro context — what analysts, media, and macro events are saying

• The narrative — sentiment, concall tone, sector rotation, management guidance

The tools chosen — FMP, Tapetide, and Tavily — are the best available for each of those jobs. FMP is the gold standard for US stock fundamentals. Tapetide is purpose-built for Indian NSE/BSE data with native MCP support. Tavily is a research-grade search engine that retrieves and synthesises real-time financial news.

Why not use the existing MCP servers for these tools directly?

All three providers publish their own MCP servers, but each exposes 50–100+ individual tools. Every tool description gets embedded into the system prompt of every LLM call. With three servers active that's potentially 150–300 tool descriptions injected into every single prompt — input tokens explode, costs spike, and the LLM gets confused by the noise.

This project is the solution: one MCP server, 6 tools maximum. The LLM talks to a single router that knows which underlying API to call, how to call it, and what parameters to use. The input token footprint stays flat no matter how many endpoints exist in the index.

finanal-mcp in one sentence: ask any financial question in plain English — the server finds the right API, calls it, and caches the answer for instant reuse.

Related MCP server: financial-research-agent

Why it is built this way

Source routing rules

These rules are enforced both in the search_apis tool description and in seeded recipes, so any LLM using this server learns them from the first call.

Why not just use prompt caching?

A fair question: FMP, Tapetide, and Tavily each publish their own MCP servers. If you registered all three directly, the LLM would have the full tool list in its context. And since modern LLMs (Claude, GPT-4o) cache the system prompt, subsequent calls would hit the cache at ~90% discount — so it would barely cost anything after the first call, right?

Prompt caching fixes the wallet problem. This architecture fixes the brain problem. Even with perfect cache hits, monolithic tool registrations still fail in three ways:

1. Cache eviction tax (TTL ~5–10 minutes)

Prompt caches are ephemeral. Most providers evict after 5–10 minutes of inactivity. If a user pauses to read, grabs a coffee, or writes a long reply — the cache evicts. The very next turn re-indexes all 150–300 tool schemas at 1.25× the base rate (cache-write premium), and the full cost resets. With 6 tools and ~159 tokens of descriptions, a cache eviction costs fractions of a cent. The TTL problem simply disappears.

2. Model attention tax ("lost in the middle")

Even if holding 200,000 tokens of tool schemas in context is cheap, it is not free for the model's reasoning. When an LLM has to parse 500 tool schemas simultaneously its retrieval accuracy degrades measurably — it hallucinates optional parameters, confuses endpoints with similar names, and dilutes attention on the actual task. By routing through search_apis first, the model only sees the 3–4 tools it actually needs for that specific turn. Attention stays sharp.

3. Context window starvation

Every model has a hard context limit. If 200,000 tokens are permanently occupied by monolithic tool schemas, that is 200,000 fewer tokens available for conversation history, API response payloads, and deep reasoning. For a tool-heavy financial workflow where API responses can be large, this matters.

The compounding win: recipes

The deeper lever is the recipe cache. A recipe hit means the model calls exactly one tool (search_recipes) instead of the usual three (search_recipes → search_apis → get_api_details → call_api). Every question answered correctly makes the next identical question instant and near-zero cost. The system gets cheaper and more accurate over time.

Measured token budget

Architecture

Copilot / LLM agent
        │
        ▼
  finanal-mcp (stdio)
  ┌─────────────────────────────────────────────┐
  │  search_recipes  ← check cache first        │
  │  search_apis     ← BM25 + synonym index     │
  │  get_api_details ← full schema for endpoint │
  │  search_docs     ← BM25 doc search          │
  │  call_api        ← live API call            │
  │  save_recipe     ← cache successful answer  │
  └──────────────┬──────────────────────────────┘
                 │  routes by source field
       ┌─────────┼──────────┐
       ▼         ▼          ▼
    FMP REST  Tavily REST  Tapetide MCP
    (US/global) (news)     (India NSE/BSE)

Prerequisites

• Python ≥ 3.14

• uv — brew install uv or pip install uv

• API keys for FMP, Tavily, and Tapetide (free tiers available for all three)

Setup

git clone <repo>
cd finanal
uv sync
cp .env.example .env
# Edit .env and fill in your three API keys

Get your keys:

• FMP: https://site.financialmodelingprep.com/developer/docs — free tier, 250 req/day

• Tavily: https://app.tavily.com — free tier, 1,000 credits/month

• Tapetide: https://tapetide.com/mcp — free token from settings

Seed the endpoint index

Run once after cloning (or after pulling updates):

uv run scripts/seed_fmp_scrape.py   # 236 FMP endpoints from official docs
uv run scripts/seed_tavily.py       # 7 Tavily endpoints
uv run scripts/seed_tapetide.py     # 49 Tapetide tool schemas
uv run scripts/enrich_docs.py       # 348 synthetic BM25 docs

Verify with smoke tests

uv run scripts/test_search.py
# Expected: 15/15 ✓ all rank-1

Run the MCP server

uv run python main.py

The server communicates over stdio and is consumed by VS Code / Copilot via the MCP protocol. You do not interact with it directly.

Register in VS Code (user-level — works in all workspaces)

Add to ~/Library/Application Support/Code/User/mcp.json (macOS) or the equivalent user-level mcp.json on your OS:

{
  "servers": {
    "finanal-mcp": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "python", "main.py"],
      "cwd": "/absolute/path/to/finanal"
    },
    "tapetide-mcp": {
      "type": "http",
      "url": "https://mcp.tapetide.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TAPETIDE_TOKEN",
        "Content-Type": "application/json",
        "Accept": "application/json, text/event-stream"
      }
    }
  }
}

Note: tapetide-mcp is registered separately as an HTTP server so Copilot can call its tools directly (faster path). finanal-mcp proxies through to it as well, but direct registration gives Copilot access to all 49 Tapetide tools without going through the router.

How to use it from Copilot Chat

finanal-mcp is a tool router, not a chat assistant. An LLM agent (Copilot, Claude, etc.) calls its tools to discover and invoke the right financial API. The mandatory workflow:

Step-by-step tool call order

1. search_recipes(query)
   └─ If score < -1.0 → use that recipe directly, skip to call_api. Done.

2. search_apis(query, source="fmp"|"tapetide"|"tavily")
   └─ Returns ranked endpoint list with id, summary, source, parameters.

3. get_api_details(endpoint_id)
   └─ Returns full parameter schema so call_api gets the right args.

4. call_api(endpoint_id, params={...})
   └─ Executes the live API call and returns the data.

5. save_recipe(question, summary, endpoint_ids=[...])
   └─ Always save after a good answer — next identical query is instant.

Example queries and what happens

Teaching the server new routing rules

Seed recipes directly:

import db
conn = db.get_conn()
db.upsert_recipe(
    conn,
    question="Get quarterly earnings for an Indian company",
    summary="Use tapetide get_financials (source=tapetide), section='profit_loss'.",
    endpoint_ids=[22],
)
conn.commit()

Or use the save_recipe tool from within a Copilot chat session after a successful answer.

DB state (after full seed)

Key files

main.py                      ← FastMCP server — 6 tools, source-aware call_api routing
db.py                        ← SQLite schema, FTS5 tables, BM25 search, synonym expansion
scripts/seed_fmp_scrape.py   ← Primary FMP seed (236 endpoints from scraped docs)
scripts/seed_fmp.py          ← Secondary FMP seed (community OpenAPI YAML, 181 endpoints)
scripts/seed_tavily.py       ← Tavily endpoint seed
scripts/seed_tapetide.py     ← Tapetide tool schema seed
scripts/enrich_docs.py       ← Synthetic BM25 doc generation (348 docs)
scripts/test_search.py       ← Smoke tests (15/15 expected)
specs/tavily.yaml            ← Hand-crafted Tavily OpenAPI spec
data/finanal.db              ← SQLite database (gitignored)
.env.example                 ← API key template
.github/copilot-instructions.md ← Copilot tool workflow instructions