Documentation

Everything you need to integrate KundaliMCP into your agents.

Quickstart

Get an API key

Sign up at kundalimcp.com and create a key from your dashboard. All keys use the sutra_ prefix followed by live_ or test_ and 32 hex characters.

# Live key format
sutra_live_a3f7b2c91d4e5f608a1b2c3d4e5f6071

# Test key format (free, rate-limited)
sutra_test_9d8c7b6a5e4f3021bcde98765432abcd

Pass the key as a Bearer token in every request:

Authorization: Bearer sutra_live_a3f7b2c91d4e5f608a1b2c3d4e5f6071

Make your first call

All requests use JSON-RPC 2.0 over HTTPS. Call cast_chart with birth datetime and coordinates:

curl -X POST https://api.kundalimcp.com/mcp \
  -H "Authorization: Bearer sutra_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "cast_chart",
      "arguments": {
        "birth_datetime": "1990-01-15T05:00:00+05:30",
        "latitude": 28.6139,
        "longitude": 77.2090,
        "config": {
          "ayanamsa": "lahiri",
          "house_system": "whole_sign",
          "school_profile": "parashari"
        },
        "session_key": "my_session",
        "ttl": 900
      }
    }
  }'

Parse the response

The response contains a ChartArtifact — a content-addressed computation result. Key fields:

{
  "chart_hash": "sha256:abc123...",   // content-addressable ID
  "lagna": {
    "rashi": "Makara",
    "nakshatra": "Shravana",
    "nakshatra_pada": 2
  },
  "graha_positions": [
    { "graha": "Surya", "rashi": "Makara", "degree": 1.42,
      "nakshatra": "Uttarashada", "retrograde": false }
  ],
  "yogas": [
    { "yoga_id": "gajakesari", "is_active": true,
      "qualification": { "final_score": 0.87 } }
  ],
  "dasha_timeline": {
    "current_maha": { "graha": "Guru", "end_date": "2031-03-10" },
    "current_antar": { "graha": "Shukra", "end_date": "2027-09-12" }
  }
}

Save the chart_hash or pass session_key to subsequent calls — generate_narrative, query_transits, explain — without re-sending birth data.

Tool Reference

KundaliMCP exposes 13 MCP tools via tools/call. Discover them at runtime with tools/list.

Core — Chart computation

cast_chartcore

Computes a full Vedic birth chart (kundali) from birth datetime and coordinates. Returns planetary positions, house cusps, nakshatra placements, ShadBala strengths, Vimshopak scores, Ashtakavarga, Vimshottari dasha timeline, qualified yogas, divisional chart placements, strength profiles, afflictions, and influence profiles.

match_chartscore

Performs Ashtakoota (8-fold) compatibility matching between two natal charts. Returns per-koota scores, dosha assessments with cancellation logic, cross-chart graha overlaps, weighted composite score, and optional multi-school consensus. Supports inline ChartArtifact objects or cached session keys.

query_transitscore

Computes a planetary transit overlay for a natal chart over a specified date range. Returns current planetary positions, gochara (house-wise transit effects), Sade Sati status, active dasha period, and Ashtakavarga transit quality.

query_muhurthacore

Finds auspicious time windows (muhurtha) for a specified activity within a date range, evaluated against 170 muhurtha rules across panchang, planetary, and yoga factors. Optionally considers the native's natal chart for personalized muhurtha selection.

Analysis — Transits, forecasts & provenance

forecast_transitsanalysis

Generates a forward-looking transit forecast for a natal chart, identifying key planetary ingresses, station points, and dasha-transit confluences within the requested window. Returns ranked forecast windows with quality scores and domain tags (career, health, relationships, finance).

forecast_dashaanalysis

Generates a multi-level dasha forecast for a natal chart, projecting Maha, Antar, Pratyantar, Sookshma, and Prana periods over a requested window. Returns period-by-period domain activations, life-aspect overlays, and cross-dasha confluences.

forecast_eventsanalysis

Identifies high-probability life-event windows from the natal compendium overlays — 247 natal overlays, 34 life-event overlays — cross-referenced with current dasha and transit state. Returns ranked event windows with domain tags, supporting evidence, and timing confidence.

assess_natalanalysis

Performs a compendium-driven 9-area natal assessment using 247 natal overlays and 34 life-event overlays. Evaluates planetary patterns against the full classical compendium, returning area-by-area assessments with pattern matches, strength scores, and provenance citations.

explainanalysis

Returns the full IDL/CIL provenance chain for a specific interpretive claim — which rules fired, which IDL facts were inputs, which CIL weights were applied, and which schools dispute the conclusion. Designed for practitioner transparency and agent reasoning traces.

recommend_remediesanalysis

Suggests Jyotish remedial measures (upaaya) for identified afflictions, weak grahas, or active doshas in a natal chart. Returns gemstone recommendations, mantra prescriptions, fasting protocols, and charitable acts — all school-parameterized and ranked by efficacy score.

Narrative — Human-readable output

generate_narrativenarrative

Generates a deterministic Tier 1 narrative for a specific life domain from a computed natal chart. Uses the Narrative Fragment Library — no LLM involved, fully reproducible. Bilingual output (en + hi). Optionally requests Tier 2/3 analytical depth.

Meta — Discovery, profiles & feedback

describe_school_profilemeta

Returns the full parameter set for a named SchoolProfile — including active dasha system, house system default, yoga weights, Shadbala component weights, and CIL calibration thresholds. Use this to understand how a school profile will affect chart interpretation before calling cast_chart.

submit_feedbackmeta

Submits practitioner feedback on a specific interpretive claim to tune Calibratable Interpretive Layer (CIL) weights. Only CIL parameters are affected — IDL (ephemeris, classical tables, combinatorial rules) is immutable.

list_toolsmeta

Returns the complete list of available MCP tools with their names, descriptions, and input schemas. This is the MCP tools/list method.

list_resourcesmeta

Returns available MCP resources such as schema definitions, school profiles, and ayanamsa options.

get_schemameta

Returns the JSON Schema for a specific artifact type (ChartArtifact, MatchingArtifact, TransitOverlay, MuhurthaWindow, etc.).

Authentication

All requests require a Bearer token in the Authorization header. There are no query-parameter keys — tokens must travel in the header only.

Key formats

# Production
Authorization: Bearer sutra_live_<32 hex chars>

# Sandbox / test
Authorization: Bearer sutra_test_<32 hex chars>

Storage

Keys are stored as SHA-256 hashes — plaintext is never persisted. Copy your key immediately after creation; it cannot be recovered.

Rotation

Create and revoke keys from your dashboard at any time. Revoked keys return 401 immediately.

Transport

TLS 1.3 required on all endpoints. HMAC signing available for webhook callbacks.

Best practice

Never embed keys in client-side code. Use environment variables or a backend proxy.

Rate Limits

Tier	Per minute	Per day	Per month
Eval	10	500	500
Standard	120	50,000	50,000
High Traffic	600	200,000	200,000
Custom	Negotiated	Negotiated	Negotiated

Rate limit state is returned in every response:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1745500800

When a limit is exceeded the server responds with 429 Too Many Requests and a Retry-After header indicating seconds to wait before retrying.

Error Handling

Errors follow the JSON-RPC 2.0 error object format. Every error includes a machine-readable code, a human-readable message, and — where applicable — a data.hint field with a self-correction suggestion for agents.

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "Invalid params: birth_datetime must include timezone offset",
    "data": {
      "field": "birth_datetime",
      "hint": "Use ISO 8601 with offset, e.g. 1990-01-15T05:00:00+05:30"
    }
  }
}

Code	Meaning
-32602	Invalid params — missing or malformed input field
-32601	Method not found — unknown tool name
-32000	Computation error — ephemeris out of range or internal failure
-32001	Session not found — session_key expired or unknown
-32002	Boundary precision — chart has low-reliability varga placements

Agents should inspect data.hint before retrying. For -32000 errors, check the supported datetime range (1800–2400 CE).

SDKs

Python

coming soon

kundalimcp-py

Async-first Python client with type-safe models for all ChartArtifact fields. Compatible with LangChain and Claude tool-use patterns.

TypeScript

coming soon

@kundalimcp/sdk

Full TypeScript SDK with generated types from the JSON Schema. Works in Node.js and edge runtimes.

coming soon

kundalimcp-go

Idiomatic Go client with context propagation, retries, and struct-based chart artifact parsing.

Until the SDKs are released, use the raw JSON-RPC API directly or configure KundaliMCP as a native MCP server in your agent framework. The tools/list response provides machine-readable schemas for all tools.