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.

https://authorityastrology.com/mcp/claude

In Claude, add this custom connector URL. Public calculations work anonymously; account tools request permission when needed. Existing OpenAI and Muse connections keep their original URL. OAuth tokens are bound to the endpoint you authorize.

claude mcp add --transport http authority-astrology https://authorityastrology.com/mcp/claude

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.

PLUGIN SETUP

Authority Astrology for Cursor and Grok Bot

Bring precise astrology into your workspace. Calculate birth charts, explore transits and relationship charts, and use your saved profiles with a skill that preserves birth-time certainty and grounds every result in Swiss Ephemeris data.

Get the free plugin and installation guide or download version 1.0.1. Marketplace submissions are under review; the package is available directly now.

Set up in Cursor

1. Download and extract the plugin. Place its contents, including .cursor-plugin, in ~/.cursor/plugins/local/authority-astrology.
2. Restart Cursor and open Customize. Check that Authority Astrology and its calculation skill appear.
3. Choose Authenticate, sign in on Authority Astrology and review the permissions. The full plugin can request this connection when first enabled, including before a public calculation.
4. Ask for a chart using your birth date, local time and birthplace. To use your library, ask to list your saved people and preserve each profile’s birth-time certainty.

For Grok Bot, use its plugin interface when the listing becomes available. See Grok Bot setup for host account requirements. The package includes its HTTPS endpoint and public OAuth client configuration; no API key or client secret is needed. Install one connection rather than adding a duplicate manual MCP entry.

The plugin uses /mcp/claude, our OAuth-compatible endpoint for these clients. The name does not restrict it to Claude. Use the complete version 1.0.1 configuration for account workflows and verify access with get_account_profile after consent. Public service calls remain available anonymously to URL-only MCP clients. Existing OpenAI and Muse connections keep their original endpoint.

The plugin is free and MIT licensed. Hosted-service permissions and limits still apply, and the host may require its own subscription. Your assistant explains the returned calculations; you choose when to save a new chart to your library.

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.