Documentation

Wire KundaliMCP into your agent in five minutes. The tool catalog below is rendered live from the running server, so it cannot drift from reality.

API version

2026.05.24

Released

2026-05-24

Engine

4.3.0

MCP protocol

2025-03-26

Build

—

Rules

1.10.1

Vedaksha

3.1.0

Quickstart

From zero to a real chart in three steps. Every authenticated request is JSON-RPC 2.0 over HTTPS to https://mcp.kundalimcp.com/mcp.

Get an API key

Sign up at kundalimcp.com/pricing, create a key from your dashboard, and pass it as a Bearer token. Keys are sutra_live_ or sutra_test_ followed by 32 hex characters.

Authorization: Bearer sutra_live_<32 hex chars>

Cast your first chart

Five required fields: birth_datetime (ISO 8601 with timezone offset), latitude, longitude, school, locale. Everything else defaults — see Tools below for the full input schema.

curl -X POST https://mcp.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": "compute_chart",
      "arguments": {
        "birth_datetime": "1990-01-15T05:00:00+05:30",
        "latitude": 28.6139,
        "longitude": 77.2090,
        "school": "parashari",
        "locale": "en"
      }
    }
  }'

Read the response

You get a content-addressed ChartArtifact — planet positions, divisional charts, qualified yogas, dasha timeline, panchanga, school attribution, and classical citations — all in the requested locale. The chart_hash identifies it for idempotency / dedupe; it is not a shortcut for follow-up calls — every chart-anchored tool re-supplies the underlying birth data (either as flat birth_datetime/latitude/longitude fields directly, or wrapped in a chart_ref object). The resulting artifact is auto-cached in encrypted form keyed off your API key (operator-blind), TTL up to 30 days. Pass cache: “skip” per-call to disable.

The exact field set evolves with the API version surfaced in every _meta.api_version. Read one response to learn the shape; introspect tools/list to wire types in code.

Three calls to feel the product

The shortest path from “I have a key” to “I just got real data about myself.” Run them in order; each grounds the next.

1 · Discover the school

Pure metadata, no chart needed. describe_school_profilereturns the methodology, rule set, and signature techniques of the school you're about to read charts through. Use it as the first call to ground the agent in its lineage.

{
  "jsonrpc": "2.0", "id": 1,
  "method": "tools/call",
  "params": {
    "name": "describe_school_profile",
    "arguments": { "school_id": "parashari", "locale": "en" }
  }
}

2 · Cast the chart

compute_chart with birth data returns the full ChartArtifact. Before quoting nakshatra-, pada-, or D9-based predictions, scan idl.boundary_margins: any graha with boundary_sensitive: true means the placement straddles a classical boundary and the agent should confirm exact birth time first.

{
  "jsonrpc": "2.0", "id": 2,
  "method": "tools/call",
  "params": {
    "name": "compute_chart",
    "arguments": {
      "birth_datetime": "1990-01-15T05:00:00+05:30",
      "latitude": 28.6139,
      "longitude": 77.2090,
      "school": "parashari",
      "locale": "en"
    }
  }
}

3 · Read today's sky

query_transits overlays planetary positions on the natal chart for a single date — gochara, vedic aspects, Sade Sati phase, plus the active dasha across all 5 levels with fraction elapsed (drives progress-bar UIs without an extra forecast_dasha call). Birth data is re-supplied each call — pass flat birth_datetime + latitude + longitude (recommended), or wrap them in a chart_ref object for legacy compatibility.

{
  "jsonrpc": "2.0", "id": 3,
  "method": "tools/call",
  "params": {
    "name": "query_transits",
    "arguments": {
      "chart_ref": {
        "birth_datetime": "1990-01-15T05:00:00+05:30",
        "latitude": 28.6139,
        "longitude": 77.2090
      },
      "transit_date": "2026-04-26",
      "school": "parashari",
      "locale": "en"
    }
  }
}

Tools (18)

Live from tools/list · revalidates hourly

Rendered directly from https://mcp.kundalimcp.com/mcp. If a field appears here, the server accepts it; if it doesn't, we don't document it because we can't guarantee it.

Discover from your agent in two unauthenticated calls

# What can this server do?
{"jsonrpc":"2.0","id":1,"method":"tools/list"}

# What's the API version + protocol?
{"jsonrpc":"2.0","id":2,"method":"tools/call",
 "params":{"name":"get_version","arguments":{}}}

Both bypass auth; tools/call for any other tool requires a sutra_ key.

Datetime contract (applies to every tool)

All datetime inputs are local clock time at the relevant location — no Z, no ±HH:MM. The server resolves the historical UTC offset from latitude + longitude via IANA tzdata (chrono-tz historical record covers India 1955, US 1966, Russia 2011, and all DST regimes).

Every emitted datetime field carries both a <field>_utc value (RFC 3339 with Z) and a <field>_local value (naive local clock face at the natal IANA zone, DST-aware at that moment). Each chart-anchored response also carries a top-level birth_context block with tz_iana, tz_offset_minutes_at_birth, birth_datetime_local, birth_datetime_utc, and dst_note (set only on DST fall-back ambiguity). Clients do not need a timezone library.

compute_chart

Compute a Vedic (Jyotish) birth chart. Ask this tool when the user wants to know: · 'What\'s my Vedic birth chart?' · 'What\'s my Moon sign / ascendant / nakshatra?' · 'What\'s my current Vimshottari dasha?' Returns: · headline: one-sentence summary the user can quote · facts.ascendant / facts.moon / facts.sun — top-asked facts inline · facts.planets — dict keyed by graha name (sun, moon, mars, ...) · facts.houses — dict keyed by 1-12 · facts.active_dasha — current Vimshottari period across 5 levels · facts.sade_sati — phase + prev/next windows · facts.active_yogas — top 5 yogas with strength + classical citation · facts.chart_ref — thread to subsequent tools to skip re-supplying birth data Use `include=detail` for the full IDL artifact; `include=schools` for per-school CIL (Jaimini, KP); `include=metrics` for Shadbala + Ashtakavarga. INVARIANT: if any graha in `idl.boundary_margins` has `boundary_sensitive: true`, ask the user to confirm exact birth time before quoting nakshatra/pada/D9-based predictions — the placement straddles a classical boundary and is sensitive to small shifts. Birth data is processed in-process; the resulting chart artifact is auto-cached in encrypted form keyed off your API key (operator-blind), TTL up to 30 days. Pass `cache: "skip"` to disable for a specific call. Tier: Free · Typical default response: ~6 KB.

Input

ayanamsa

string

no description

birth_datetimerequired

string

Local clock time at the birth location, ISO 8601 naive form (e.g. '1990-06-15T06:30:00'). NO 'Z' suffix, NO ±HH:MM offset. The server resolves the historical UTC offset from latitude + longitude using IANA tzdata. Pre-1955 Indian charts, pre-2006 Indianapolis charts, post-2011 Russian charts, etc. all map correctly because the resolver uses chrono-tz's full historical record. DST fall-back ambiguity is resolved to the pre-transition offset and surfaced via `birth_context.dst_note`. DST spring-forward gaps (clock face that never existed locally) return -32602 InvalidParams.

cache

string

Optional. Pass "skip" to disable tier-2 cache read+write for this call.

enum: skip

dasha_max_level

integer

Dasha sub-period depth (0=Maha, 1=Maha+Antar default, 2=+Pratyantar, 3=+Sookshma, 4=+Prana). Higher depths grow response size super-linearly.

range: 0 – 4

house_system

string

no description

include

string

Comma-separated opt-in expansions. Tokens: detail (full IDL artifact, 7-layer yoga practitioner narrative + per-domain user narrative, full Ashtakavarga grid, per-varga yoga re-qualification, dasha period narratives), schools (per-school CIL analysis), metrics (Shadbala + Ashtakavarga computed metrics), trace (yoga 6-stage qualification log, Vivek reasoning trace, Anvaya graph propagation), all (every current and future expansion token). Omit for the slim agent-first response (~4-10 KB).

latituderequired

number

Birth latitude in decimal degrees, WGS84.

range: -90 – 90

localerequired

string

Response language. Required.

enum: en · hi · sa · ta · te · kn · bn

longituderequired

number

Birth longitude in decimal degrees, WGS84. Used for tz resolution.

range: -180 – 180

schoolrequired

string

Jyotish school for interpretation. Required.

enum: parashari · jaimini · kp · tajika · nadi

compute_life_journey

Compute a lifetime Vedic forecast across Vimshottari dasha periods. Ask this tool when the user wants to know: · 'What does my life journey look like?' · 'When does my next mahadasha begin?' · 'When is my next Sade Sati?' · 'What are the major life events forecast for the next 10 years?' Returns: · headline: single-sentence summary the user can quote · facts.current — active mahadasha + antardasha + themes · facts.next_mahadashas — next 2-3 maha periods with themes · facts.sade_sati — phase + previous + next windows · facts.returns — Saturn / Jupiter / Rahu return cycles · facts.key_events — top 10 forecast events with age + year + description · facts.chart_ref — thread to subsequent tools Use `include=detail` (or `include=life_events`) for `detail.life_events[]` — the full lifetime forecast-event list, each with age, area, strength, gate, status, the active maha/antar dasha lords, and a localized `why` reasoning-chain (resolved to the request locale); `include=trajectories` for the per-area life-arc curves; `include=schools` for per-school CIL; `include=metrics` for Shadbala + Ashtakavarga. Tier: Standard · Typical default response: ~10 KB.

Input

ayanamsa

string

no description

birth_datetimerequired

string

house_system

string

no description

latituderequired

number

Birth latitude in decimal degrees, WGS84.

range: -90 – 90

localerequired

string

Response language.

enum: en · hi · sa · ta · te · kn · bn

longituderequired

number

Birth longitude in decimal degrees, WGS84. Used for tz resolution.

range: -180 – 180

sample_step

number

Trajectory sampling step in years (default 0.8). Higher = coarser + smaller payload.

enum: 0.5 · 0.8 · 1 · 2

schoolrequired

string

Jyotish school for interpretation.

enum: parashari · jaimini · kp · tajika · nadi

compute_compatibility

Compute Ashtakoota compatibility between two Vedic birth charts. Ask this tool when the user wants to know: · 'Check compatibility between two people for marriage.' · 'What\'s our Ashtakoota match?' · 'Are there any dosha issues between these charts?' Returns: · headline: total score + verdict + Mangal dosha summary · facts.total / facts.out_of / facts.verdict — Ashtakoota total (0-36) with verdict label · facts.kootas — dict keyed by koota name (varna, vashya, tara, yoni, graha_maitri, gana, bhakoot, nadi) · facts.doshas — Mangal / Nadi / Bhakoot status · facts.flags — notable warnings (bhakoot_0, mutual_mangal, etc.) · facts.chart_ref_groom / facts.chart_ref_bride — thread to subsequent calls Inputs are `groom: {birth_datetime, latitude, longitude}` and `bride: {birth_datetime, latitude, longitude}`. Use `include=detail` for the full per-koota classical analysis (BPHS / Phaladeepika citations) + Venus/Jupiter karaka comparison + antardasha windows. Tier: Standard · Typical default response: ~5 KB.

Input

briderequired

object

no description

eval_date

string

Optional. Evaluation moment (UTC) for the temporal-compatibility block (Sade Sati overlap, Ashtama Shani, antardasha sync windows, upcoming dasha transitions, synthesis narrative). Date-only `YYYY-MM-DD` is treated as noon UT; full `YYYY-MM-DDTHH:MM[:SS]` is treated as UT. Defaults to the server's current wall-clock if omitted. Unlike `birth_datetime`, this field is NOT location-anchored — it is a global civil moment.

groomrequired

object

no description

include_provenance

boolean

Optional. When true, every koota score, dosha assessment, dosha cancellation, and composite-score weight is annotated with a `provenance` object carrying `source_class` (primary | secondary | engineering_convention), `citation` (specific MC / BPHS / Saravali / Phaladeepika anchor for primary/secondary), and `rationale` (required for engineering conventions). Default false — keeps the response payload unchanged for the common consumer path. Use this flag when building source-traceable consumer experiences or auditing the engine's classical fidelity.

localerequired

string

Response language. Required.

enum: en · hi · sa · ta · te · kn · bn

schoolrequired

string

Jyotish school for interpretation. Required.

enum: parashari · jaimini · kp · tajika · nadi

query_transits

Compute Vedic transits over your natal chart — either a single-date snapshot or a range of ingress events. Mode `snapshot` (default) returns positions + active dasha + Sade Sati at one date. Mode `ingress_events` returns chronological sign-change events over [start_date, end_date]. Ask this tool when the user wants to know: · 'Where are the planets transiting today?' · 'When does Saturn next change signs?' · 'Am I in Sade Sati right now?' · 'What major ingresses are coming in the next 5 years?' Returns (snapshot mode): · headline: planet-of-interest summary + sade sati state + active dasha · facts.transit_date — local + UTC · facts.sade_sati — phase + previous/next windows · facts.planets_now — dict keyed by graha · facts.active_dasha — Vimshottari at this JD · facts.notable_aspects — top drishti aspects to natal planets Returns (ingress_events mode): · headline: count of major events in range · facts.range, facts.summary, facts.events — chronological list with planet, from/to sign, your house Use `include=detail` for the full transit artifact (sub-divisional positions, all aspects, panchanga in snapshot mode; per-event classical themes in ingress mode). Tier: Standard · Typical default response: 4 KB (snapshot) / 8 KB (ingress, 5y range).

Input

birth_datetimerequired

string

cache

string

Optional. Pass "skip" to disable tier-2 cache read+write for this call.

enum: skip

end_date

string

Required when mode is ingress_events.

include

string

latituderequired

number

no description

range: -90 – 90

localerequired

string

no description

enum: en · hi · sa · ta · te · kn · bn

longituderequired

number

no description

range: -180 – 180

mode

string

snapshot: single date → positions + dasha + sade-sati. ingress_events: range → timeline.

enum: snapshot · ingress_events

schoolrequired

string

no description

enum: parashari · jaimini · kp · tajika · nadi

start_date

string

Required when mode is ingress_events.

transit_date

string

Required when mode is snapshot or omitted.

query_muhurtha

Find auspicious time windows (muhurtha) for an event. Ask this tool when the user wants to know: · 'When\'s a good time to schedule a wedding in May?' · 'What\'s an auspicious muhurtha for starting a business?' · 'When should I travel next month?' Returns: · headline: count + dates of top windows · facts.event_type, facts.location, facts.range · facts.top_windows — 5-10 ranked windows with quality + factors + blockers Use `include=detail` for the full per-window factor breakdown + classical citations. Tier: Standard · Typical default response: ~3 KB.

Input

datetimerequired

string

event_typerequired

string

no description

latituderequired

number

Event latitude in decimal degrees, WGS84.

range: -90 – 90

localerequired

string

Response language. Required.

enum: en · hi · sa · ta · te · kn · bn

longituderequired

number

Event longitude in decimal degrees, WGS84. Used for tz resolution.

range: -180 – 180

schoolrequired

string

Jyotish school for interpretation. Required.

enum: parashari · jaimini · kp · tajika · nadi

assess_natal

Compute an in-depth Vedic natal assessment across life areas (career, marriage, health, wealth, progeny, education, parents, siblings, longevity, spirituality). Ask this tool when the user wants to know: · 'What does my chart say about my career / marriage / health?' · 'What are the strongest and weakest areas of my chart?' · 'Is my chart indicated to bring children?' Returns: · headline: top 3 life-area verdicts the user can quote · facts.life_areas — dict keyed by area with verdict + key_factors + top_yogas + doshas · facts.chart_ref — thread to subsequent tools Use `include=detail` for per-area rule citations (BPHS, Phaladeepika, Saravali) + alternative-school readings. Tier: Standard · Typical default response: ~7 KB.

Input

ayanamsa

string

no description

birth_datetimerequired

string

cache

string

Optional. Pass "skip" to disable tier-2 cache read+write for this call.

enum: skip

dasha_max_level

integer

Dasha sub-period depth (0=Maha, 1=Maha+Antar default, 2=+Pratyantar, 3=+Sookshma, 4=+Prana). Higher depths grow response size super-linearly.

range: 0 – 4

house_system

string

no description

latituderequired

number

Birth latitude in decimal degrees, WGS84.

range: -90 – 90

localerequired

string

Response language. Required.

enum: en · hi · sa · ta · te · kn · bn

longituderequired

number

Birth longitude in decimal degrees, WGS84. Used for tz resolution.

range: -180 – 180

schoolrequired

string

Jyotish school for interpretation. Required.

enum: parashari · jaimini · kp · tajika · nadi

compute_panchanga

Compute the Vedic panchanga (five-limbed almanac) for any date, time, and location. Ask this tool when the user wants to know: · 'What is today\'s tithi / nakshatra / yoga / karana?' · 'Is this an auspicious time? Is Rahu Kalam active?' · 'What are today\'s inauspicious periods?' · 'When does the current tithi end?' · 'What rashi (sign) is the Moon in?' · 'When is the next solar or lunar eclipse?' Returns for each of the five limbs (tithi, nakshatra, yoga, karana, vara): · Entity (id + localized name) · Quality, lord, pada as applicable · Remaining degrees until the limb changes · End time in local and UTC Also returns: · Approximate sunrise and sunset (HH:MM local) · Rahu Kalam, Gulika Kalam, Yamaganda windows with active flag · Calendar: masa (with adhika/kshaya flags), samvatsara, Vikrama and Shaka year, ayana, ritu, and the next sankranti · Day yogas: anandadi yoga + the active dainika yogas (Sarvartha Siddhi, Amrita Siddhi, Ravi, Dagdha, etc.), each tier-tagged standard (Drik-Panchang set) or classical (extended) · Moon's rashi (Chandra rashi — the Vedic moon sign), localized · Eclipses: next solar + next lunar eclipse (grahana) — type, certainty, days away, and UTC date For birth chart panchanga, use `compute_chart` which includes `facts.panchanga` anchored to the birth moment. Tier: Free · Typical response: ~4 KB.

Input

datetimerequired

string

Local clock time at the given location, ISO 8601 naive (e.g. '2026-05-16T10:30:00'). NO 'Z' suffix.

include

string

Comma-separated opt-ins (detail, trace, schools, metrics, all). `detail` adds facts.windows (choghadiya 16, hora 24, abhijit/brahma/dur muhurtas, varjya + amrita kala); the other tokens are accepted but do not affect this tool. Omit for the default ~4 KB response.

latituderequired

number

no description

range: -90 – 90

localerequired

string

Response language.

enum: en · hi · sa · ta · te · kn · bn

longituderequired

number

no description

range: -180 – 180

generate_narrative

Generate prose narrative for a specific life domain in a Vedic chart (career, marriage, health, wealth, progeny, longevity, self, family, spirituality). Ask this tool when the user wants: · A free-form narrative about a specific life area (deeper than assess_natal's 1-paragraph verdict). · Prose synthesis across placements, yogas, and active dasha — already localized; do NOT translate or paraphrase from memory. · Life-area cards or dashboard summaries (single-shot, no agent loop overhead). Returns: · content[0].text — the narrative in markdown · structuredContent.facts — { domain, claims_resolved, citations } Use `chat` instead for multi-turn conversations or queries that need safety classification + redirect-to-consultation handling. Tier: Standard · Typical response: ~3-5 KB.

Input

chart_refrequired

object

no description

domainrequired

string

no description

localerequired

string

Response language. Required.

enum: en · hi · sa · ta · te · kn · bn

schoolrequired

string

Jyotish school for interpretation. Required.

enum: parashari · jaimini · kp · tajika · nadi

recommend_remedies

Recommend Vedic remedies (gemstones, mantras, deities, charities, fasts) calibrated to a chart and a specific life-area concern. Ask this tool when the user wants: · Remedial gemstone or mantra recommendations. · Classical countermeasures for an afflicted house or graha. · Karaka-strengthening practices. Returns: · facts.remedies — ranked list of { type, target, prescription, classical_citation } · facts.cautions — astrological caveats (e.g. 'consult an astrologer before wearing a gemstone') Frame results as classical guidance, not medical/financial/legal advice. Use `chat` for back-and-forth refinement. Tier: Standard · Typical response: ~2-4 KB.

Input

chart_refrequired

object

no description

localerequired

string

Response language. Required.

enum: en · hi · sa · ta · te · kn · bn

schoolrequired

string

Jyotish school for interpretation. Required.

enum: parashari · jaimini · kp · tajika · nadi

explain

Explain WHY a specific Jyotish claim is true for a chart — full reasoning chain with rule provenance and classical citations. Ask this tool when the user wants: · Justification for a specific yoga / dosha / verdict (e.g. 'Why does my chart have Gajakesari Yoga?'). · The sequence of rules fired, entities touched, and school weights applied. · The classical citation (chapter / verse) anchoring a conclusion. · Counterfactual analysis ('What would change this verdict?'). Returns: · content[0].text — explanatory prose · facts.claim, facts.evidence, facts.citations Agents should quote source_text verbatim when relaying the answer. Tier: Standard · Typical response: ~2-3 KB.

Input

chart_refrequired

object

no description

claim_idrequired

string

no description

localerequired

string

Response language. Required.

enum: en · hi · sa · ta · te · kn · bn

schoolrequired

string

Jyotish school for interpretation. Required.

enum: parashari · jaimini · kp · tajika · nadi

forecast_dasha

Return the active Vimshottari dasha at a specific eval_date with classical interpretation of the lord's significations. Ask this tool when the user wants to know: · 'What dasha was I in at a past date?' · 'What dasha will I be in at a future date?' · The themes / events typical of the active dasha-lord. · Per-level fraction elapsed + the lord's natal placement context. Returns: · facts.eval_date, facts.active_dasha (5 levels), facts.themes · A school-attributed effect summary (favourable / mixed / challenging) Use compute_life_journey instead for a full multi-decade forecast. Tier: Standard · Typical response: ~2 KB.

Input

chart_refrequired

object

no description

eval_daterequired

string

Either a date-only `YYYY-MM-DD` (treated as noon UT, ignoring latitude/longitude) OR a full naive local clock time `YYYY-MM-DDTHH:MM[:SS]` evaluated at the natal chart's birth location. NO 'Z' suffix, NO ±HH:MM offset.

include

string

localerequired

string

Response language. Required.

enum: en · hi · sa · ta · te · kn · bn

schoolrequired

string

Jyotish school for interpretation. Required.

enum: parashari · jaimini · kp · tajika · nadi

forecast_events

Return specific event predictions within a dasha window — career shifts, marriage timing, health events, etc. Ask this tool when the user wants: · 'What events are likely during my Saturn dasha?' · 'When in the next 5 years is marriage indicated?' · Date-pinned event forecasts within a specific window. Evaluates the YAML life-event rule corpus with natal-trigger + dasha-trigger + transit-trigger evidence layers, severity scores, and citation provenance. Returns: · facts.window, facts.events — ranked by probability + classical strength Use compute_life_journey.life_events[] for the full lifetime event list. Tier: Standard · Typical response: ~3 KB.

Input

chart_refrequired

object

no description

end_date

string

Optional end date (ISO 8601) for timeline scan. When provided with eval_date, returns the union of triggered events across the window (weekly scan steps).

eval_daterequired

string

include

string

localerequired

string

Response language. Required.

enum: en · hi · sa · ta · te · kn · bn

schoolrequired

string

Jyotish school for interpretation. Required.

enum: parashari · jaimini · kp · tajika · nadi

compare_schools

Compare a chart's reading across multiple Jyotish schools (Parashari, Jaimini, KP, Tajika, Nadi). Ask this tool when the user wants to know: · 'How do different schools interpret my chart?' · 'Where do Parashari and Jaimini agree / disagree?' · 'What's the KP sub-lord reading for my current dasha?' Returns: · headline: consensus count + top divergence · facts.schools_requested — list of school keys · facts.consensus — fields where all requested schools agree (ascendant, moon, dasha lord, sade sati) · facts.divergences — up to 8 topics where schools differ, each with per-school summary · facts.chart_ref **Heavy tool.** Default response keeps only the consensus + top divergences. Use `include=schools` to fetch the full per-school CIL analysis (typical ~250 KB per school at N=3). Tier: HighTraffic · Typical default response: ~12 KB (without include=schools).

Input

ayanamsa

string

no description

birth_datetimerequired

string

cache

string

Optional. Pass "skip" to disable tier-2 cache read+write for this call.

enum: skip

dasha_max_level

integer

no description

range: 0 – 4

house_system

string

no description

latituderequired

number

Birth latitude in decimal degrees, WGS84.

range: -90 – 90

localerequired

string

Response language. Required.

enum: en · hi · sa · ta · te · kn · bn

longituderequired

number

Birth longitude in decimal degrees, WGS84. Used for tz resolution.

range: -180 – 180

schoolsrequired

array

Two or more Jyotish schools to compare in parallel.

size: 2–5 items

item enum: parashari · jaimini · kp · tajika · nadi

get_varga_chart

Retrieve the divisional chart (varga) for a birth chart — planet placements in D2, D3, D4, D7, D9, D10, D12, D16, D20, D24, D27, D30, D40, D45, or D60. Ask this tool when the user wants to: · Examine the Navamsha (D9) for spouse, dharma, and chart corroboration. · Check the Dashamsha (D10) for career and professional life. · Validate dignity-in-varga for any planet (BPHS Ch. 6 Vimshopak principle). Returns: · facts.varga_type — the requested varga slug (e.g. 'd9') · facts.varga_lagna — ascendant sign in this varga · facts.planets — per-graha: sign, house, dignity, retrograde · facts.houses — per-house: sign, lord, lord_in, occupants · facts.reliability — 'reliable' | 'conditional' | 'requires_rectification' | 'unreliable' **Accepted varga_type values:** d1/rashi · d2/hora · d3/drekkana · d4 · d7/saptamsha · d9/navamsha · d10/dashamsha · d12 · d16 · d20 · d24 · d27 · d30 · d40 · d45 · d60/shashtiamsha. For full chart interpretation use `compute_chart`. For multi-varga yoga corroboration use `compare_schools`. Tier: Standard · Typical response: ~4 KB.

Input

birth_datetimerequired

string

include

string

latituderequired

number

no description

range: -90 – 90

localerequired

string

no description

enum: en · hi · sa · ta · te · kn · bn

longituderequired

number

no description

range: -180 – 180

schoolrequired

string

no description

enum: parashari · jaimini · kp · tajika · nadi

varga_typerequired

string

Divisional chart to retrieve. Accepted: d1/rashi, d2/hora, d3, d4, d7/saptamsha, d9/navamsha, d10/dashamsha, d12, d16, d20, d24, d27, d30, d40, d45, d60/shashtiamsha.

describe_school_profile

Describe a Jyotish school's calibration profile — its rule weights, dasha system, ayanamsha, divisional-chart usage, and signature techniques. Pure metadata — no chart needed. Ask this tool when the user wants: · Background on Parashari vs Jaimini vs KP vs Tajika vs Nadi. · School-specific calibration settings before running a chart. · Help choosing the right school for a given question. Returns: · facts.school_id, facts.dasha_system, facts.ayanamsha, facts.rule_weight_summary Recommended as the FIRST call in an agent session to ground the agent in the school it is about to read charts through (Parashari is the default). Tier: Free · Typical response: ~1 KB.

Input

locale

string

no description

enum: en · hi

school_idrequired

string

no description

enum: parashari · jaimini · nadi · kp · tajika

submit_feedback

Submit feedback on a chart / claim / explanation. Stored anonymously for engine improvement — no birth data is retained; the claim_id is the only correlator. Ask this tool when the user wants to: · Rate a chart's accuracy (1–5). · Flag a claim that seems off. · Suggest improvements to a verdict or narrative. Feeds the Calibratable Interpretive Layer (CIL) for school-weight tuning. Returns: · facts.acknowledged: true, facts.feedback_id Tier: Free · Typical response: <1 KB.

Input

claim_id

string

no description

feedback_typerequired

string

no description

enum: accuracy · completeness · relevance · clarity

notes

string

no description

ratingrequired

integer

no description

range: 1 – 5

get_version

Return engine + API version + protocol info. Unauthenticated — no API key required. Ask this tool to: · Verify the engine version your client is talking to. · Confirm wire compatibility (api_version CalVer). · Display a 'powered by KundaliMCP' line. Returns: · facts.engine_version, facts.api_version, facts.release_codename, facts.build Tier: Free (no auth required) · Typical response: <1 KB.

No input parameters.

get_dasha_timeline

Return the complete Vimshottari dasha timeline from birth — all 9 mahadashas with nested antardashas (MD + AD by default). Ask this tool when the user wants to: · See every dasha period across their entire life. · Find Julian-Day (JD) + local + UTC boundaries for each period. · Build a multi-decade dasha calendar. Returns: · facts.periods — 9 mahadashas each with up to 9 antardasha sub_periods · facts.total_years — approximate lifetime span from birth · facts.dasha_system — always Vimshottari for this tool For the active dasha at a specific date with classical interpretation use `forecast_dasha`. For a full lifetime forecast with life-event scores use `compute_life_journey`. Tier: Standard · Typical response: ~36 KB.

Input

birth_datetimerequired

string

latituderequired

number

no description

range: -90 – 90

localerequired

string

no description

enum: en · hi · sa · ta · te · kn · bn

longituderequired

number

no description

range: -180 – 180

schoolrequired

string

no description

enum: parashari · jaimini · kp · tajika · nadi

Reference agent system prompt

Eight behavioral invariants for an agent calling KundaliMCP. Drop into your system prompt, refine to taste. Each invariant encodes a real product constraint (boundary sensitivity, school attribution, locale fidelity, privacy, scope) so the agent doesn't reinvent them badly.

Agent system prompt

You are using KundaliMCP, a Vedic Jyotish computation server. The server is the source of truth — never paraphrase astrology from memory; always read it from a tool response.

1. CHART FIRST. When the user supplies birth data (datetime + latitude + longitude), call compute_chart before answering any chart-related question. Every chart-anchored tool accepts the flat fields (birth_datetime + latitude + longitude) directly; a chart_ref object wrapping the same three fields also works for legacy callers. chart_hash is for bookkeeping (idempotency, dedupe), not for skipping re-supply.

2. RESPECT BOUNDARY SENSITIVITY. compute_chart returns an idl.boundary_margins block flagging placements near nakshatra / pada / sign cusps. If anything has boundary_sensitive: true, ask the user to confirm exact birth time before quoting any nakshatra-, pada-, or D9-based prediction.

3. PICK THE RIGHT TIME-WINDOW TOOL.
   - Active dasha at a date: forecast_dasha with eval_date.
   - The sky on a single date: query_transits with transit_date (mode "snapshot", default).
   - Significant transits across a range: query_transits with mode "ingress_events", start_date, end_date.
   - Triggered life events around a date: forecast_events with eval_date.
   - Lifetime view (dasha tree, life-area trajectories, life events, sade sati, returns, yoga zones, natal_assessment): compute_life_journey ($0.50 wallet-metered).

4. PRESERVE LOCALIZATION. Response strings are returned in the requested locale (en, hi, sa, ta, te, kn, bn). Quote them verbatim — never re-translate. If a response signals a locale fallback (English shown because that locale is not yet authored), surface the English and note the locale is pending.

5. CITE SCHOOL AND SOURCE. Every rule-based interpretation (yoga, gochara, dasha effect, life-event verdict) carries school attribution and a classical citation in its response object. Quote the citation when stating a verdict, and name the school when reasonable practitioners might disagree (Parashari vs Jaimini vs KP).

6. PRIVACY. Birth data is processed in-process and may be cached in encrypted form, with cache lifetime up to 30 days. Cached entries are encrypted with material derived from your API key, which KundaliMCP cannot decrypt without your live key. Pass cache: "skip" per-call to disable.

7. SCOPE. KundaliMCP is Vedic / Indian-tradition only. Synastry, composite charts, Western aspects, Babylonian ayanamshas, Regiomontanus / Porphyry / Morinus / Alcabitius houses, and Western dignity are out of scope. If the user asks, redirect to the Vedic equivalent (e.g. compute_compatibility for Kundali Milan) or decline.

Authentication

Two methods — both via Authorization: Bearer

OAuth 2.1 — for interactive AI clients (Claude, ChatGPT, Kimi). One-click connect; no secret to manage. Setup guides →
API key — long-lived sutra_… bearer for CI and server-to-server callers. Generate from dashboard →

Discovery methods (initialize, tools/list, ping, get_version) are unauthenticated — agents can introspect before paying.

API 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 on 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

State is returned in every response:

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

Exceeding a limit returns 429 Too Many Requests with a Retry-After header (seconds).

Error handling

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

Code	Meaning
-32602	Invalid params — missing or malformed input field
-32601	Method not found — unknown tool name
-32603	Internal — tier-capability denial, quota exhaustion, infrastructure
-32000	Computation error — ephemeris out of range or internal failure

Agents should inspect data.hint before retrying. Supported birth-datetime range: 1800–2400 CE.

Documentation

Quickstart

3-call script

Tools

Agent prompt

Authentication

Quickstart

Get an API key

Cast your first chart

Read the response

Three calls to feel the product

Tools (18)

compute_chart

compute_life_journey

compute_compatibility

query_transits

query_muhurtha

assess_natal

compute_panchanga

generate_narrative

recommend_remedies

explain

forecast_dasha

forecast_events

compare_schools

get_varga_chart

describe_school_profile

submit_feedback

get_version

get_dasha_timeline

Reference agent system prompt

Authentication

Rate limits

Error handling