Vedākṣha

Integration Guide — MCP Integration

7 tools your agent already knows.

The Model Context Protocol (MCP) is a standard transport for exposing typed tools to AI agents via JSON-RPC 2.0. Vedākṣha exposes 7 tools with full JSON schemas — any MCP-compatible agent can call them without custom prompting, output parsing, or glue code.

Auth: OAuth 2.1. Transport: JSON-RPC 2.0 over HTTP or stdio. Errors are structured with machine-readable codes and suggested_action fields that let agents self-correct without human intervention.

Starting the Server

The Vedākṣha MCP server supports both stdio transport (for Claude Desktop, local agents) and HTTP transport (for remote agents and production deployments).

stdioterminal
vedaksha-mcp --transport stdio
HTTPterminal
vedaksha-mcp --transport http --port 8080
Configmcp.json
{
  "mcpServers": {
    "vedaksha": {
      "command": "vedaksha-mcp",
      "args": ["--transport", "stdio"]
    }
  }
}

The 7 Tools

compute_natal_chart

Computes a complete natal chart and returns it as a ChartGraph JSON object. Includes planetary longitudes, house cusps, nakshatras, dashas, aspects, dignities, yogas, and patterns. This is the primary entry point for most workflows.

Parameters

julian_dayf64Julian Day in Terrestrial Time (TT).
latitudef64Geographic latitude in decimal degrees. Negative = south.
longitudef64Geographic longitude in decimal degrees. Negative = west.
configChartConfig?Optional. House system, ayanamsha, extra bodies, data classification. Defaults to Vedic/Lahiri/Placidus.

Returns

ChartGraph — the full typed graph with all 10 node types.
compute_dasha

Returns the dasha tree for a previously computed chart. Each DashaPeriod node carries the lord planet, start Julian Day, end Julian Day, and duration in days. The tree goes from Mahadasha down through Antardasha, Pratyantardasha, Sookshma, and Prana.

Parameters

chart_idstringDeterministic ID returned by compute_natal_chart.
systemDashaSystem?Optional. Vimshottari | Yogini | Chara. Default: Vimshottari.

Returns

DashaTree — recursive structure up to 5 levels of sub-periods.
compute_vargas

Computes one or more of the 16 Shodasha Varga divisional charts. Each varga is an independent ChartGraph with its own planetary positions, house cusps, and dignities. Request multiple divisions in one call — they are computed in parallel.

Parameters

chart_idstringDeterministic ID from compute_natal_chart.
divisionsnumber[]Array of divisional chart numbers, e.g. [2, 9, 12]. Valid range 1–60.

Returns

VargaMap — keyed by division number, each value is a full ChartGraph.
emit_graph

Emits the ChartGraph as Cypher (Neo4j MERGE statements), SurrealQL (RELATE syntax), JSON-LD (Schema.org-compatible), plain JSON, or RAG-optimised embedding text. All formats use deterministic node IDs.

Parameters

chart_idstringDeterministic ID from compute_natal_chart.
formatEmitFormatCypher | SurrealQL | JsonLd | Json | EmbeddingText

Returns

string — the emitted output in the requested format.
search_transits

Finds exact transit moments in a Julian Day range. Each TransitEvent carries the exact JD, ingress/egress flag, aspect type, orb at exactitude, and a ready-to-use natural language description. Suited for streaming to AI agents.

Parameters

planetPlanetThe transiting body (Sun through Pluto or lunar nodes).
targetTransitTargetPlanet | Sign | House | Degree — what the transit is to.
start_jdf64Search window start (Julian Day).
end_jdf64Search window end (Julian Day).
configTransitConfig?Optional. Orb, aspect types to include, ingress-only flag.

Returns

TransitEvent[] — exact moment, direction, and description for each hit.
search_muhurta

Finds auspicious time windows matching classical muhurta criteria. Results are scored from 0–100 by combining tithi quality, nakshatra quality, planetary hora strength, and any active auspicious yogas. Windows are sorted highest-score first.

Parameters

criteriaMuhurtaCriteriaTithi, nakshatra, weekday, hora, and yoga conditions. Any combination.
start_jdf64Search window start.
end_jdf64Search window end.
locationGeoPointLatitude and longitude for local time and house-dependent criteria.

Returns

MuhurtaWindow[] — time windows sorted by combined auspiciousness score.
describe_chart

Returns structured natural-language descriptions for the chart's most significant features: active yogas, planetary dignities and weaknesses, dominant dasha period, and notable patterns. Ready for agent relay without further interpretation.

Parameters

chart_idstringDeterministic ID from compute_natal_chart.
localeLocale?Optional. en | hi | sa | ta | te | kn | bn. Default: en.

Returns

ChartDescription — pre-written paragraphs keyed by topic.

Calling Tools via JSON-RPC

request.json
{
  "jsonrpc": "2.0",
  "id": "req-001",
  "method": "tools/call",
  "params": {
    "name": "compute_natal_chart",
    "arguments": {
      "julian_day": 2460389.0,
      "latitude":   28.6139,
      "longitude":  77.2090,
      "config": {
        "house_system": "Placidus",
        "ayanamsha":    "Lahiri",
        "data_class":   "Anonymous"
      }
    }
  }
}

Structured Error Responses

Every error from the Vedākṣha MCP server follows a consistent shape. The suggested_action field is machine-readable — AI agents can read it and self-correct without escalating to a human.

error-response.json
{
  "jsonrpc": "2.0",
  "id": "req-001",
  "error": {
    "code": -32001,
    "message": "Julian Day 1000000.0 is outside ephemeris coverage.",
    "data": {
      "error_code":       "DATE_OUT_OF_RANGE",
      "julian_day":       1000000.0,
      "valid_min":        2287184.5,
      "valid_max":        2816787.5,
      "suggested_action": "Use a Julian Day in the range 2287184.5–2816787.5 (1550–2650 CE), or switch to the DE441 ephemeris for extended coverage."
    }
  }
}
DATE_OUT_OF_RANGE

Julian Day is outside the ephemeris coverage window.

suggested_action: Use a JD within DE440 range (1550–2650 CE) or DE441 (-13000 to +17000).

BODY_NOT_AVAILABLE

Requested planet or asteroid not included in the current ephemeris file.

suggested_action: Switch to an ephemeris file that covers the requested body, or omit it from the config.

INVALID_FORMAT

A parameter value did not match its expected type or enum.

suggested_action: Inspect the JSON schema for the tool and correct the offending field.

CHART_NOT_FOUND

The chart_id supplied does not match any computed chart in the current session.

suggested_action: Call compute_natal_chart first and use the returned chart_id.

PII-Blind Security Model

The Vedākṣha MCP server never receives a person's name, date of birth as a calendar date, or any other identifying string. All inputs are in astronomical units: Julian Day, decimal latitude, decimal longitude. The caller is responsible for the date-to-JD conversion before the tool call.

When the caller sets data_class: "Anonymous", the graph itself contains no PII. The mapping between a person and their Julian Day is never sent to the server.

← Graph Output·WASM Browser →