MCP for AI agents

An assistant asked for a birth chart will happily invent one. Point it at the Kaal Jyoti MCP server instead and it computes one.

@kaaljyoti/mcp exposes seventeen tools — one per route family — whose input schemas are the very same ones the HTTP API validates with, so an assistant and a curl are held to one contract. Nothing is calculated in the package and nothing is stored: every tool call is one request to the API, and the API computes and forgets.

Two ways to run it#

stdio — the kaaljyoti-mcp binary. Your MCP client spawns it; it calls the API with your key. This is what you want on a laptop.

Remote Streamable HTTP — https://api.kaaljyoti.com/mcp, served by the gateway itself and authenticated with the same Authorization: Bearer key as every other route. No process to install.

Both expose the same tools with the same schemas, and a tool call is exactly one API request either way — the same credits, the same rate limit, the same quota and the same cache as the equivalent POST /v1/…. What each costs is on

Credits per API.

Claude Desktop#

~/Library/Application Support/Claude/claude_desktop_config.json on macOS, or %APPDATA%\Claude\claude_desktop_config.json on Windows:

{
  "mcpServers": {
    "kaaljyoti": {
      "command": "npx",
      "args": ["-y", "@kaaljyoti/mcp"],
      "env": { "KAALJYOTI_API_KEY": "kj_live_your_key_here" }
    }
  }
}

Restart Claude Desktop; the tools appear under the connector menu.

Claude Code#

claude mcp add kaaljyoti --env KAALJYOTI_API_KEY=kj_live_your_key_here -- npx -y @kaaljyoti/mcp

or, with no local process at all:

claude mcp add --transport http kaaljyoti https://api.kaaljyoti.com/mcp \
  --header "Authorization: Bearer kj_live_your_key_here"

Cursor#

.cursor/mcp.json in the project, or ~/.cursor/mcp.json for every project:

{
  "mcpServers": {
    "kaaljyoti": {
      "command": "npx",
      "args": ["-y", "@kaaljyoti/mcp"],
      "env": { "KAALJYOTI_API_KEY": "kj_live_your_key_here" }
    }
  }
}

Environment#

Variable	Meaning
`KAALJYOTI_API_KEY`	Required. Your API key. The binary exits with an explanation if it is missing.
`KAALJYOTI_API_URL`	Base URL including the version prefix. Default `https://api.kaaljyoti.com/v1`. Point it at `http://localhost:8787/v1` to develop against a local gateway.

The tools#

Tool	What it computes
`kundli`	The full birth chart: grahas, lagna, bhavas, birth panchang, dasha balance
`kundli_dasha`	Dasha timeline, one `system` per call (`vimshottari`, `yogini`, `chara`, `sthira`, `mandook`), `levels` 1–5
`kundli_vargas`	Divisional charts; narrow with `vargas: ["d1","d9"]`
`kundli_yogas`	Every classical yoga detected, with the rule that fired
`kundli_shadbala`	Six-fold planetary strength, in rupas
`kundli_chart`	The chart drawn as an SVG document, returned as text
`panchang`	Tithi, nakshatra, yoga, karana, vara, sunrise/sunset, maasa for a day at a place
`panchang_muhurta`	Rahu kaal, yamaganda, gulika, abhijit, choghadiya, hora; tara/chandra bala when given a birth
`kp_chart`	KP cusps, star and sub lords, ruling planets, significators (Krishnamurti ayanamsa by default)
`jaimini_karakas`	Chara karakas, including the atmakaraka
`varshphal`	The Tajika annual chart for a `year`: muntha, year lord, annual maasa
`transit_now`	Where the grahas are now (or at `at`) over a place
`transit_scan`	Every gochar event in a `from`…`to` window against a birth chart (heavy)
`match_ashtakoot`	Guna milan out of 36 between `bride` and `groom`, with Mangal dosha
`match_compare`	A symmetric comparison of two charts
`reference`	The API's static tables — pick one with `kind`
`timezone`	The IANA zone at a coordinate and its historical UTC offset

The two rules that matter#

Tell the assistant these once and it will stop getting them wrong:

A birth datetime is the local wall clock at the birth place ("1990-05-14T10:30:00"), with timezone (an IANA name) beside it. Not UTC, and not the user's own zone. Give utc_offset instead only if that is all you have; give neither and the zone is derived from the coordinates, with historical rules applied.
from, to and at are the opposite: plain UTC instants.

If the model does not know the zone for a place, the timezone tool answers it and costs no credits.

What a refusal looks like#

A refused call comes back as an MCP tool error whose text starts with the API's own error code — invalid_key, quota_exceeded, rate_limited, validation_error, plan_required — so an assistant can tell "you are out of credits" from "that is not a real date". They are all on the errors page.

A note on keys in agent configurations#

An MCP configuration file is a file on a laptop, often in a repository. Use a key you can revoke on its own — a kj_test_… key for experiments — and keep kj_live_… out of anything you commit. Publishable keys are not the answer here: they are checked against a browser Origin, which an MCP client does not send.