# MCP

`POST https://genka.dev/mcp` · JSON-RPC 2.0 · `X-API-Key` auth.

Genka is **MCP-native**. Every tool maps 1:1 to a `/latest/mf/*` REST
endpoint, so billing, rate-limits, scopes, and `X-Genka-*` response
headers behave identically. One handler chain, two surfaces.

## Where Genka fits in the Indian markets ecosystem

Genka is one tool in a stack. We're the **research layer** —
read-only, broker-agnostic. Each ecosystem service below has a focused
doc page with decision matrix, honest praise, composition snippet, and
code. Full landscape map at [/docs/ecosystem/](/docs/ecosystem/).

| If you need | Reach for | Doc |
|---|---|---|
| Place / modify orders, holdings, GTT (1st-party MCP) | Zerodha Kite MCP | [/docs/ecosystem/kitemcp/](/docs/ecosystem/kitemcp/) |
| Trade + ₹499/mo flat-data via REST | Groww API | [/docs/ecosystem/groww/](/docs/ecosystem/groww/) |
| Lowest-latency order pipe (sub-100ms, 25 ord/s) | Dhan API | [/docs/ecosystem/dhan/](/docs/ecosystem/dhan/) |
| Brokerage tied to a consumer wealth app (₹5/order) | INDmoney / INDstocks | [/docs/ecosystem/indmoney/](/docs/ecosystem/indmoney/) |
| Free Python OHLC for IN tickers (.NS / .BO) | yfinance | [/docs/ecosystem/yfinance/](/docs/ecosystem/yfinance/) |
| Free AMFI mutual fund NAV history | mfapi.in | [/docs/ecosystem/mfapi/](/docs/ecosystem/mfapi/) |
| Consumer dashboard / human UI | Tickertape | [/docs/ecosystem/tickertape/](/docs/ecosystem/tickertape/) |
| Fundamentals viewer for humans | Screener.in | [/docs/ecosystem/screenerin/](/docs/ecosystem/screenerin/) |

Most agentic stacks compose Genka with one of the brokerage APIs above:
research on Genka, execute on the broker. Each ecosystem page carries
the two-MCP `mcp.json` snippet.

## Setup (Claude Code)

Drop into `~/.config/claude/mcp.json`:

```json
{
  "servers": {
    "genka": {
      "transport": "http",
      "url": "https://genka.dev/mcp",
      "headers": { "X-API-Key": "${GENKA_API_KEY}" }
    }
  }
}
```

Then:

```bash
export GENKA_API_KEY=imk_live_...
```

Restart Claude Code. The 12 tools below appear under **MCP > genka**.

## Tools

| Name | What it does | Tier (credits) |
|---|---|---|
| `mf_search` | Two-stage fund search (BM25 + trigram fallback). Groups hits by `fund`, `theme`, `amc`, `category`. | search (5) |
| `mf_get_fund` | One fund: AMC, SEBI category, theme, TER, AUM, exit load, benchmark, status. | read (1) |
| `mf_get_metrics` | Risk metrics for one fund. Time-travel via `as_of`. Returns absolute + rolling distributions for cagr / vol / sharpe / sortino / max_dd / ulcer / upi / calmar plus benchmark group (alpha, beta, …) and tail risk (var_95, cvar_95, skew, kurt). | read (1) |
| `mf_screener` | Filter funds by any metric column. Filter grammar: `{metric}_{absolute|rolling_<stat>}_{op}=value`. Sort: `-col` for descending. | search (5) |
| `mf_compare` | Aligned NAV + metric matrix for 2–6 funds. Rebased-to-100 series for chart-ready output. | search (5) |
| `mf_capabilities` | Full discovery: every metric name, period, op, theme, factor, AMC, benchmark, snapshot date range, pricing tier. | free (0) |
| `mf_today` | Dataset heartbeat: counts, latest NAV date, latest metrics `as_of`, RBI risk-free rate. | free (0) |
| `mf_holdings` | Latest disclosed portfolio. Each row has `weight_pct` + `(ticker, sid)` for cross-reference into the equities universe. | read (1) |
| `mf_overlap` | Holdings overlap % between two funds + per-instrument breakdown. Symmetric: `overlap(A, B) == overlap(B, A)`. | compute (25) |
| `mf_backtest` | Multi-fund portfolio backtest with rebalance + survivorship transparency. Returns CAGR, vol, Sharpe, max DD, monthly returns, `inactive_funds_used`. | compute (25) |
| `mf_sip` | Monthly SIP simulation. Returns total invested, current value, units, absolute return, XIRR. | compute (25) |
| `mf_export` | Bulk pulldown of `funds | nav | metrics` as JSONL/CSV. | export (50) |

## Common workflows

### "Find defence funds with 5y Sharpe > 1.2"

```
> Claude calls mf_capabilities (to learn `theme=defence` is valid)
> then mf_screener(period=5y, theme=defence, sharpe_absolute_gte=1.2,
                   sort=-sharpe_absolute, limit=10)
```

### "Backtest 60% PPFAS + 40% HDFC Flexi Cap from 2022, monthly rebalance"

```
> Claude calls mf_search to resolve the slugs
> then mf_backtest({ from: "2022-01-01", to: "2024-12-31",
                     allocation: [{slug: "ppfas-...", weight: 0.6},
                                  {slug: "hdfc-...",  weight: 0.4}],
                     rebalance: "monthly" })
```

### "How much do PPFAS and HDFC Flexi Cap overlap?"

```
> Claude calls mf_overlap(slug=ppfas-..., with=hdfc-flexi-cap)
→ overlap_pct: 34.81%, common_count: 27 holdings
```

### "If I'd SIP'd ₹10K/mo into PPFAS for 7 years, what would I have today?"

```
> Claude calls mf_sip(slug=ppfas-..., from=2018-01-01, to=2024-12-31,
                       monthly_amount=10000)
→ invested: ₹8.4L, current_value: ₹19.6L, XIRR: 23.86%
```

## Auth + billing

Same `X-API-Key` as REST. Each tool call deducts the same credits as
the underlying endpoint. The MCP `structuredContent` block on every
response carries `tier`, `credits_used`, `credits_remaining` so an
agent can self-throttle when it sees the budget running low.

## Rate limits

600 req/min per key, shared across REST and MCP. 429 carries
`Retry-After`.

## Why agents should prefer MCP over REST

- **Self-describing.** `tools/list` returns name + input schema for
  every tool. The agent doesn't have to read `llms.txt` at runtime.
- **Schema validation upfront.** Bad arguments fail in the JSON-RPC
  envelope before reaching the API; you don't burn a credit on a
  validation 400.
- **One round-trip auth.** Agent connects once, then issues N tool
  calls in a single MCP session.
- **Lower context burn.** A `tools/call` envelope is ~150 tokens vs
  ~600 tokens to render a full HTTP request + response in REST.

## Non-Claude-Code MCP clients

Any MCP-compatible client works (Cline, Continue, custom). The
endpoint is plain JSON-RPC 2.0 over HTTPS; no SSE required.

`tools/list` example:

```bash
curl -s -X POST https://genka.dev/mcp \
  -H "X-API-Key: $GENKA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

`tools/call` example:

```bash
curl -s -X POST https://genka.dev/mcp \
  -H "X-API-Key: $GENKA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0","id":2,
    "method":"tools/call",
    "params":{
      "name":"mf_screener",
      "arguments":{"period":"5y","sharpe_absolute_gte":1.2,"limit":5}
    }
  }'
```

## Source + versioning

The MCP server is the same Worker that serves the REST API. Pin a
specific version via the `genka-Version` header (same as REST):

```json
"headers": {
  "X-API-Key": "${GENKA_API_KEY}",
  "genka-Version": "2026-04-25-caracal"
}
```

Setup is one config file. Trial is `$5` for 7 days, 500 credits. Get
a key at [/v1/auth/authorize](https://genka.dev/v1/auth/authorize?return=/dashboard.html).