# Connect to Agent Astrology

Agent Astrology is a hosted astrology service for AI agents: 29 tools
covering chart computation, aspect analysis, dignities, event search,
lookups, time-lord techniques, and SVG chart rendering. The primary
surface is a remote MCP server; a plain REST API exposes the same tools
over HTTP.

- **MCP endpoint:** `https://mcp.agentastrology.com/mcp` — Streamable
  HTTP transport
- **Auth:** `Authorization: Bearer <key>` on every request
  (`x-api-key: <key>` is accepted as an alternative)
- **Get a key:** `https://agentastrology.com/account`
- **REST alternative:** `https://mcp.agentastrology.com/v1` — see
  [`public-quickstart.md`](public-quickstart.md)

Pick your client below; every block is copy-paste ready once
`YOUR_API_KEY` is replaced with a real key.

## Get an API key

1. Sign in at `https://agentastrology.com/account`.
2. Create a key and copy it.
3. Keys are free during the beta and currently unlock all 29 tools.
   Create and revoke keys from the same page at any time.

**Keep keys out of committed files.** MCP config files often live inside
repositories (`.mcp.json`, `.cursor/mcp.json`, `.vscode/mcp.json`).
Prefer user-level config paths, environment variables, or prompted
inputs (see the VS Code setup) — and revoke any key that leaks.

## Claude Code

```sh
claude mcp add --transport http astrolabi https://mcp.agentastrology.com/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"
```

Verify with `claude mcp list` — `astrolabi` should report as connected
(restart the session if it is not picked up). To register the server for
every project instead of only the current one, add `-s user` right after
`add`.

## Claude Desktop

Claude Desktop launches local (stdio) servers from its config file, and
its connector settings expect OAuth sign-in — neither takes a bearer-key
server URL directly yet. Bridge with `mcp-remote` (requires Node.js).
Edit `claude_desktop_config.json`:

- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "astrolabi": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.agentastrology.com/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

`Authorization:${AUTH_HEADER}` has no space after the colon on purpose —
some platforms split spaced arguments. Restart Claude Desktop after
saving; `astrolabi` appears in the tools list.

## Cursor

One-click install:

[Install in Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=astrolabi&config=eyJ0eXBlIjoiaHR0cCIsInVybCI6Imh0dHBzOi8vbWNwLmFnZW50YXN0cm9sb2d5LmNvbS9tY3AiLCJoZWFkZXJzIjp7IkF1dGhvcml6YXRpb24iOiJCZWFyZXIgWU9VUl9BUElfS0VZIn19)

The link installs the server with a `YOUR_API_KEY` placeholder — replace
it in Cursor Settings → MCP (or in the file). Manual setup: add to
`~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "astrolabi": {
      "url": "https://mcp.agentastrology.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

Prefer the user-level `~/.cursor/mcp.json` over a project
`.cursor/mcp.json`, which is easy to commit by accident.

## VS Code

One-click install — VS Code prompts for the key and stores it outside
your repository:

[Install in VS Code](https://vscode.dev/redirect/mcp/install?name=astrolabi&inputs=%5B%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22astrolabi-key%22%2C%22description%22%3A%22Agent%20Astrology%20API%20key%22%2C%22password%22%3Atrue%7D%5D&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.agentastrology.com%2Fmcp%22%2C%22headers%22%3A%7B%22Authorization%22%3A%22Bearer%20%24%7Binput%3Aastrolabi-key%7D%22%7D%7D)

Manual setup — run "MCP: Open User Configuration" from the Command
Palette and add:

```json
{
  "inputs": [
    {
      "type": "promptString",
      "id": "astrolabi-key",
      "description": "Agent Astrology API key",
      "password": true
    }
  ],
  "servers": {
    "astrolabi": {
      "type": "http",
      "url": "https://mcp.agentastrology.com/mcp",
      "headers": {
        "Authorization": "Bearer ${input:astrolabi-key}"
      }
    }
  }
}
```

VS Code asks for the key on first use and keeps it encrypted — nothing
secret sits in the JSON.

## ChatGPT

ChatGPT custom connectors currently authenticate with OAuth or not at
all — they cannot send an API-key header, so a direct MCP connection is
not available yet. Use the REST surface as a Custom GPT action instead:
create a GPT → Configure → Actions → Import from URL →
`https://mcp.agentastrology.com/v1/openapi.json`, set Authentication to
API Key with Auth Type "Bearer", and paste your key. Every tool becomes
a callable action.

## Any other MCP client

Most MCP clients accept this configuration shape (the top-level key name
varies — `mcpServers`, `servers`, or the client's own registry):

```json
{
  "mcpServers": {
    "astrolabi": {
      "type": "http",
      "url": "https://mcp.agentastrology.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

Facts for client authors:

- Transport is MCP Streamable HTTP: `POST /mcp` carries JSON-RPC, and
  the `Accept` header must list both `application/json` and
  `text/event-stream`.
- The server is stateless — no session id is issued or required, and
  responses to `POST` arrive as plain JSON, not an event stream.
- `x-api-key: YOUR_API_KEY` is accepted as an alternative to the
  `Authorization` header.
- Requests without a valid key return HTTP 401 with
  `{ "error": { "code": "invalid_api_key" } }`.

## No client — raw JSON-RPC

Autonomous agents can call tools with a single POST. No initialize
handshake or session is needed:

```sh
curl -s https://mcp.agentastrology.com/mcp \
  -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "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
        }
      }
    }
  }'
```

The response is one JSON object — `result.content[0].text` holds the
chart as JSON text and `result.structuredContent` holds the same data as
an object. For this input the Sun is Capricorn 10°48′ (longitude
280.814) — [`public-quickstart.md`](public-quickstart.md) reads the same
response field by field. To list all 29 tools and their schemas:

```sh
curl -s https://mcp.agentastrology.com/mcp \
  -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

## REST instead of MCP

The same tools are plain HTTP at `https://mcp.agentastrology.com`:
`POST /v1/tools/{slug}` to call one, `GET /v1/tools` to list them, and
`GET /v1/openapi.json` for the OpenAPI description.
[`public-quickstart.md`](public-quickstart.md) walks the same natal
chart over REST — start there rather than duplicating it here.

## Verify the connection

Ask your agent to cast a natal chart for 1990-01-01, 12:00, London. A
connected agent calls `astro_chart` and reports the Sun at Capricorn
10°48′. From a shell, the curl above is the same check. A 401 means the
key is missing or wrong; [`public-errors.md`](public-errors.md) has the
full code table.

## Rate limits

Free tier: 500 calls per month. Paid tier: 50,000 calls per month. Every
key currently runs at the paid tier while the service is in beta, so
plan against 50,000/month until pricing launches. Each MCP request —
including `tools/list` — draws one call from the quota. Over the limit
the server returns `429` with a reset time;
[`public-errors.md`](public-errors.md) explains the headers.

## Related

- [`public-quickstart.md`](public-quickstart.md) — worked calls with
  verified outputs in five minutes.
- [`public-errors.md`](public-errors.md) — the error envelope, error
  codes, and rate-limit semantics.