:::note **TL;DR** - An astrology API for AI agents must return deterministic structured JSON so the model reads real charts instead of inventing them. - Agent-ready means three things wired in: Remote MCP over Streamable HTTP with no local setup, typed function-calling schemas from a live OpenAPI 3.1 spec, and machine-readable discovery files (llms.txt, AGENTS.md, agent-card.json). - Quota is flat: 1 request equals 1 unit, tool discovery is free, only invocations count. - Ship this with the [Astrology API](/products/astrology-api "production-ready astrology API for AI agents with natal charts, transits, and Remote MCP") in about 30 minutes. ::: Most AI agents fail at astrology for one reason: the model guesses. Ask a raw language model for a natal chart and it hallucinates planet positions, invents house cusps, and drifts a degree here or an hour there. An astrology API for AI agents fixes this by returning verified, deterministic calculations the agent grounds its answer on. This guide is the buyer-intent reference for that exact phrase. It covers what agent-ready actually requires, how to connect over Remote MCP, how to wire the same endpoint into OpenAI and Anthropic function calling from a live OpenAPI 3.1 spec, and how tool-call quota economics work so the bill stays predictable as your agent scales. ## What makes an astrology API agent-ready? An astrology API is agent-ready when a language model can discover it, call it, and trust the result without a human in the loop. That means four concrete properties: deterministic structured JSON (same input, same output, every time), a Remote MCP server the agent connects to over HTTP, typed function-calling schemas generated from a live spec, and machine-readable discovery surfaces. RoxyAPI ships all four across 12 domains and 164+ endpoints under one key. The failure mode of a non-agent-ready API is subtle. A generic text endpoint returns prose the model paraphrases, so errors compound silently. A structured endpoint returns fields like `sign`, `degree`, `house`, and `isRetrograde` that the agent reads verbatim and cannot rewrite. The agent stays in its own voice and system prompt while every fact traces back to a NASA JPL Horizons verified calculation. That separation, your interpretation layer over our calculation layer, is the whole design. Discovery is the fourth property, and it is what lets an agent find the API with zero manual wiring. RoxyAPI publishes an llms.txt manifest for AI crawlers, an AGENTS.md execution playbook inside every SDK for coding agents, and an agent-card.json for agent-to-agent discovery. A runtime agent also pulls the full tool catalog, with typed input schemas and enum values, from the free `tools/list` handshake on connect. So the agent learns not only that the endpoint exists but exactly how to call it before it spends a single quota unit. Ready to build this? The [Astrology API](/products/astrology-api "production-ready astrology API with natal charts, synastry, transits, and Remote MCP for agents") gives you deterministic charts, Remote MCP, and typed SDKs under one key. [See pricing](/pricing "RoxyAPI flat all-inclusive pricing, one subscription for every domain"). ## Why deterministic structured JSON stops chart hallucination Deterministic structured JSON is the single most important property for grounding an agent. When the natal chart endpoint returns `{ "sign": "Cancer", "degree": 23.05, "house": 9 }`, the model has a fact it cannot argue with, so it stops fabricating positions. The same birth data always returns the same numbers, which makes responses cacheable and testable. Non-deterministic text output, by contrast, gives the model room to drift. Each field carries a rich description in the spec so the agent knows not just the value but what it means. The `planets` array returns 14 bodies, the 10 classical planets plus lunar nodes, Chiron, and Black Moon Lilith, each with `longitude`, `sign`, `degree`, `house`, `speed`, and `isRetrograde`. The `aspects` array returns `orb`, `strength`, and `interpretation`. Feed this into a companion app and the model narrates a real chart. Ground every turn on structured data and hallucinated charts disappear. This is the grounding pattern covered in depth on the [MCP docs](/docs/mcp "connect AI agents to RoxyAPI over Remote MCP for grounded calculations"). ## How do you connect an agent over Remote MCP? You connect a runtime agent by pointing it at a per-domain Remote MCP server over Streamable HTTP, with no local install and no self-hosting. The astrology server lives at `/mcp/astrology` and exposes 33 tools auto-generated from the OpenAPI spec. Authenticate with an `X-API-Key` header, an `Authorization: Bearer` token, or an `api_key` query parameter. The transport is stateless HTTP, so it runs in seconds inside Claude Desktop, ChatGPT, Gemini, n8n, or any MCP-compatible client. There is a routing rule worth learning once. Coding agents (GitHub Copilot, Claude Code, Cursor) that write integration code connect the keyless Docs server at `/mcp/docs`, which returns documentation and field contracts so they generate correct calls first try. Deployed runtime agents that make real, billable calculations connect the per-domain servers like `/mcp/astrology`. Never point a coding agent at a domain server; it has no reason to burn quota computing a chart while writing code. ```json { "mcpServers": { "roxy-astrology": { "type": "http", "url": "https://roxyapi.com/mcp/astrology", "headers": { "X-API-Key": "YOUR_API_KEY" } } } } ``` ## How do you wire it into OpenAI and Anthropic function calling? You wire it in by declaring a tool whose JSON schema mirrors the endpoint request schema from the live OpenAPI 3.1 spec, then letting the model fill the arguments. Because RoxyAPI generates its spec from production, the schema never drifts from the live API, so a tool definition derived from it will not return a 400. Below is a real tool definition for the natal chart endpoint, with the exact field names, types, and enum values pulled from the spec. ```json { "type": "function", "function": { "name": "generateNatalChart", "description": "Generate a complete Western natal chart with planets, houses, and aspects.", "parameters": { "type": "object", "properties": { "date": { "type": "string", "description": "Birth date YYYY-MM-DD" }, "time": { "type": "string", "description": "Birth time HH:MM:SS, 24-hour" }, "latitude": { "type": "number" }, "longitude": { "type": "number" }, "timezone": { "type": "number", "description": "UTC offset in hours, or an IANA name" }, "houseSystem": { "type": "string", "enum": ["placidus", "whole-sign", "equal", "koch"] } }, "required": ["date", "time", "latitude", "longitude", "timezone"] } } } ``` The typed SDKs (TypeScript, Python, PHP, C#, Go) and the WordPress plugin all regenerate from the same spec. Full tool patterns for OpenAI and Anthropic live in the [function calling guide](/docs/guides/function-calling "wire RoxyAPI endpoints into OpenAI and Anthropic function calling with typed schemas"). ## How does tool-call quota economics work for agent builders? Quota is flat and legible: 1 request equals 1 unit, whether the agent calls REST or Remote MCP. Tool discovery is free (the `tools/list` handshake an agent runs on connect costs nothing), and only actual invocations (`tools/call`) count against your monthly quota. There is no per-token markup, no credit weighting where one endpoint secretly costs five units, and no per-domain fee. A natal chart, a synastry, and a daily horoscope each cost exactly one unit. For companion and chat agents, two patterns keep the bill flat as daily active users grow. First, deterministic calculations are cacheable: the natal chart endpoint sets an `X-Cache-TTL` so repeat reads of the same birth data are served from cache. Second, keep memory in your own stack. RoxyAPI stores no end-user data, so your agent computes a chart once, caches the structured JSON, and grounds every future conversation turn on that stored result without re-billing. Cache the calculation, own the memory. :::tip Compute a users natal chart once, store the structured JSON in your own database, and ground every later turn on it. You pay for one calculation, not one per message. ::: ## How do you call the natal chart endpoint from an agent? Every coordinate-dependent call starts with a location lookup, then feeds the coordinates into the chart endpoint. First call `GET /location/search?q={city}` to resolve latitude, longitude, and an IANA timezone. Then `POST /astrology/natal-chart` with the birth date, time, and those coordinates. The timezone field accepts a decimal offset or an IANA name, so you can pass the location results `timezone` straight through and let the API resolve the DST-correct offset for the birth date. :::tabs ### curl ```bash # 1. Resolve coordinates and timezone curl "https://roxyapi.com/api/v2/location/search?q=Austin" \ -H "X-API-Key: YOUR_API_KEY" # 2. Generate the natal chart curl -X POST "https://roxyapi.com/api/v2/astrology/natal-chart" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "date": "1990-07-15", "time": "14:30:00", "latitude": 30.26715, "longitude": -97.74306, "timezone": "America/Chicago" }' ``` ### TypeScript ```typescript import { createRoxy } from "@roxyapi/sdk"; const roxy = createRoxy(process.env.ROXY_API_KEY!); const { data } = await roxy.astrology.generateNatalChart({ body: { date: "1990-07-15", time: "14:30:00", latitude: 30.26715, longitude: -97.74306, timezone: "America/Chicago", }, }); console.log(data.ascendant.sign, data.summary.dominantElement); ``` ### Python ```python from roxy_sdk import create_roxy roxy = create_roxy("YOUR_API_KEY") chart = roxy.astrology.generate_natal_chart( date="1990-07-15", time="14:30:00", latitude=30.26715, longitude=-97.74306, timezone="America/Chicago", ) print(chart["ascendant"]["sign"], chart["summary"]["dominantElement"]) ``` ::: Here is a trimmed excerpt of the real production response, so you can see the exact shape an agent reads: ```json { "birthDetails": { "date": "1990-07-15", "time": "14:30:00", "timezone": -5 }, "ascendant": { "sign": "Scorpio", "degree": 2.93 }, "midheaven": { "sign": "Leo", "degree": 5.78 }, "planets": [ { "name": "Sun", "sign": "Cancer", "degree": 23.05, "house": 9, "isRetrograde": false } ], "aspectsInterpretation": { "dominant": "balanced", "harmonious": 7, "challenging": 17, "neutral": 13 }, "summary": { "dominantElement": "Water", "dominantModality": "Cardinal", "retrogradePlanets": ["Saturn", "Uranus", "Neptune", "Pluto", "North Node", "South Node"] } } ``` Paste your key and run the same call live in the [API reference](/api-reference#tag/western-astrology/POST/astrology/natal-chart "live natal chart API playground returning real production responses"). Every field traces to a calculation verified against NASA JPL Horizons; see the [methodology](/methodology "how RoxyAPI verifies accuracy against NASA JPL Horizons"). ## FAQ **What is the best astrology API for AI agents?** The best astrology API for AI agents returns deterministic structured JSON, ships a Remote MCP server, and generates typed function-calling schemas from a live OpenAPI 3.1 spec. RoxyAPI does all three across 12 domains and 164+ endpoints under one key, with charts verified against NASA JPL Horizons so agents ground answers instead of hallucinating them. **How do I stop my AI agent from hallucinating birth charts?** Ground the agent on structured calculations instead of letting the model guess. Connect RoxyAPI over Remote MCP or declare the natal chart endpoint as a function-calling tool, then have the agent read the returned `sign`, `degree`, and `house` fields verbatim. The model narrates the chart in its own voice while every number comes from a verified calculation. **Does RoxyAPI support Remote MCP for AI agents?** Yes. Each of the 12 domains has a Remote MCP server over Streamable HTTP, such as `/mcp/astrology` with 33 tools. There is no local setup or self-hosting. Runtime agents like ChatGPT, Claude Desktop, Gemini, and n8n connect the per-domain servers with an API key, while coding agents connect the keyless Docs server at `/mcp/docs`. **How much does an astrology API for AI agents cost per tool call?** Pricing is flat: 1 request equals 1 unit, whether the call is REST or an MCP tool invocation. Tool discovery is free and only invocations count. There is no per-token markup, no credit weighting, and no per-domain fee, so a natal chart and a daily horoscope each cost exactly one unit under one all-inclusive subscription. **Can AI agents discover the API automatically?** Yes. RoxyAPI publishes machine-readable discovery surfaces: llms.txt for AI crawlers, AGENTS.md in every SDK for coding agents, and an agent-card.json for agent-to-agent discovery. Runtime agents also fetch the full tool catalog with typed input schemas from any MCP server through the free `tools/list` handshake, so no manual configuration is required. ## Conclusion An astrology API for AI agents earns its place by removing the one hard thing that is not your product: verified multi-domain calculation. Return deterministic JSON, expose it over Remote MCP and function calling from a spec that never drifts, and your agent grounds every answer in real data while you own the voice, prompt, and memory. Start with the [Astrology API](/products/astrology-api "production-ready astrology API for AI agents with Remote MCP and typed SDKs") and pick a plan on the [pricing page](/pricing "RoxyAPI flat all-inclusive pricing for every domain under one key").