AGENT ASTROLOGY — DOCSagentastrology.com
Menu

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

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

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
{
  "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

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:

{
  "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

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

{
  "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):

{
  "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:

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 reads the same response field by field. To list all 29 tools and their schemas:

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 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 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 explains the headers.