# First calls in five minutes

This is a worked session against the hosted service. All examples use the
same chart subject — 1990-01-01, 12:00, London — so your first response
matches the numbers below exactly. Worked JSON uses the plain REST endpoint
at `https://mcp.agentastrology.com`; MCP calls are identical except for the
tool-call envelope and the connection, which the connect guide covers.

## 1. Cast a natal chart — `astro_chart`

```sh
curl -X POST https://mcp.agentastrology.com/v1/tools/astro_chart \
  -H "Authorization: Bearer <key>" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "natal",
    "birthData": {
      "year": 1990,
      "month": 1,
      "day": 1,
      "hour": 12,
      "minute": 0,
      "latitude": 51.5074,
      "longitude": -0.1278,
      "timezone": 0
    }
  }'
```

As an MCP tool call the same request is:

```json
{
  "name": "astro_chart",
  "arguments": {
    "method": "natal",
    "birthData": {
      "year": 1990,
      "month": 1,
      "day": 1,
      "hour": 12,
      "minute": 0,
      "latitude": 51.5074,
      "longitude": -0.1278,
      "timezone": 0
    }
  }
}
```

## 2. Read the response

The response is a `birthChart` object. The verified values for this input:

```json
{
  "summary": {
    "dateTime": "1990-01-01 12:00 (UTC+0)",
    "universalTime": "12:00:00",
    "houseSystem": "Placidus system",
    "coordinates": "51d30'N, 0d8'W",
    "zodiac": "Tropical",
    "ayanamsaOffset": null
  },
  "planets": [
    { "id": "Sun", "longitude": 280.814,
      "sign": { "sign": 9, "signName": "Capricorn", "degrees": 10, "minutes": 48, "seconds": 51 },
      "house": 10 },
    { "id": "ASC",
      "sign": { "signName": "Aries", "degrees": 24, "minutes": 56 } }
  ],
  "houses": [
    { "house": 1, "longitude": 24.934,
      "sign": { "signName": "Aries", "degrees": 24, "minutes": 56 } }
  ]
}
```

The chart subject's Sun is Capricorn 10°48′ — longitude 280.814° — and the
Ascendant is Aries 24°56′. The full output also includes the midheaven,
vertex, major aspects, technical coordinates, and the Part of Fortune and
Part of Spirit. Planet longitudes are decimal degrees in the tropical zodiac
by default.

## 3. Render the wheel — `astro_render_wheel`

```sh
curl -X POST https://mcp.agentastrology.com/v1/tools/astro_render_wheel \
  -H "Authorization: Bearer <key>" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "single",
    "birthData": {
      "year": 1990,
      "month": 1,
      "day": 1,
      "hour": 12,
      "minute": 0,
      "latitude": 51.5074,
      "longitude": -0.1278,
      "timezone": 0
    }
  }'
```

The response is `{ "svg": string, "style": "wheel", "harmonic": 1 }`. The
`svg` field is a full standalone SVG document (about 138 KB for this chart —
wheel, houses, planets, and aspect lines). Save it to a file and open it in a
browser:

```sh
curl -X POST https://mcp.agentastrology.com/v1/tools/astro_render_wheel \
  -H "Authorization: Bearer <key>" \
  -H "Content-Type: application/json" \
  -d '{ "method": "single", "birthData": { "year": 1990, "month": 1, "day": 1, "hour": 12, "minute": 0, "latitude": 51.5074, "longitude": -0.1278, "timezone": 0 } }' \
  | python3 -c "import json,sys,sysconfig; out=json.load(sys.stdin); open('wheel.svg','w').write(out['svg'])" 2>/dev/null || \
curl -X POST https://mcp.agentastrology.com/v1/tools/astro_render_wheel \
  -H "Authorization: Bearer <key>" -H "Content-Type: application/json" \
  -d '{ "method": "single", "birthData": { "year": 1990, "month": 1, "day": 1, "hour": 12, "minute": 0, "latitude": 51.5074, "longitude": -0.1278, "timezone": 0 } }' \
  -o response.json
```

Then pull the `svg` field out of `response.json` with any JSON tool. Pass
`"style": "square"` for the square layout, `"harmonic": 4` for a harmonic
chart (whole numbers from 1 to 360), or `"mode": "dark"` for the midnight
register — every render tool accepts `mode` (`"light"` is the default).

## 4. A flat-input call — `astro_moment`

`astro_moment` does not take `birthData`. Its fields are flat at the top
level, so don't nest them:

```sh
curl -X POST https://mcp.agentastrology.com/v1/tools/astro_moment \
  -H "Authorization: Bearer <key>" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "moon-phase",
    "year": 2026,
    "month": 8,
    "day": 9,
    "hour": 12,
    "minute": 0,
    "timezone": -3,
    "houseSystem": "placidus",
    "zodiac": "tropical"
  }'
```

The response:

```json
{
  "moon": {
    "sign": { "signName": "Cancer", "degrees": 4, "minutes": 26 },
    "longitude": 94.435,
    "isRetrograde": false,
    "house": null
  },
  "phase": {
    "name": "Waning Crescent",
    "displayName": "Balsamic Moon (Waning Crescent)",
    "elongation": 317.386,
    "elongationDegrees": 317,
    "elongationMinutes": 23
  },
  "zodiac": "tropical",
  "ayanamsaOffset": null
}
```

Only `year`, `month`, `day`, `houseSystem`, and `zodiac` are required;
`hour`, `minute`, `second`, `latitude`, `longitude`, and `timezone` are
optional. Use a current date rather than the 1990 example to see the phase
for "now".

## 5. Debugging a bad call

Wrong payloads do not return charts. Check the body for a missing `method`,
a `birthData` field passed to a flat tool like `astro_moment`, or a timezone
written as a string (`"Europe/London"`) instead of a number. Every failure
comes back with a structured error envelope — the errors guide lists the
codes and what each one means.

## Related

- [`public-connect.md`](public-connect.md) — get a key and connect Claude
  Code, Claude Desktop, or plain REST.
- [`public-errors.md`](public-errors.md) — error codes and rate limits.