Vedic Astrology MCP Server

What MCP is, in one paragraph

The Model Context Protocol is an open standard for letting a language model call external tools. Instead of pasting astrological data into a prompt, you point the model's client at a server; the client asks the server what tools it has, the server answers with names, descriptions and JSON Schemas, and from then on the model can call any of them mid- conversation and reason over what comes back. This server publishes the Jagannatha Hora Vedic astrology engine that way. It is read-only — every tool computes and returns; none of them write, send, charge or change anything — so an agent can call them freely without a confirmation step in front of each one.

How to connect

In a client that supports remote MCP servers, adding the endpoint URL is the entire setup. There is no package to install and no process to spawn — this is not a stdio server.

Which clients this works with

MCP clients that support remote HTTP servers

Work directly. Add the endpoint URL as a remote or custom MCP server. Because the server requires no authentication, leave any API-key or OAuth field empty — and note that a client which insists on OAuth for remote servers will not connect.

Clients that only speak stdio

Need a bridge. A stdio-to-HTTP proxy (the mcp-remote npm package is the common one) runs locally as the stdio server and forwards to this URL. Configure the proxy, not this endpoint, as the command.

Your own agent code

Nothing special required. It is HTTP and JSON — an MCP SDK's HTTP transport works, and so does a plain POST, as the examples below show. Every response is deterministic, so caching on your side is safe.

Client support for remote MCP servers moves quickly and differs between products and versions, so the honest answer is the one above: this server is a standard HTTP JSON-RPC MCP endpoint with no authentication, and it works with any client that can talk to one. If yours only speaks stdio, put a stdio-to-HTTP bridge in front of it.

Verify it in two commands

curl -sS "https://jagannatha-hora-359167915530.europe-west1.run.app/mcp/health"

{"status":"ok","cache":{"entries":3,"max_entries":15,"ttl_seconds":600,
                        "hits":41,"misses":12,"hit_rate":0.77}}

curl -sS -X POST "https://jagannatha-hora-359167915530.europe-west1.run.app/mcp" \
  -H "content-type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Machine-readable versions of this page

Same facts, formats a program would rather have. Kept in sync with this page by a test that fails the build when they drift.

• horoscopes.today/mcp-tools.json — The tool manifest: every tool name, description and input schema as JSON. Useful for planning a call before you connect — though tools/list on the live server is always the authority.
• horoscopes.today/mcp.md — This whole reference as plain Markdown, for LLM fetchers.
• horoscopes.today/openapi.json — OpenAPI 3.1 for the REST surface, if you would rather call HTTP endpoints directly.
• horoscopes.today/api.md — The REST reference in Markdown.

Protocol

Standard JSON-RPC 2.0. These are the methods the server implements; anything else returns a -32601.

initialize

Handshake. Returns protocolVersion, capabilities ({"tools": {"listChanged": false}}) and serverInfo. The server echoes back whatever protocolVersion the client sent, falling back to 2024-11-05 when the client sends none.

tools/list

The authoritative tool inventory with full JSON Schemas. Call this rather than trusting any written list, including this page.

tools/call

Runs one tool. Takes name and arguments. The result comes back as MCP content: a single text part whose text is the JSON-encoded result object.

ping

Returns an empty object. Liveness.

notifications/*

Accepted and acknowledged with no response body, per JSON-RPC notification semantics.

Transport detail

• The transport is JSON-RPC 2.0 over HTTP. POST your request to the endpoint and the JSON-RPC response comes straight back in the body — no session, no handshake beyond initialize.
• An SSE variant exists for clients that want it: GET /mcp/sse with Accept: text/event-stream opens the stream, which emits an endpoint event followed by a session event carrying the session id. Messages are then POSTed with an X-MCP-Session-ID header and the reply is pushed down the stream as a message event, with the POST itself returning 202. A keepalive comment goes out every 25 seconds.
• This is the HTTP + SSE shape of the 2024-11-05 protocol revision. It is not a stdio server: there is no command to spawn and no package to install.

Errors

-32700

Parse error. The request body was not valid JSON.

-32601

Method not found. A method outside the list above.

-32602

Invalid params. tools/call with no name, an unknown tool name, or birth details that fail to parse — a missing required field names the fields it is missing.

-32603

Internal error. The tool raised. The message carries the reason.

The shared inputs

Most tools identify a chart the same way, with the same six fields. They are listed once here; the tool tables below only name what each tool adds on top.

Three tools take no birth details at all: list_divisional_charts takes no parameters whatsoever, get_planet_ingress works on planets and dates alone, and get_marriage_match takes two nested person objects instead.

Event location override

get_gochara, get_gochara_range and get_muhurta also accept an event location, for the common case where someone was born in one place and is asking about something happening in another. Every field is optional and falls back to the corresponding birth value.

All 32 tools

Grouped by what they are for. Tools that take parameters beyond the birth block have those parameters tabulated in the next section.

What a tool call returns

A tools/call result is MCP content: a single text part whose text is the JSON-encoded result object. Thirty-one of the 32 tools wrap their payload in the same envelope — {"section": "...", "data": ...} — with some adding one field, such as the varga that was applied. generate_horoscope is the exception and returns its overview at the top level.

{
  "content": [
    { "type": "text",
      "text": "{\"section\": \"chara_karakas\", \"data\": { ... }}" }
  ]
}

Tool parameters

The 8 tools below take something beyond the shared birth block. Defaults are applied by the server at call time — no tool schema declares a JSON-Schema default, so a client reading the schema will not see them.

The 55 dasha systems

get_dasha accepts any of these as its system argument. 28 are graha (planetary) systems, where the periods belong to planets:

vimsottari, ashtottari, yogini, shodasottari, dwadasottari, panchottari, satabdika, chaturaaseeti_sama, shashtisama, shattrimsa_sama, dwisatpathi, kaala, buddhi_gathi, naisargika, aayu, tara, karaka, tithi_ashtottari, tithi_yogini, karana_chaturaaseeti_sama, saptharishi_nakshathra, rasi_bhukthi_vimsottari, yoga_vimsottari, ashtaka_varga_planet, ashtaka_varga_sign, ashtaka_varga_pinda, moola_graha, rashmi

The other 27 are rasi (sign) systems, where the periods belong to signs. These naturally run shallower, which is why the default depth is 2 rather than 3:

narayana, chara, kendraadhi_rasi, sudasa, drig, nirayana, shoola, kendraadhi_karaka, lagnamsaka, padhanadhamsa, mandooka, sthira, tara_lagna, brahma, varnada, yogardha, navamsa, paryaaya, trikona, kalachakra, chakra, sandhya_panchaka, chathurvidha_utthara, karaka_kendraadhi, lagna_kendraadhi, niryaana, raashiyanka

A worked example: an agent answering a real question

Take the question "I was born on 27 July 1993 at 1:51pm in Hassan, India. Which dasha am I running, and is Saturn giving me trouble right now?" An agent with this server connected answers it in three calls. Nothing below is hypothetical protocol — it is the literal JSON-RPC each step sends.

Step 1 — establish the chart

The agent calls generate_horoscope first. This is the expensive step, and it populates the server's chart cache, so every later call for the same birth details is a lookup rather than a recomputation.

POST https://jagannatha-hora-359167915530.europe-west1.run.app/mcp
content-type: application/json

{
  "jsonrpc": "2.0", "id": 1, "method": "tools/call",
  "params": {
    "name": "generate_horoscope",
    "arguments": {
      "date": "1993-07-27", "time": "13:51:00", "place": "Hassan",
      "latitude": 13.0, "longitude": 76.1, "timezone": 5.5
    }
  }
}

{
  "birth_details": { "date": "1993-07-27", "time": "13:51:00",
                     "place": "Hassan", "latitude": 13.0,
                     "longitude": 76.1, "timezone": 5.5,
                     "ayanamsa_mode": "LAHIRI" },
  "summary": {
    "ascendant_nakshatra": "Swati", "ascendant_pada": 2,
    "moon_nakshatra": "Uttara Ashadha", "moon_pada": 3,
    "moon_nakshatra_lord": "Sun", "sun_nakshatra": "Pushya"
  },
  "available_sections": ["ashtakavarga", "bhava_bala", "chara_karakas",
                         "divisional_charts", "doshas", "graha_dashas", "..."]
}

Step 2 — the running dasha

Now the timing question. The agent asks for Vimshottari to three levels, and the server marks which maha, antar and pratyantar contain today's date, so the model does not have to do date arithmetic over a period tree.

{
  "jsonrpc": "2.0", "id": 2, "method": "tools/call",
  "params": {
    "name": "get_dasha",
    "arguments": {
      "date": "1993-07-27", "time": "13:51:00",
      "latitude": 13.0, "longitude": 76.1, "timezone": 5.5,
      "system": "vimsottari", "depth": 3
    }
  }
}

{
  "section": "dasha",
  "data": {
    "dasha_type": "graha", "system": "vimsottari",
    "as_of": "2026-08-09", "depth": 3, "levels_available": 3,
    "current_maha":  { "level": 1, "ruler": "Sun",
                       "start": "2023-01-14", "end": "2029-01-13" },
    "current_antar": { "level": 2, "ruler": "Venus",
                       "start": "2026-05-05", "end": "2027-05-05" },
    "current": { "maha": "Sun", "antar": "Venus", "pratyantar": "Rahu",
                 "path": "Sun / Venus / Rahu",
                 "current_period_ends": "2026-09-21" },
    "maha_timeline": [ "..." ]
  }
}

Step 3 — the Saturn question

"Is Saturn giving me trouble" is a Sade Sati question, so the agent calls the tool that answers it directly rather than trying to infer it from planetary positions.

{
  "jsonrpc": "2.0", "id": 3, "method": "tools/call",
  "params": {
    "name": "get_saturn_transit",
    "arguments": {
      "date": "1993-07-27", "time": "13:51:00",
      "latitude": 13.0, "longitude": 76.1, "timezone": 5.5
    }
  }
}

Three calls, and the model now has the running period with its end date and the Saturn transit windows — the two things the question actually turned on. It writes the answer from computed data instead of from whatever it remembered about Vedic astrology.

The shape of this matters more than the specifics. Do not reach for generate_horoscope and then ask the model to find the answer in it — that is the megabyte-into-the-context-window mistake. Establish the chart, then call the one or two tools that own the question. Each returns kilobytes.

How the server behaves

Every tool is read-only

Each tool advertises readOnlyHint: true, destructiveHint: false, idempotentHint: true and openWorldHint: false. Nothing here writes, sends, charges or mutates anything. An agent can call any of them without a confirmation step.

The chart is cached, so slice freely

The expensive step is computing the chart, not slicing it. The server keeps a small in-process LRU of parsed charts — 15 entries, with a 10-minute TTL that refreshes on every hit — keyed by the birth details and the calculation settings. So the intended pattern is one generate_horoscope followed by as many section tools as the question needs, not one call that drags 3.5 MB back to the model. Cache statistics are exposed at GET /mcp/health.

No authentication

The MCP router enforces no authorization header today. There is no API key to obtain and no OAuth flow to complete — which also means an MCP client that requires OAuth for remote servers will not be satisfied by this one. Do not send anything you would not put in a public request.

Rate limits apply here too

The MCP router runs inside the same FastAPI app as the REST API, so the app-wide default of 200 requests per minute per IP governs it. The per-endpoint REST limits do not apply to tool calls; the default does.

tools/list is the contract

The registry discovers tools by importing every module in its tools package at startup, so the live set can differ from any written list. Call tools/list at connect time and use the schemas it returns. This page is a snapshot for humans and crawlers; the server is the authority.

Undocumented parameters exist — do not rely on them

The birth parser accepts calculation settings that appear in no advertised schema: elevation, ayanamsa_mode, ayanamsa_value, calculation_type, bhava_madhya_method, language, pravesha_type, years, months, sixty_hours, tamil_month_method and kali_start_year. They work, but they are not part of the published contract and could change without notice. Send only what tools/list advertises. If you need a non-default ayanamsa today, the REST API exposes it as a supported, documented parameter.