01 / OVERVIEW

A chart engine for your assistant

The MCP exposes our existing calculation engine: placements, aspects, houses, angles, velocities, event times and calculation provenance. It returns no summaries, readings, judgments or ranked recommendations.

02 / CONNECTION

Connect your assistant

https://authorityastrology.com/mcp

Add this URL in a client that supports remote MCP over Streamable HTTP. Public tools need no API key. Account tools use OAuth authorization with explicit scopes and PKCE; your client discovers the authorization endpoints automatically.

The endpoint uses stateless JSON responses. A standard MCP client handles initialization, tool discovery and the required Accept headers. Persistent SSE streams and JSON-RPC batches are not supported.

ChatGPT directory publication is a separate review process. This endpoint is available to compatible MCP clients; a directory listing is not yet being claimed.

03 / THE CONVERSATION

Type the birthplace in chat

Ask for the birth date, local time and birth city/country. Call resolve_birthplace with only the place name. LocationIQ returns candidate labels, coordinates and an IANA timezone. Clarify ambiguous matches in chat, and ask for more detail if there are no matches.

“What is your birth date, local birth time, and birth city/country? If you don’t know the time, that’s fine.”

No external location form or device GPS is needed. Do not guess coordinates or timezones. Do not send names, birth dates or birth times to the place resolver.

For a known time, call validate_birth_data to resolve local civil time to UTC. Repeated clock times require clarification; nonexistent clock times require correction. Preserve approximate or unknown birth-time knowledge.

04 / TOOL REFERENCE

From birthplace to raw chart

resolve_birthplace

{
  "query": "Greenwich, London, United Kingdom"
}

validate_birth_data

{
  "local": {
    "year": 2000,
    "month": 1,
    "day": 1,
    "hour": 12,
    "minute": 0,
    "second": 0
  },
  "timeZone": "Europe/London",
  "disambiguation": "reject"
}

calculate_natal_chart

This synthetic example uses Greenwich coordinates and a UTC instant. In a real request, pass the chosen resolver coordinates and the validated UTC result.

{
  "timeKnowledge": "EXACT",
  "natal": {
    "utc": {
      "year": 2000,
      "month": 1,
      "day": 1,
      "hour": 12,
      "minute": 0,
      "second": 0
    },
    "location": {
      "latitude": 51.4779,
      "longitude": 0
    },
    "houseSystem": "P"
  }
}

When the birth time is unknown

Use the unknown-time branch. Never substitute noon or midnight for an unknown birth time.

{
  "timeKnowledge": "UNKNOWN",
  "unknownTime": {
    "localDate": {
      "year": 2000,
      "month": 1,
      "day": 1
    },
    "timeZone": "Europe/London",
    "location": {
      "latitude": 51.4779,
      "longitude": 0
    }
  }
}

get_capabilities publishes the supported settings and schemas. get_chart_data retrieves complete sections of a large result. get_chart_schema publishes the complete raw result schema for each family.

Six account tools provide scoped access: get_account_profile, list_people, get_person, list_saved_charts, get_saved_chart, and save_chart. Only save_chart writes a saved chart, following the user’s explicit request.

05 / RESPONSE DATA

Complete raw data, with its context

Results include units, certainty, engine provenance and a manifest. Small results are inline. Large results return a calculation reference and section paths: use get_chart_data and follow pagination until complete. A partial page is not a complete chart.

Native chart data includes supported planetary positions and speeds, signs, retrograde status, houses and cusps, angles, aspects and orbs, applying/separating motion and moon phase where the selected calculation provides them. Unknown-time charts return sampled planetary ranges without inventing houses or angles.

Longitudes, latitudes and orbs are degrees; angular speeds are degrees/day. Distances are AU and distance speeds are AU/day. The response’s units and schema describe the remaining fields. Exact, approximate, unknown and unspecified time knowledge are preserved.

Your chosen model interprets the data. Horary returns geometry without judgments; electional results are chronological, with no scoring or ranking. Existing interpreted reports and older saved-chart formats are outside this raw MCP contract.

06 / RELIABLE REQUESTS

Handle limits and missing details

The raw MCP permits 60 requests per minute and two concurrent requests per account or anonymous IP. Calculation workers are separately bounded, with a 60-second execution limit. Respect HTTP 429 and Retry-After. Request bodies are limited to 32 KiB.

Transient calculation references expire after 15 minutes and are held in bounded process memory. Retrieve the needed sections promptly. After expiry or a service restart, calculate again. Large requests can exceed capacity; reduce their time range or number of candidate instants.

Tool failures return isError: true with a structured error code. Ask for missing or invalid input, clarify ambiguous local times, and retry transient service errors. Never invent a successful result after a failed calculation.

07 / DATA HANDLING

Choose what to save

Only the place-search query goes to LocationIQ. Birth data goes to Authority Astrology for calculation. Raw results are encrypted in temporary process memory; no customer profile or saved chart is created unless the user explicitly saves a chart through an authorized account connection.

Anonymous calculation references act as temporary bearer credentials: keep them private. Account results are bound to the account and OAuth grant. Saved raw chart data is encrypted at rest. Disconnecting an account revokes its grant; account deletion also removes its saved raw charts.

Responses use Cache-Control: no-store. Your assistant’s conversation retention is governed separately. Provide only the data needed for the calculation.

08 / EXISTING INTEGRATIONS

Existing natal HTTP API

/api/v1/mcp now serves the same full raw MCP as /mcp, including all 26 tools and optional OAuth account access. Connect using either URL; OAuth grants are specific to the endpoint you connect to.

The dedicated-key natal integration remains available at /api/v1/astrology/mcp, with search_birthplaces and calculate_natal_chart. It uses signed birthplace tokens and a different input contract from the expanded raw MCP.

Its direct HTTP endpoints are /api/v1/astrology/birthplaces and /api/v1/astrology/natal. Refer to the OpenAPI specification for that integration’s request schemas. Keep its dedicated key in server-side credentials, never in chat messages or URLs.