> ## Documentation Index
> Fetch the complete documentation index at: https://docs.astrom8.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Agents and MCP

> Use astrom8 natal charts from Claude over MCP, and how the agent tools behave.

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.

> [!NOTE]
>
> 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:

1. **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).
2. **Confirm.** The assistant shows the summary and the cost. Nothing is charged until the user agrees.
3. **Calculate.** One calculation per confirmed input. Asking again with the same details reuses the result.
4. **Follow up.** Later questions use the stored result for free.
5. **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.

1. In Claude, add a custom connector with the astrom8 MCP server URL that astrom8 gave you for early access.
2. Sign in with your astrom8 account when Claude asks, and allow access.
3. 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

> [!NOTE]
>
> 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](https://bun.sh) 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.

```bash theme={null}
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).

```bash theme={null}
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.

> [!WARNING]
>
> 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.