Build an AI astrology chatbot

A language model can talk about a kundli, but it cannot calculate one: asked for a planet's position, it will produce a plausible number that is wrong. The fix is to let the model call the API for every fact, and only explain what the API returns.

Two ways to connect

With MCP, every public operation is a tool, and the model can also search these docs over the docs MCP server.

Tool calling from your server

Give the model a few tools, each one an operation, with its parameters from the OpenAPI spec. Start small: POST /v1/kundli (2 credits), POST /v1/dasha/vimshottari/current (2 credits), GET /v1/panchang (1 credit) and POST /v1/match/ashtakoot (1 credit) answer most questions.

When the model calls a tool, your server makes the request and hands back the JSON:

// Your server: the model asked for a kundli. The key never reaches the browser.
async function getKundli(birth) {
  const res = await fetch('https://api.astrologics.in/v1/kundli', {
    method: 'POST',
    headers: { Authorization: `Bearer ${process.env.ASTROLOGICS_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({ birth }),
  });
  const body = await res.json();
  if (!res.ok) return { error: body.error.code, message: body.error.message };   // let the model ask the user again
  return body.data;
}

Pass errors back to the model as they are. A place_ambiguous error carries candidates, so the model can ask the user which place they meant; see errors.

Rules for the model

Put these in its instructions:

• Use the tools for every position, period, date and score. Never estimate one.
• If the birth time is not known, say so, and send time_accuracy: "unknown" rather than a guessed time.
• Say which method a result follows when it matters, for example the Lahiri ayanamsa or the Ashtakoot table; see conventions.
• Present results as what the tradition says, not as certainty or as medical, legal or financial advice. See the disclaimer.

Keys, costs and data

• Keys. Keep the secret key on your server. A chatbot running in a browser or a phone must call your server, not us. See mobile apps.
• Costs. Each tool call is an ordinary call, charged its operation's credits; errors are free and test keys are never charged. A chart for one person does not change, so cache it for the conversation instead of asking again. See caching.
• Hindi. Add lang=hi to get labels and readings in Hindi for a Hindi conversation. See languages.
• Birth details. They are your user's personal data. We do not store request bodies; decide what your chatbot keeps, and tell your users.