Connect to Agent Astrology

Connect to Agent Astrology

Agent Astrology is a hosted astrology API for AI agents: 29 tools with 125 methods covering chart computation, aspect analysis, moment calculations, event search, lookups, and SVG chart rendering. Agents connect over MCP (Claude Code, Claude Desktop) or plain HTTPS. This guide gets you connected with a key and verifies the connection with one call.

1. Get an API key

Keys are issued from your account:

1. Sign in at https://agentastrology.com/account.
2. Create a key and copy it.
3. Keep the key secret — it authorizes every call on your account.

Every key authenticates with the Authorization: Bearer <key> header (the x-api-key header is accepted as an alternative on REST calls). Keys are free during the beta and every key currently has full access to all 29 tools. You can create and revoke keys from the same account page at any time.

2. Connect Claude Code

From a terminal:

claude mcp add --transport http astrolabi https://mcp.agentastrology.com/mcp \
  --header "Authorization: Bearer <key>"

Replace <key> with your API key. Verify with:

claude mcp list

astrolabi should show as connected. Restart the Claude Code session if the newly added server is not picked up.

3. Connect Claude Desktop

Edit your Claude Desktop configuration (claude_desktop_config.json — the MCP configuration file for the desktop app):

{
  "mcpServers": {
    "astrolabi": {
      "url": "https://mcp.agentastrology.com/mcp",
      "headers": {
        "Authorization": "Bearer <key>"
      }
    }
  }
}

Restart Claude Desktop after saving. The astrolabi server should appear in your MCP tools list; enable it for chats where you want astrology tools.

4. Plain REST

The REST API lives at https://api.agentastrology.com:

• POST /v1/tools/{slug} — call one tool by slug.
• GET /v1/tools — list every tool and its methods.
• GET /v1/openapi.json — the OpenAPI description of the whole surface.

A minimal call from a shell:

curl -X POST https://api.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, "timezone": -3 }'

5. Verify the connection

The call above is also the verification call: a 200 response whose body contains a moon object means the key, the endpoint, and the connection are all working. A 401 means the key is missing or wrong; see the errors guide for the full code table.

6. Rate limits today

• Free tier: 500 calls per month.
• Paid tier: 50,000 calls per month.

All keys are currently issued at the paid tier with full access while the service is in beta, so plan against 50,000/month until pricing launches. When you exceed a limit the API returns 429 with a reset time; the errors guide explains the headers.

Related

• public-quickstart.md — first successful calls in five minutes.
• public-errors.md — the error envelope, error codes, and rate-limit semantics.