Agents and MCP

astrom8 offers an agent integration for Western natal charts. An assistant collects birth details, shows them back for confirmation, calculates the chart once, and answers follow-up questions from that result. astrom8 calculates the facts; the assistant explains them.

The agent tools are in early access. They are turned on per account by astrom8, and they are off by default. The steps below describe how they work and how to try them with mock data today.

How it works

The agent profile has four tools and one prompt.

Name	Kind	What it does	Credits
`prepare_chart_input`	tool	Checks and normalizes birth details, and returns a summary to confirm	0
`calculate_chart`	tool	Calculates the confirmed chart (`POST /v1/natal-chart`)	1 per successful call
`get_calculation`	tool	Returns an earlier result for a follow-up question	0
`clear_session`	tool	Deletes the session’s details and access to its results	0
`astrom8_heart_v1`	prompt	How to explain results: grounding, uncertainty, consent, costs, privacy	—

The flow is always the same:

Prepare. The assistant sends the birth date, time, time zone and place. astrom8 returns a summary, or asks a question when something is ambiguous (for example 03/04/1990, a Buddhist Era year, or a time that falls in a daylight-saving change).
Confirm. The assistant shows the summary and the cost. Nothing is charged until the user agrees.
Calculate. One calculation per confirmed input. Asking again with the same details reuses the result.
Follow up. Later questions use the stored result for free.
Clear. The user can delete the session at any time.

Birth time

Exact time: the full chart, including houses, ascendant and Moon.
Approximate time (a time and how far off it might be, for example ±60 minutes): the chart is calculated at the stated time, and the result carries a time_approximate limitation. Houses, ascendant, midheaven, the Moon and aspects involving the Moon should be treated as uncertain.
Unknown time: not calculated. astrom8 never guesses a time such as noon.

Place

There is no place lookup. The user (or the assistant, with the user’s agreement) gives the city name, its latitude and longitude, and its IANA time zone, such as Asia/Bangkok.

Use Claude over MCP

The astrom8 MCP server is a remote MCP server using Streamable HTTP and OAuth 2.1. Users sign in with their astrom8 account; no API key goes into the assistant.

In Claude, add a custom connector with the astrom8 MCP server URL that astrom8 gave you for early access.
Sign in with your astrom8 account when Claude asks, and allow access.
Ask Claude for a natal chart. Claude calls prepare_chart_input, shows you the summary, and asks before it runs calculate_chart.

Claude can ask before each tool call that can change something or cost credits; keep that approval on. The server can require a confirmed input, but only the host can show that a person agreed.

Use the agent CLI

The agent CLI is shared with early-access partners on request. It is not in a public repository yet.

The CLI is a second client that uses the same adapter as the MCP server. It is a reference for building your own integration. It needs Bun and runs from the apps/mcp folder of the code you receive. Try it with mock data first. Mock mode uses a bundled synthetic chart: it needs no key, makes no network calls, and costs nothing.

cd apps/mcp
bun install
bun examples/agent-cli.ts --mock --date 1992-04-15 --time 09:30 \
  --timezone Asia/Bangkok --place "Bangkok, Thailand" --lat 13.7563 --lon 100.5018

The CLI prints the summary and asks Calculate for 1 credit? [y/N]. Only y or yes continues. It then prints the facts, shows that a follow-up reuses the result, and clears the session. Mock output is labelled SYNTHETIC and is not a chart for the details you typed. To calculate with the real API, set your API key in the environment and drop --mock. Each successful calculation costs 1 credit. Before it asks, the CLI shows the API host your key will be sent to (api.astrom8.com unless ASTROM8_API_BASE_URL is set).

export ASTROM8_API_KEY=astrom8_...
bun examples/agent-cli.ts --date 1992-04-15 --time 09:30 \
  --timezone Asia/Bangkok --place "Bangkok, Thailand" --lat 13.7563 --lon 100.5018

Option	Meaning
`--precision exact\|approximate\|unknown`	Birth time precision. Defaults to `exact` with `--time`, `unknown` without.
`--window MINUTES`	Required with `approximate`, for example `60`.
`--calendar gregorian\|buddhist`	Calendar of `--date`. Defaults to `gregorian`.
`--house-system P\|W\|K\|E`	Placidus, Whole Sign, Koch or Equal. Defaults to `P`.
`--locale en\|th`	Language of the summary and messages.
`--json`	Print only the full result as JSON on standard output; everything else goes to standard error.
`--yes`	Skip the question. Accepted only with `--mock`.

The CLI never prints your key. It keeps its state in memory for one run and clears it before it exits.

Because the CLI forgets everything when it exits, it cannot retry a request whose outcome is unknown. If a real run ends with OUTCOME_UNKNOWN, check your credit usage in the dashboard before running it again: a new run is a new request and can be charged again.

Troubleshooting

You see	What it means	What to do
`INPUT_NEEDS_CLARIFICATION`	The date, calendar or time is ambiguous, or Placidus or Koch houses were asked for beyond 66.5° north or south	Answer the question (which date order, which side of a daylight-saving change), or use Whole Sign or Equal houses
`VALIDATION_FAILED`	A value is invalid, for example a time zone that is not an IANA name	Correct the value and prepare again
`AUTHENTICATION_REQUIRED`	The sign-in or API key was not accepted	Sign in again, or check `ASTROM8_API_KEY`
`CREDITS_EXHAUSTED`	The account has no credits left	Add credits in the dashboard; nothing was charged
`PERMISSION_DENIED`	The account or key may not use this calculation	Check the account’s plan or the key’s scope
`RATE_LIMITED`	Too many requests, or the daily agent limit was reached	Wait and try again later
`OUTCOME_UNKNOWN`	The request may have reached astrom8, but no answer came back	Do not resend blindly. Over MCP, wait a minute and confirm a retry: it reuses the same request, so it is normally not charged twice (a retry after signing in again can be). With the CLI, check your usage first
`IN_PROGRESS`	The same calculation is already running	Wait for it; do not start another
`INVALID_UPSTREAM_OUTPUT`	astrom8 returned a result that failed checks; the credit may have been used	Do not retry; contact support with the request id
`EXPIRED` or `NOT_FOUND` (MCP)	The session or result is gone or belongs to someone else	Prepare and confirm again; a new calculation costs 1 credit
`UNSUPPORTED_CAPABILITY`	For example an unknown birth time	Give an exact time, or an approximate time with a window

Compatibility

Host or client	Transport and sign-in	Confirmation before a charge	Status
Claude (custom connector)	Remote MCP, Streamable HTTP, OAuth 2.1	Claude’s tool approval plus a server-side confirmation id	Built for this host. Tested against mocks only; not yet tested with a live Claude client
agent CLI (early access, on request)	Direct API call with `ASTROM8_API_KEY`	`[y/N]` question on the terminal	Mock mode tested; real mode not yet tested live
Other MCP hosts	Remote MCP, Streamable HTTP, OAuth 2.1	Depends on the host’s tool approval	Not tested

Limits that apply everywhere:

Western natal charts only.
English and Thai.
No place lookup.
Unknown birth time is not calculated.

Start here

Build and operate

How it works

Birth time

Place

Use Claude over MCP

Use the agent CLI

Troubleshooting

Compatibility

​How it works

​Birth time

​Place

​Use Claude over MCP

​Use the agent CLI

​Troubleshooting

​Compatibility

How it works

Birth time

Place

Use Claude over MCP

Use the agent CLI

Troubleshooting

Compatibility