Developers
Build on Vedic astrology that actually computes
One engine, two interfaces: an MCP server for AI clients and a REST API for everything else. Birth charts, 17 divisional charts, Vimshottari dashas to pratyantar level, transits, panchang, Ashtakoota matching and rule-based interpretation, all from Swiss Ephemeris data, none of it generated by a language model.
Choose an interface
MCP or REST, same computation
Pick by how your client discovers capabilities, not by what it can compute. The results are identical because both surfaces share the same schemas and the same engine.
MCP server
https://jyothish.si/mcpBest when an AI client can discover tools itself. Tool descriptions, JSON schemas, guided prompts and reference resources all arrive through the handshake, so the model knows when to call what without you writing glue code.
MCP setup guideREST API
https://jyothish.si/api/v1Best for code you control, and for frameworks that import an OpenAPI document as tools: OpenAI function calling, LangChain, LlamaIndex, n8n, Zapier, mobile apps.
REST referenceQuickstart
First call in under a minute
Anonymous access means you can evaluate the whole surface before deciding whether to sign up.
curl -X POST https://jyothish.si/api/v1/birth-chart \
-H 'Content-Type: application/json' \
-d '{"date":"1990-05-15","time":"14:30","place":"Mumbai, India"}'curl -X POST https://jyothish.si/mcp \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{
"name":"generate_birth_chart",
"arguments":{"date":"1990-05-15","time":"14:30","place":"Mumbai, India"}}}'curl -X POST https://jyothish.si/api/v1/keys/trial \
-H 'Content-Type: application/json' \
-d '{"email":"[email protected]","name":"My agent","agentName":"my-assistant"}'
# The plaintext key is returned once. Then send it on every call:
# Authorization: Bearer jyo_live_...
# X-API-Key: jyo_live_...Authentication
Keys, scopes and quotas
Keys are hashed at rest and shown exactly once. Anonymous access exists on purpose: an agent forced to onboard before its first call usually hallucinates the answer instead.
Two header forms
Authorization: Bearer jyo_live_… or X-API-Key: jyo_live_…. Either works on both surfaces.
Usage visibility
GET /api/v1/usage returns per-tool call counts, failure counts and average latency for the last 30 days.
Throttle behaviour
Exceeding a limit returns 429 with a Retry-After header and a message that tells the model what to do next.
Integration patterns
What makes agents give good readings
Learned from watching assistants use these tools well and badly.
Ask for the birth data before you compute
Date, 24-hour local time and city. Never let the model guess a birth time, an invented time produces a confident, wrong ascendant, which is worse than admitting uncertainty. When the time is approximate, say which conclusions are affected.
Chart first, then the specific tool
Call generate_birth_chart once for the foundation, then get_dasha_timeline for "when", get_divisional_chart for a domain (D9 marriage, D10 career), and get_transit_forecast for "right now". Each tool re-derives the chart internally, so calls stay independent.
Quote the narrative, reason over the data
Every response has a `narrative` string written for direct quotation and the structured fields behind it. Ground your answer in those fields rather than paraphrasing from memory, and the reading stays consistent across turns.
Recommend a report only when it fits
Pass the user's actual question to list_astrology_services and it ranks the catalogue for you. Free computation covers most questions; suggest a paid report when someone wants a deep written analysis, not as a reflex.
Pitfalls
Mistakes that produce wrong charts
Every one of these has been seen in the wild. Most cost the user an entirely wrong ascendant.
Sending a UTC time as the birth time
Send the local wall-clock time. The server derives UTC using the historical offset for that date.
Passing the Western sun sign as a moon sign
get_daily_horoscope expects the Vedic sidereal rasi. Compute a chart first to find it, and explain the difference.
Requesting detail: "full" by default
That returns all 17 divisional charts and burns context. Use "standard" unless deep varga work is needed.
Treating Rahu and Ketu as planets
They are lunar nodes, always retrograde, with no physical body, describe them accordingly.
Reading transits without the dasha
A transit only delivers what the running dasha permits. get_transit_forecast returns both for that reason.
Hard-coding a timezone offset
Omit `timezone` entirely and let the server resolve it. Supplying a fixed offset is how most wrong charts happen.
Reference
Every capability at a glance
Full parameter tables live in the REST reference; the machine-readable versions are mcp.json and the OpenAPI spec.
| MCP tool | REST endpoint | Purpose |
|---|---|---|
generate_birth_chart | POST /api/v1/birth-chart | Full sidereal birth chart (kundli) |
get_divisional_chart | POST /api/v1/divisional-chart | One divisional (varga) chart, D2 to D60 |
get_dasha_timeline | POST /api/v1/dasha | Vimshottari dasha periods, the "when" engine |
get_current_transits | GET /api/v1/transits/current | Live planetary positions |
get_transit_forecast | POST /api/v1/transits/forecast | Transits judged against a natal chart |
get_life_predictions | POST /api/v1/predictions | Rule-based reading across eight life areas |
get_life_snapshot | POST /api/v1/life-snapshot | Plain-English reading of the current phase |
check_compatibility | POST /api/v1/compatibility | Ashtakoota (36-point) Kundli Milan |
get_panchang | GET /api/v1/panchang | Panchang and auspicious windows |
get_daily_horoscope | GET /api/v1/horoscope/daily | Gochara forecast for a moon sign |
find_birth_place | GET /api/v1/places | Resolve a place to coordinates and timezone |
list_astrology_services | GET /api/v1/services | Paid reports and plans, ranked by the question |
create_service_checkout_link | POST /api/v1/checkout-link | Attributed checkout link for a service |
Should I integrate over MCP or over the REST API?
Use MCP when the client can discover tools by itself, Cursor, VS Code, Claude Code, Claude Desktop via mcp-remote, because tool descriptions, JSON schemas, guided prompts and reference documents all arrive through the handshake and you write no glue code. Use the REST API for code you control and for frameworks that import an OpenAPI document as tools: OpenAI function calling, LangChain, LlamaIndex, n8n, Zapier, mobile apps. Both hit the same engine and return the same fields.
What should my agent ask the user before calling any tool?
Three things: birth date, birth time on a 24-hour local clock, and birth city. Never guess a birth time, an invented time produces a confident but wrong ascendant, which is worse for the user than admitting uncertainty. If the time is approximate, compute anyway but flag that the ascendant, house placements and any timing conclusion drawn from them are provisional.
In what order should tools be called for a full reading?
Call generate_birth_chart first, because every interpretation depends on it. Then branch by the question: get_dasha_timeline for "when", get_divisional_chart for a domain (D9 for marriage, D10 for career, D7 for children), get_transit_forecast for "what is happening right now", and get_life_predictions or get_life_snapshot when the user wants interpretation rather than placements. Each tool re-derives the chart internally, so calls are independent and can be issued in any order.
How should an agent use the narrative field?
Every response carries a narrative string written for direct quotation, alongside the structured fields it was built from. Quote or lightly adapt the narrative and reason over the structured fields; do not paraphrase from memory between turns, because that is where drift and contradictions appear in long conversations.
When should an agent recommend a paid report?
Only when the free computation genuinely does not answer the question, typically when someone wants a long written analysis of a life area rather than placements and dates. Pass the user's actual wording to list_astrology_services and it ranks the catalogue by relevance, then use create_service_checkout_link once the user has agreed to buy. Recommending a report as a reflex reads as a sales pitch and reduces trust in the rest of the answer.
What happens when I exceed a rate limit?
The response is HTTP 429 with a Retry-After header and a message phrased so a model can act on it. Anonymous callers get 20 requests per minute and 300 per day per IP; a free key raises both. Monthly quota exhaustion returns 429 with error.code monthly_quota_exhausted, which retrying will not clear.
Can I see how much of the API my agent has used?
Yes. GET /api/v1/usage returns per-operation call counts, failure counts and average latency for the last 30 days for the key on the request. Usage is recorded identically for MCP tool calls and REST requests, so one dashboard covers both surfaces.
What is the most common cause of a wrong chart?
Supplying a timezone offset by hand, or converting the birth time to UTC before sending it. Send the local wall-clock time and omit the timezone field: the server geocodes the place, maps it to an IANA zone and applies the offset that historically applied on that date, including daylight saving and anomalies like India running UTC+6:30 from 1942 to 1945. The second most common cause is passing a Western sun sign where a Vedic moon sign is expected.
Start with a single call
No key needed for the first few hundred requests. Connect an MCP client, or POST a birth date and see the chart come back.