Model Context Protocol

What it is

POST https://genka.dev/mcp — a JSON-RPC 2.0 endpoint implementing the Model Context Protocol's Streamable HTTP transport (spec dated 2025-03-26). Each MCP tool maps 1:1 to a /latest/mf/* REST endpoint, so billing, rate-limit, scoping, and X-Genka-* 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/.

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 in Claude Code

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

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

Then export the key and restart Claude Code:

export GENKA_API_KEY=imk_live_...

The 12 tools below appear under MCP > genka in the tool palette. The full tool catalog ships in tools/list — the agent discovers schemas at runtime, you don't have to brief it.

Your first call

Ask Claude in plain English:

# prompt
"Find flexi-cap funds with 3-year Sharpe over 0.9, sorted by Sharpe."

# Claude calls mf_screener via MCP, returns 7 funds in 200ms:
PPFAS Flexi Cap        sharpe = 1.40
HDFC Flexi Cap         sharpe = 1.38
WhiteOak Flexi Cap     sharpe = 1.18
Bank of India Flexi    sharpe = 1.17
Invesco India Flexi    sharpe = 1.14
ITI Flexi Cap          sharpe = 1.12
ICICI Pru Flexicap     sharpe = 1.10

Tools (12)

Every tool maps to a /latest/mf/* endpoint. The "Tier" column is the credit cost per call — same as REST.

Workflows

Find defence funds with 5y Sharpe > 1.2

1. mf_capabilities                # learn theme=defence is valid
2. mf_screener({
     period: "5y",
     theme: "defence",
     sharpe_absolute_gte: 1.2,
     sort: "-sharpe_absolute",
     limit: 10
   })

Backtest 60% PPFAS + 40% HDFC Flexi Cap, monthly rebalance

1. mf_search({ q: "ppfas flexi cap" })   # resolve slug
2. mf_search({ q: "hdfc flexi cap" })    # resolve slug
3. mf_backtest({
     from: "2022-01-01",
     to:   "2024-12-31",
     allocation: [
       { slug: "ppfas-parag-parikh-flexi-cap", weight: 0.6 },
       { slug: "hdfc-flexi-cap",                weight: 0.4 }
     ],
     rebalance: "monthly"
   })

# → CAGR 20.57%, Sharpe 1.13, max DD -14.97%

How much do PPFAS and HDFC Flexi Cap overlap?

mf_overlap({
  slug: "ppfas-parag-parikh-flexi-cap",
  with: "hdfc-flexi-cap"
})

# → overlap_pct: 34.81%, common_count: 27

If I'd SIP'd ₹10K/mo into PPFAS for 7 years?

mf_sip({
  slug: "ppfas-parag-parikh-flexi-cap",
  from: "2018-01-01",
  to:   "2024-12-31",
  monthly_amount: 10000
})

# → invested ₹8.4L, current ₹19.6L, XIRR 23.86%

Auth + billing

Same X-API-Key header as REST. Each tool call deducts the credits in the table above. The MCP structuredContent block on every response carries:

• tier — the pricing tier the call resolved to
• credits_used — how many credits this call cost
• credits_remaining — balance after deduction

Agents can read these and self-throttle when the budget runs low. A 402 carries credits_required + hint so retries are mechanical.

Rate limits

600 req/min per key, shared across REST and MCP. Hitting the limit returns a JSON-RPC error with the equivalent of HTTP 429 and a Retry-After hint.

Versioning

Pin behavior to a published version with the genka-Version header (same as REST):

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

The metrics tool's compute_version field then reflects your pin. A paper citing “Sharpe 1.4 from genka @ 2026-04-25-caracal” can re-derive that exact number forever.

Non-Claude MCP clients

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

List the tools

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"}'

Call a tool

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}
    }
  }'

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.