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

/plugin marketplace add RoxyAPI/agent-plugin
/plugin install roxyapi@roxyapi

claude mcp add-json roxy-docs '{"type":"http","url":"https://roxyapi.com/mcp/docs"}'

{
  "servers": {
    "roxy-docs": {
      "type": "http",
      "url": "https://roxyapi.com/mcp/docs"
    }
  }
}

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/docs",
    name: "roxy-docs"
  }],
  tools: [{
    type: "mcp_toolset",
    mcp_server_name: "roxy-docs"
  }],
  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/docs"
        }
    ) as server:
        agent = Agent(
            name="Assistant",
            instructions="Use RoxyAPI tools to answer questions",
            mcp_servers=[server]
        )
        result = await Runner.run(agent, "How do I authenticate and call the natal chart endpoint?")
        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/docs"
    ) 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(
                "search_docs",
                arguments={"query": "how do I generate a natal chart with the TypeScript SDK"}
            )
            print(result)

asyncio.run(main())

# pip install mcp

{
  "mcpServers": {
    "roxy-docs": {
      "serverUrl": "https://roxyapi.com/mcp/docs"
    }
  }
}

// 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/docs')
);
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/docs"
    ) 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-docs, find the natal chart endpoint and show me how to call it with the TypeScript SDK.

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.

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

Protocol

Remote MCP server using Streamable HTTP transport (POST). Implements MCP Specification 2026-07-28 (latest) and every earlier revision on the same URL: 2024-10-07, 2024-11-05, 2025-03-26, 2025-06-18, 2025-11-25. The earlier initialize handshake is the default, so existing configs need no change. A client gets 2026-07-28 by sending the MCP-Protocol-Version: 2026-07-28 header with the per-request _meta envelope, which the official SDKs do when version negotiation is on. On 2026-07-28 there is no handshake and no session: server/discover returns the supported revisions, capabilities and server identity in one call, and ping is gone from that revision. No local process, no stdio, no Docker, just an HTTPS endpoint. Tool schemas follow our OpenAPI 3.1 spec.

Authentication

Pass your API key via X-API-Key header, Authorization: Bearer token, or api_key query parameter. Claude Messages API uses authorization_token which maps to Bearer auth.

Billing

MCP tool calls count against your monthly request quota. Tool discovery (listing endpoints) is free.

Supported platforms

Any MCP client that sends a header works. Verified with Claude Desktop, Claude Code, Codex, Gemini CLI, Cursor, Windsurf, Cline, GitHub Copilot, Copilot Studio, Perplexity, Mistral Le Chat, Lovable, v0, Replit, n8n, Zapier, the OpenAI and Gemini agent SDKs, and custom agent frameworks. Hosted assistants that sign in without a header, such as claude.ai and ChatGPT, connect to the docs server today.

Testing

Test endpoints in your browser using the MCP Inspector. Set transport to "Streamable HTTP", add your endpoint URL and X-API-Key header.

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.

Frequently Asked Questions