Astrology MCP server for 18 insight domains

Two kinds of MCP server

A coding agent wants the Docs server to write the integration. A runtime agent wants a domain server to compute a real chart. Both are hosted by us and both speak Streamable HTTP.

How to connect your AI agent to RoxyAPI MCP

{
  "servers": {
    "roxy-dreams": {
      "type": "http",
      "url": "https://roxyapi.com/mcp/dreams",
      "headers": {
        "X-API-Key": "your_api_key_here"
      }
    }
  }
}

claude mcp add-json roxy-dreams '{"type":"http","url":"https://roxyapi.com/mcp/dreams","headers":{"X-API-Key":"your_api_key_here"}}'

{
  "mcpServers": {
    "roxy-dreams": {
      "command": "npx",
      "args": ["-y", "@roxyapi/mcp"],
      "env": {
        "ROXY_API_KEY": "your_api_key_here",
        "ROXY_MCP_DOMAINS": "dreams"
      }
    }
  }
}

import Anthropic from "@anthropic-ai/sdk";

const anthropic = new Anthropic();

const response = await anthropic.beta.messages.create({
  model: "claude-sonnet-4-20250514",
  max_tokens: 1024,
  mcp_servers: [{
    type: "url",
    url: "https://roxyapi.com/mcp/dreams",
    name: "roxy-dreams",
    authorization_token: "your_api_key_here"
  }],
  tools: [{
    type: "mcp_toolset",
    mcp_server_name: "roxy-dreams"
  }],
  messages: [
    { role: "user", content: "Your prompt here" }
  ]
}, {
  headers: { "anthropic-beta": "mcp-client-2025-11-20" }
});

import asyncio
from agents import Agent, Runner
from agents.mcp import MCPServerStreamableHttp

async def main():
    async with MCPServerStreamableHttp(
        name="RoxyAPI",
        params={
            "url": "https://roxyapi.com/mcp/dreams",
            "headers": {"X-API-Key": "your_api_key_here"}
        }
    ) as server:
        agent = Agent(
            name="Assistant",
            instructions="Use RoxyAPI tools to answer questions",
            mcp_servers=[server]
        )
        result = await Runner.run(agent, "Get today's horoscope for Aries")
        print(result.final_output)

asyncio.run(main())

# pip install openai-agents

import asyncio
from mcp import ClientSession
from mcp.client.streamable_http import streamable_http_client

async def main():
    async with streamable_http_client(
        "https://roxyapi.com/mcp/dreams",
        headers={"X-API-Key": "your_api_key_here"}
    ) as (read_stream, write_stream, _):
        async with ClientSession(read_stream, write_stream) as session:
            await session.initialize()

            # Discover all available tools
            tools = await session.list_tools()
            print(f"Available tools: {[t.name for t in tools.tools]}")

            # Call a tool
            result = await session.call_tool(
                "post_astrology_natal_chart",
                arguments={
                    "date": "1990-06-15",
                    "time": "14:30",
                    "latitude": 40.7128,
                    "longitude": -74.0060
                }
            )
            print(result)

asyncio.run(main())

# pip install mcp

{
  "mcpServers": {
    "roxy-dreams": {
      "serverUrl": "https://roxyapi.com/mcp/dreams",
      "headers": {
        "X-API-Key": "your_api_key_here"
      }
    }
  }
}

// TypeScript: npm install @modelcontextprotocol/client
import { Client, StreamableHTTPClientTransport } from '@modelcontextprotocol/client';

// 'auto' probes server/discover and lands on 2026-07-28; omit it for the 2025 handshake
const client = new Client(
  { name: 'my-app', version: '1.0.0' },
  { versionNegotiation: { mode: 'auto' } }
);
const transport = new StreamableHTTPClientTransport(
  new URL('https://roxyapi.com/mcp/dreams'),
  { requestInit: { headers: { 'X-API-Key': 'your_api_key_here' } } }
);
await client.connect(transport);
const tools = await client.listTools();

// Python: pip install mcp
import asyncio
from mcp import ClientSession
from mcp.client.streamable_http import streamable_http_client

async def main():
    async with streamable_http_client(
        "https://roxyapi.com/mcp/dreams",
        headers={"X-API-Key": "your_api_key_here"}
    ) as (read_stream, write_stream, _):
        async with ClientSession(read_stream, write_stream) as session:
            await session.initialize()
            tools = await session.list_tools()
            print([t.name for t in tools.tools])

asyncio.run(main())

Using roxy-dreams, interpret a dream about flying over open water.

Connect from hosted automation platforms and bots

The IDE configs above run on your own machine. For hosted automation platforms and messaging bots, the same Streamable HTTP MCP server is reachable over the public URL. Each platform has its own MCP node form or HTTP request step. The dedicated integration guides walk through the exact setup with the right URL field, header field, and API key placement.

The MCP URL and X-API-Key from the snippets above are the same values every guide uses. If your platform is not listed, the Custom tab above shows the raw MCP SDK calls any client can adapt.

Clients that only run local servers (stdio)

Some MCP clients can only launch a local process. For those, the open source astrology-mcp-server package runs over stdio and relays every call to the hosted servers: the same tools, the same answers and the same billing, with no local calculation to keep current. List the domains you want in ROXY_MCP_DOMAINS, comma separated.

{
  "mcpServers": {
    "roxyapi": {
      "command": "npx",
      "args": ["-y", "@roxyapi/mcp"],
      "env": {
        "ROXY_API_KEY": "your_api_key_here",
        "ROXY_MCP_DOMAINS": "astrology,vedic-astrology,tarot"
      }
    }
  }
}

Claude Desktop users can install it in one click instead: download the desktop extension, double-click it and paste your key. Any client that accepts a URL should use the hosted server above instead.

How AI agents discover and call MCP tools

When your AI agent connects to a RoxyAPI MCP server, it sends a tools/list request and receives the full catalog of available tools with typed input schemas, field descriptions, and enum values. Tool discovery is free and does not count toward your quota. The agent then selects the right tool based on user intent, calls it with structured parameters, and receives computed data to interpret into a natural language response.

1. Your AI agent connects to the MCP server URL
2. It auto-discovers all available tools (endpoints) for that domain, including parameter schemas
3. When a user asks a question, the agent picks the right tool and calls RoxyAPI
4. RoxyAPI computes the answer, the agent interprets it into a natural response

Every reading is backed by real astronomical calculations verified against NASA JPL Horizons, not hallucinated data.

Cut agent token cost with compact responses

Every tool on every RoxyAPI MCP server takes one optional argument: compact. Set it to true and the same data comes back in a token-optimized shape: whitespace removed, and arrays of same-shaped objects encoded columnar so each field name is sent once, not once per row. The encoding is lossless. No field is dropped, no value changes, and the round trip is verifiable.

Fewer response tokens means lower inference cost for the calling agent. It is requested per call, in the tool arguments:

{
  "method": "tools/call",
  "params": {
    "name": "get_astrology_signs",
    "arguments": { "compact": true }
  }
}

Nothing sets this automatically. The calling model includes compact when your agent instructions ask for it, and a programmatic client (MCP SDK, n8n, a custom agent) sets it directly in the arguments as shown. It defaults to off, so existing clients keep their current response shape until they ask, and it never touches your bill: one tool call is still one request, compact or not.

What is MCP?

Model Context Protocol is an open standard for connecting AI agents to external APIs. Instead of writing integration code, your agent discovers what tools are available and calls them based on user questions. Think of it as API documentation for AI.

MCP servers come in two forms: local (stdio), where you run a process on your own machine, and remote (Streamable HTTP), where the server is hosted for you. RoxyAPI is a remote MCP server with no infrastructure to manage, no containers to run, no dependencies to install. Just a URL and an API key.

MCP server protocol and authentication

Available MCP servers and tool counts

Each domain has its own MCP server with dedicated tools. Connect to one domain or all 18. Every subscription plan includes access to all servers at no extra cost. Tool counts reflect the number of callable operations per domain, from birth chart generation to tarot spreads to dream symbol lookups.

All servers use the same authentication and Streamable HTTP transport. See pricing for plan details.

curl -X POST https://roxyapi.com/mcp/astrology \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' \
  | jq -r '.result.tools[].name'

Build a multi-domain AI chatbot with MCP

Want all 18 domains in one chatbot? Free Astrology AI Chatbot is a MIT-licensed app that does tarot readings, astrology charts, numerology, dream interpretation, and more. It connects to multiple MCP servers simultaneously, auto-discovers tools across all domains, and supports Gemini, Claude, and GPT. A single user question like "compare my birth chart with a tarot reading" triggers calls across two domains automatically. Clone it, add your key, and ship. Browse all free templates →

Can the agent draw the chart, not just describe it?

Yes, in any chat UI you build. The model never draws anything: it calls a RoxyAPI tool, and the tool result is the same JSON the UI components already take, so your interface maps the tool name to the component with componentForTool and sets data, and a natal chart wheel, a kundli or a tarot spread renders beside the reply. Every component decodes the compact tool result itself, the model needs no component names and no UI instructions, and the same four lines work for the Vercel AI SDK and for the Anthropic, OpenAI, and Gemini connectors. Inside a hosted assistant such as Claude Desktop or ChatGPT the reply stays text today. Walkthrough: AI chat widgets.

AGENTS.md for AI coding agents

MCP is the runtime surface where Claude, GPT, and Cursor call RoxyAPI tools. AGENTS.md is the build-time surface where coding agents write the code that wires the rest of your app to those tools. Different file, different audience.

RoxyAPI publishes a tight playbook at https://roxyapi.com/AGENTS.md (imperative, blind-agent friendly) covering authentication, base URL, error contract, rate limits, idempotency, and the right endpoint for common tasks. It is the 2026 cross-tool standard read by Cursor, Codex, Windsurf, Aider, Claude Code, Gemini CLI, Zed, Warp, and RooCode. The same file ships inside @roxyapi/sdk, roxy-sdk, roxyapi/sdk, RoxyApi.Sdk, and github.com/RoxyAPI/sdk-go, so your coding agent picks it up the moment you install the SDK in any of the five languages.