# Jagannatha Hora Agent MCP Usage Guide

Last updated: 2026-07-07

Purpose: download this file and give it to Claude (or any AI assistant that speaks MCP) so it can call Jagannatha Hora's Vedic astrology calculation tools for you.

## Overview

Jagannatha Hora exposes one Model Context Protocol (MCP) server. It is open — no signup, no API key, and no auth header.

- Server name: `Jagannatha Hora MCP Server`
- Version: `1.0.0`
- Endpoint: `https://jagannatha-hora-359167915530.europe-west1.run.app/mcp`

The endpoint above is the **production** MCP server. If the "API & MCP" page in the app shows a different URL for you (for example, when using a staging or development environment), use that URL instead — the page is the source of truth for whichever environment you are configuring.

The MCP server lets AI agents call Vedic astrology calculation tools directly instead of asking for the full `/horoscope` REST response. Most tools are read-only slices over the horoscope engine output, with tool-specific arguments for dashas, divisional charts, marriage matching, gochara, and muhurta.

This file is written so an AI agent can read it as operating instructions. Give the agent this file along with the endpoint above, and instruct it to call `tools/list` before making tool calls so it can confirm the live schema.

## Tool Reference Covered In This Guide

This guide documents the current public tool set:

1. `generate_horoscope`
2. `get_amsa_rulers`
3. `get_arudha_padas`
4. `get_ashtakavarga`
5. `get_bhava_bala`
6. `get_chandra_arudhas`
7. `get_chara_karakas`
8. `get_dasha`
9. `get_divisional_chart`
10. `get_doshas`
11. `get_gochara`
12. `get_gochara_range`
13. `get_graha_arudhas`
14. `get_house_varnadas`
15. `get_longevity`
16. `get_marriage_match`
17. `get_muhurta`
18. `get_nakshatra_pada`
19. `get_other_bala`
20. `get_planet_ingress`
21. `get_planetary_states`
22. `get_sahams`
23. `get_saturn_transit`
24. `get_shad_bala`
25. `get_special_lagnas`
26. `get_sphutas`
27. `get_surya_arudhas`
28. `get_upagrahas`
29. `get_vaiseshikamsa_bala`
30. `get_vimsopaka_bala`
31. `get_yogas`
32. `list_divisional_charts`

## Responsible Use

The endpoint is open, but the data flowing through it — someone's date, time, and place of birth — is personal. Please treat it that way.

Recommended agent behavior:

- Do not paste raw birth details into public logs, screenshots, or public repositories.
- Call only the tools needed to answer the user's question.
- Treat returned data as calculation data, not as final counseling.
- Ask for missing birth details instead of inventing them.
- Cache results on your side where you can — the same birth data produces the same chart, so re-fetching wastes cycles for everyone.


## Agent Instructions

If you are an AI agent using this file:

1. Use the endpoint listed in the Overview above as the MCP server URL.
2. Call `initialize`.
3. Call `tools/list` and compare the live tool names with this guide.
4. Choose the smallest tool that answers the user question.
5. Call `tools/call` with validated arguments.
6. Parse `result.content[0].text` as JSON.
7. Explain the result in plain language, clearly separating calculation facts from interpretation.
8. Never invent missing birth date, birth time, latitude, longitude, or timezone.

## Supported MCP Methods

The server supports JSON-RPC 2.0 over HTTP:

- `initialize`
- `tools/list`
- `tools/call`
- `ping`
- `notifications/*`

It also supports an SSE-style flow for clients that open `GET /mcp/sse` and then post messages with `X-MCP-Session-ID`.

## Common Birth Input And Calculation Settings

Most tools require the same birth details:

```json
{
  "date": "1990-01-01",
  "time": "12:00:00",
  "latitude": 13.0827,
  "longitude": 80.2707,
  "timezone": 5.5,
  "place": "Chennai"
}
```

Required fields:

- `date`: birth date in `YYYY-MM-DD`
- `time`: birth time in `HH:MM:SS`
- `latitude`: decimal degrees
- `longitude`: decimal degrees
- `timezone`: UTC offset in hours

Optional common field:

- `place`: display-only place name

Public contract: clients should send only the fields advertised by `tools/list`. If an input is not listed in the live schema, do not send it.

## Basic JSON-RPC Examples

For convenience, the shell examples below use `MCP_URL` as a variable. Set it once to the URL from the Overview above (or the URL shown on the API & MCP page in the app if you are configuring a non-production environment):

```bash
MCP_URL="https://jagannatha-hora-359167915530.europe-west1.run.app/mcp"
```

### Initialize

```bash
curl -X POST "$MCP_URL" \
  -H "content-type: application/json" \
  --data '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05"
    }
  }'
```

### List Tools

```bash
curl -X POST "$MCP_URL" \
  -H "content-type: application/json" \
  --data '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list",
    "params": {}
  }'
```

### Call A Tool

```bash
curl -X POST "$MCP_URL" \
  -H "content-type: application/json" \
  --data '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "generate_horoscope",
      "arguments": {
        "date": "1990-01-01",
        "time": "12:00:00",
        "latitude": 13.0827,
        "longitude": 80.2707,
        "timezone": 5.5,
        "place": "Chennai"
      }
    }
  }'
```

## Response Shape

MCP tool calls return content blocks. The actual tool result is JSON encoded inside `result.content[0].text`.

Typical shape:

```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"section\":\"...\",\"data\":{...}}"
      }
    ]
  }
}
```

Client code should parse `result.content[0].text` as JSON before using the data.

Do not route client behavior by the returned `section` value. Some section labels preserve legacy engine names, such as `arudha_padhas` or `sphuta`, and do not always match the tool name. Route by the tool that was called, then parse that tool's returned payload.

## Tool Catalog By Category

| Category | Tools |
| --- | --- |
| Overview | `generate_horoscope` |
| Birth positions | `get_nakshatra_pada`, `get_planetary_states` |
| Divisional charts | `list_divisional_charts`, `get_divisional_chart` |
| Dashas | `get_dasha` |
| Compatibility | `get_marriage_match` |
| Transits and muhurta | `get_gochara`, `get_gochara_range`, `get_planet_ingress`, `get_muhurta`, `get_saturn_transit` |
| Yogas and doshas | `get_yogas`, `get_doshas`, `get_longevity` |
| Strengths | `get_shad_bala`, `get_bhava_bala`, `get_other_bala`, `get_vimsopaka_bala`, `get_vaiseshikamsa_bala`, `get_ashtakavarga` |
| Jaimini and special points | `get_chara_karakas`, `get_special_lagnas`, `get_sahams`, `get_sphutas`, `get_upagrahas`, `get_amsa_rulers`, `get_house_varnadas` |
| Arudhas | `get_arudha_padas`, `get_graha_arudhas`, `get_surya_arudhas`, `get_chandra_arudhas` |

## Tool Details

### 1. `generate_horoscope`

Use this first when an AI agent needs a concise birth-chart summary and a list of available calculated sections.

Required arguments: common birth input.

Returns:

- Birth details echo
- Ascendant nakshatra and pada
- Moon nakshatra and pada
- Sun nakshatra
- Calendar info
- Available section names

Example:

```json
{
  "name": "generate_horoscope",
  "arguments": {
    "date": "1990-01-01",
    "time": "12:00:00",
    "latitude": 13.0827,
    "longitude": 80.2707,
    "timezone": 5.5,
    "place": "Chennai"
  }
}
```

### 2. `get_nakshatra_pada`

Use this when the user asks for nakshatra, pada, nakshatra lord, or degrees within nakshatra for planets or ascendant.

Required arguments: common birth input.

Returns nakshatra details for Ascendant, Sun, Moon, Mars, Mercury, Jupiter, Venus, Saturn, Rahu, Ketu, Uranus, Neptune, and Pluto.

### 3. `get_planetary_states`

Use this when the user asks which planets are retrograde, combust, exalted, debilitated, in own sign, friend sign, or enemy sign.

Required arguments: common birth input.

Returns grouped lists of planets by condition.

### 4. `list_divisional_charts`

Use this when the AI or user needs to choose which varga chart to request.

Required arguments: none.

Returns the available divisional chart tokens, chart names, and purposes.

Example:

```json
{
  "name": "list_divisional_charts",
  "arguments": {}
}
```

### 5. `get_divisional_chart`

Use this when the user asks for a specific divisional chart such as D-1, D-9, or D-10.

Required arguments: common birth input.

Optional argument:

- `varga`: one of `D-1`, `D-2`, `D-3`, `D-4`, `D-5`, `D-6`, `D-7`, `D-8`, `D-9`, `D-10`, `D-11`, `D-12`, `D-16`, `D-20`, `D-24`, `D-27`, `D-30`, `D-40`, `D-45`, `D-60`, `D-81`, `D-108`, `D-144`

Common usage:

- `D-1`: main rasi chart
- `D-9`: navamsa, marriage, dharma, overall strength
- `D-10`: career
- `D-7`: children
- `D-24`: education
- `D-60`: past-life karma

Example:

```json
{
  "name": "get_divisional_chart",
  "arguments": {
    "date": "1990-01-01",
    "time": "12:00:00",
    "latitude": 13.0827,
    "longitude": 80.2707,
    "timezone": 5.5,
    "varga": "D-9"
  }
}
```

### 6. `get_dasha`

Use this when the user asks about current, past, or future dasha periods.

Required arguments: common birth input.

Optional arguments:

- `system`: dasha system token. Defaults to `vimsottari`.
- `as_of_date`: anchor date in `YYYY-MM-DD`.
- `depth`: 1 to 4. Defaults to a practical depth for the selected system.
- `maha`: expand a specific maha period.
- `antar`: expand a specific antar period inside the selected maha.

Supported systems include planetary dashas such as `vimsottari`, `ashtottari`, `yogini`, `shodasottari`, `tara`, `karaka`, and sign dashas such as `narayana`, `chara`, `kalachakra`, `sthira`, `varnada`, `trikona`, and others exposed by the schema.

Example:

```json
{
  "name": "get_dasha",
  "arguments": {
    "date": "1990-01-01",
    "time": "12:00:00",
    "latitude": 13.0827,
    "longitude": 80.2707,
    "timezone": 5.5,
    "system": "vimsottari",
    "as_of_date": "2026-07-07",
    "depth": 3
  }
}
```

### 7. `get_marriage_match`

Use this when the user asks for Vedic marriage compatibility between two people.

Required arguments:

- `boy`: birth object
- `girl`: birth object

Optional argument:

- `system`: `both`, `north`, or `south`. Defaults to `both` when omitted.

Each birth object requires:

- `date`
- `time`
- `latitude`
- `longitude`
- `timezone`
- optional `place`

Returns:

- North Indian Ashtakoota score
- South Indian porutham result
- Boy and girl nakshatra, pada, and rasi
- Manglik/dosha data
- Beeja and kshetra rasi

Example:

```json
{
  "name": "get_marriage_match",
  "arguments": {
    "boy": {
      "date": "1990-01-01",
      "time": "12:00:00",
      "latitude": 13.0827,
      "longitude": 80.2707,
      "timezone": 5.5,
      "place": "Chennai"
    },
    "girl": {
      "date": "1992-05-15",
      "time": "08:30:00",
      "latitude": 12.9716,
      "longitude": 77.5946,
      "timezone": 5.5,
      "place": "Bengaluru"
    },
    "system": "north"
  }
}
```

### 8. `get_gochara`

Use this for a single-day transit snapshot against a natal chart.

Required arguments:

- common birth input
- `target_date`: transit date in `YYYY-MM-DD`

Optional arguments:

- `target_time`: target time, default local noon
- `include`: enrichment sections such as `ashtakavarga` or `gochara_phala`
- `event_place`, `event_latitude`, `event_longitude`, `event_timezone`, `event_elevation`: event-place override

Returns panchanga, muhurta windows, planetary transits, Tara Bala, Chandra Bala, and Sade Sati context for the target date.

Example:

```json
{
  "name": "get_gochara",
  "arguments": {
    "date": "1990-01-01",
    "time": "12:00:00",
    "latitude": 13.0827,
    "longitude": 80.2707,
    "timezone": 5.5,
    "target_date": "2026-07-07"
  }
}
```

### 9. `get_gochara_range`

Use this when the AI needs raw daily transit details across a date range and wants to reason over the days itself.

Required arguments:

- common birth input
- `from_date`
- `to_date`

Optional arguments:

- `time_of_day`
- `include`
- event-place override fields

Range limit: maximum 60 days.

Use `get_muhurta` instead when the system should rank dates.

### 10. `get_planet_ingress`

Use this when the user asks when planets change signs.

Required arguments:

- `from_date`
- `to_date`

Optional arguments:

- `planets`: list of planets. Defaults to slower planets where appropriate.
- `timezone`: UTC offset used for crossing dates. Defaults to UTC if omitted.
- `ayanamsa_mode`

Returns sidereal sign-change dates, including retrograde back-out and re-entry events.

Example:

```json
{
  "name": "get_planet_ingress",
  "arguments": {
    "from_date": "2026-01-01",
    "to_date": "2027-12-31",
    "planets": ["Saturn", "Jupiter"]
  }
}
```

### 11. `get_muhurta`

Use this when the user asks for auspicious dates for an event.

Required arguments:

- common birth input
- `event_type`
- `from_date`
- `to_date`

Optional arguments:

- `day_part_resolution_minutes`: granularity for time-of-day scoring
- `respect_inauspicious_windows`: whether to account for Rahu, Gulika, and Yamaganda windows
- event-place override fields

Returns ranked candidate dates with scoring breakdown and recommended clean windows.

Range limit: maximum 90 days.

Current supported `event_type` values:

- `griha_pravesha_own`
- `griha_pravesha_rented`
- `travel_prayana`
- `vehicle_purchase`
- `business_shop_opening`
- `property_purchase_registration`

Example:

```json
{
  "name": "get_muhurta",
  "arguments": {
    "date": "1990-01-01",
    "time": "12:00:00",
    "latitude": 13.0827,
    "longitude": 80.2707,
    "timezone": 5.5,
    "event_type": "business_shop_opening",
    "from_date": "2026-08-01",
    "to_date": "2026-09-30"
  }
}
```

### 12. `get_saturn_transit`

Use this when the user asks about Sade Sati, Saturn over Moon, or Saturn over Ascendant.

Required arguments: common birth input.

Returns degree-based and sign-based Sade Sati periods, Moon reference, Ascendant reference, and transit windows.

### 13. `get_yogas`

Use this when the user asks which yogas are present in the chart.

Required arguments: common birth input.

Returns a summary count and full yoga list with chart, name, condition, and effect text.

### 14. `get_doshas`

Use this when the user asks about Manglik, Kala Sarpa, Pitru, Guru Chandala, Ganda Moola, Kalathra, Ghata, or Shrapit dosha.

Required arguments: common birth input.

Returns dosha verdicts and reasoning from the engine.

### 15. `get_longevity`

Use this when the user asks for longevity or ayur category.

Required arguments: common birth input.

Returns life-span category, check summaries, detailed bala/alpa/madhya ayur checks, calculation basis, and key planetary positions.

### 16. `get_ashtakavarga`

Use this when the user asks about Ashtakavarga, BAV, SAV, bindus, or pinda scores.

Required arguments: common birth input.

Returns:

- Binna Ashtakavarga by planet and sign
- Samudhaya Ashtakavarga totals
- Raasi, graha, and sodhya pindas

### 17. `get_shad_bala`

Use this when the user asks for Shadbala or six-fold planetary strength.

Required arguments: common birth input.

Returns sthana, kala, dig, cheshta, naisargika, drik bala, total virupas, total rupas, and strength ratio for the seven classical planets.

### 18. `get_bhava_bala`

Use this when the user asks for strength of houses or bhavas.

Required arguments: common birth input.

Returns House 1 through House 12 with total virupas, rupas, and strength ratio.

### 19. `get_other_bala`

Use this when the user asks for additional bala values not covered by Shadbala.

Required arguments: common birth input.

Returns Harsha Bala, Pancha Vargeeya Bala, Dwadhasa Vargeeya Bala, Ishta Phala, and Kashta Phala.

### 20. `get_vimsopaka_bala`

Use this when the user asks for Vimsopaka Bala or varga-based dignity strength.

Required arguments: common birth input.

Returns four classical weighting schemes: Shadvarga, Sapthavarga, Dashavarga, and Shodashavarga.

### 21. `get_vaiseshikamsa_bala`

Use this when the user asks how many favorable vargas a planet attains.

Required arguments: common birth input.

Returns the auspicious varga count for each planet under the same four weighting schemes.

### 22. `get_chara_karakas`

Use this when the user asks for Jaimini chara karakas such as Atmakaraka or Amatyakaraka.

Required arguments: common birth input.

Returns eight chara karakas with planet, sign, and longitude.

### 23. `get_special_lagnas`

Use this when the user asks for special lagnas such as Pranapada, Indu, Sree, Kunda, Bhava, Hora, Ghati, or Vighati lagna.

Required arguments: common birth input.

Returns each special lagna with sign and longitude.

### 24. `get_sahams`

Use this when the user asks for sahams or Arabic parts.

Required arguments: common birth input.

Returns the computed zodiac positions for sahams such as Punya, Vidya, Yasas, Mitra, Vivaha, Putra, Karma, Roga, and Mrithyu.

### 25. `get_sphutas`

Use this when the user asks for special sphutas or sensitive points.

Required arguments: common birth input.

Returns Tri Sphuta, Chatur Sphuta, Pancha Sphuta, Prana Sphuta, Deha Sphuta, Mrityu Sphuta, Beeja Sphuta, Kshetra Sphuta, Tithi Sphuta, Yoga Sphuta, Rahu Tithi Sphuta, Yogi Sphuta, and Avayogi Sphuta.

### 26. `get_upagrahas`

Use this when the user asks for upagrahas or shadow sub-planets.

Required arguments: common birth input.

Returns Dhuma, Vyatipaata, Parivesha, Indrachaapa, Upaketu, Kaala, Mrityu, Artha Praharaka, Yama Ghantaka, Gulika, and Maandi.

### 27. `get_amsa_rulers`

Use this when the user asks which amsa or fine subdivision each point occupies.

Required arguments: common birth input.

Returns amsa information for Ascendant, planets, upagrahas, special lagnas, varnada lagnas, and sphutas.

### 28. `get_house_varnadas`

Use this when the user asks for house varnada lagnas.

Required arguments: common birth input.

Returns `V2` through `V12` with sign and longitude.

### 29. `get_arudha_padas`

Use this when the user asks for arudha padas such as Arudha Lagna, Dhanarudha, or Upapada Lagna.

Required arguments: common birth input.

Optional argument:

- `varga`: same divisional chart token list as `get_divisional_chart`

Returns the 12 arudha padas for the requested chart. Defaults to D-1.

### 30. `get_graha_arudhas`

Use this when the user asks for arudha signs of the Ascendant and grahas.

Required arguments: common birth input.

Returns arudha signs for Ascendant, Sun, Moon, Mars, Mercury, Jupiter, Venus, Saturn, Rahu, and Ketu.

### 31. `get_surya_arudhas`

Use this when the user asks for arudhas counted from the Sun.

Required arguments: common birth input.

Returns arudha signs for the 12 houses from Surya Lagna.

### 32. `get_chandra_arudhas`

Use this when the user asks for arudhas counted from the Moon.

Required arguments: common birth input.

Returns arudha signs for the 12 houses from Chandra Lagna.

## Choosing The Right Tool

Use this routing guide in AI prompts or integration code:

| User question | Preferred tool |
| --- | --- |
| "Generate my birth chart summary" | `generate_horoscope` |
| "What is my nakshatra?" | `get_nakshatra_pada` |
| "Show D9 / Navamsa" | `get_divisional_chart` with `varga: "D-9"` |
| "Show D10 / career chart" | `get_divisional_chart` with `varga: "D-10"` |
| "What dasha am I running?" | `get_dasha` |
| "Do these two charts match?" | `get_marriage_match` |
| "When does Saturn change sign?" | `get_planet_ingress` |
| "What are today's transits for this chart?" | `get_gochara` |
| "Find a good date for an event" | `get_muhurta` |
| "List good days and let AI decide" | `get_gochara_range` |
| "Am I in Sade Sati?" | `get_saturn_transit` |
| "What yogas are present?" | `get_yogas` |
| "Do I have Manglik dosha?" | `get_doshas` |
| "Which houses are strong?" | `get_bhava_bala` |
| "Which planets are strong?" | `get_shad_bala` |
| "What are my chara karakas?" | `get_chara_karakas` |
| "What is Upapada Lagna?" | `get_arudha_padas` |
| "What are my sphutas?" | `get_sphutas` |

## Integration Notes

- All tools are declared read-only through MCP annotations.
- Most natal tools can reuse cached chart data after the first call.
- `get_gochara_range`, `get_muhurta`, and `get_planet_ingress` are date-range tools and can be more expensive than simple natal-section tools.
- `get_marriage_match` takes two birth objects and does not use the common single-birth input shape.
- The server returns calculation data, not final human counseling. The AI client should write the explanation or recommendation using the returned data.

## Health Check

The server exposes a public health probe at `/mcp/health`. Reusing the `MCP_URL` variable set earlier keeps this call consistent with whichever environment you are configuring:

```bash
curl -sS "$MCP_URL/health"
```

Use it to confirm the server is reachable before wiring the endpoint into an MCP client.