- Docs
- Build With Roxy
- MCP Setup
Remote MCP Server Setup
Roxy provides a Remote MCP server over Streamable HTTP. Point your agent at a URL, pass your API key, and every tool is auto-discovered. No local processes, no Docker, no self-hosting.
How to connect your AI agent to RoxyAPI MCP
Prerequisite: You need an API key. Get one instantly →
MCP Endpoint: https://roxyapi.com/mcp/astrology-api
Create or edit .vscode/mcp.json in your workspace:
{
"servers": {
"roxy-astrology-api": {
"type": "http",
"url": "https://roxyapi.com/mcp/astrology-api",
"headers": {
"X-API-Key": "your_api_key_here"
}
}
}
}Works with: GitHub Copilot (VS Code 1.102+), Cline, Continue, Roo Code. Reload VS Code after saving.
Add RoxyAPI MCP server via CLI (Claude Code 2.1.1+):
claude mcp add-json roxy-astrology-api '{"type":"http","url":"https://roxyapi.com/mcp/astrology-api","headers":{"X-API-Key":"your_api_key_here"}}'Add --scope user to make it available across all projects. Run claude mcp list to verify. Restart Claude Code after adding.
Edit your claude_desktop_config.json file:
{
"mcpServers": {
"roxy-astrology-api": {
"type": "http",
"url": "https://roxyapi.com/mcp/astrology-api",
"headers": {
"X-API-Key": "your_api_key_here"
}
}
}
}Config location: macOS: ~/Library/Application Support/Claude/claude_desktop_config.json | Windows: %APPDATA%\Claude\claude_desktop_config.json. Restart Claude Desktop after saving.
Connect via the Claude Messages API (beta):
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/astrology-api",
name: "roxy-astrology-api",
authorization_token: "your_api_key_here"
}],
tools: [{
type: "mcp_toolset",
mcp_server_name: "roxy-astrology-api"
}],
messages: [
{ role: "user", content: "Your prompt here" }
]
}, {
headers: { "anthropic-beta": "mcp-client-2025-11-20" }
});Pass your Roxy API key as authorization_token. No OAuth required. See Claude MCP Connector docs.
Use the OpenAI Agents SDK with MCPServerStreamableHttp:
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/astrology-api",
"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-agentsConnect using the MCP Python SDK with Streamable HTTP transport:
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/astrology-api",
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 mcpNote: RoxyAPI uses Streamable HTTP transport (POST). The Google ADK SseConnectionParams uses the older SSE transport (GET) which is not compatible. Use the MCP Python SDK directly as shown above, or call our REST API with Gemini function calling.
Use the official MCP SDK for your platform:
// TypeScript — npm install @modelcontextprotocol/sdk
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
const client = new Client({ name: 'my-app', version: '1.0.0' });
const transport = new StreamableHTTPClientTransport(
new URL('https://roxyapi.com/mcp/astrology-api'),
{ 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/astrology-api",
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())See MCP documentation.
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.
- Your AI agent connects to the MCP server URL
- It auto-discovers all available tools (endpoints) for that domain, including parameter schemas
- When a user asks a question, the agent picks the right tool and calls Roxy
- Roxy 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. Response time is under 50ms for most endpoints.
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. Roxy is a remote MCP server — 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 2025-11-25 (latest stable). 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-compatible platform works. Verified with OpenAI Agents, Gemini Agents SDK, VS Code, GitHub Copilot, Claude Desktop, Windsurf, Cline, and custom agent frameworks.
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 9. 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.
| Domain | MCP Server | Product page |
|---|---|---|
| Astrology | /mcp/astrology-api | View → |
| Vedic | /mcp/vedic-astrology-api | View → |
| Tarot | /mcp/tarot-api | View → |
| Numerology | /mcp/numerology-api | View → |
| Dreams | /mcp/dreams-api | View → |
| Angel Numbers | /mcp/angel-numbers-api | View → |
| I-Ching | /mcp/iching-api | View → |
| Crystals | /mcp/crystals-api | View → |
| Location | /mcp/location-api | View → |
All servers use the same authentication and Streamable HTTP transport. See pricing for plan details.
Build a multi-domain AI chatbot with MCP
Want all 9 domains in one chatbot? Insight AI Chatbot is a free, MIT-licensed starter 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 and ship in 30 minutes. Browse all free starter apps →
Frequently Asked Questions
What is MCP (Model Context Protocol)?
MCP is an open standard for connecting AI agents to external APIs. Instead of writing integration code or manually defining tool schemas, your AI agent connects to an MCP server and auto-discovers all available tools at runtime. RoxyAPI provides remote MCP servers for 9 domains including astrology, tarot, numerology, dreams, I-Ching, crystals, and angel numbers.
What is the difference between MCP and function calling?
Function calling requires you to manually define every tool schema in your code before the model can use it. MCP eliminates this step by letting the agent discover tools dynamically from a server. MCP is ideal when an API has many endpoints (RoxyAPI has 122+), because you connect once and get access to all tools without writing or maintaining definitions.
How do I connect my AI agent to the RoxyAPI MCP server?
Get an API key from roxyapi.com/pricing, then add the MCP server URL and your API key to your platform config. For Claude Desktop, add it to claude_desktop_config.json. For VS Code, add it to .vscode/mcp.json. For Claude Code, run the claude mcp add-json command. No local processes, Docker, or self-hosting required.
Which AI platforms support RoxyAPI MCP servers?
RoxyAPI MCP servers work with any MCP-compatible platform. Verified platforms include Claude Desktop, Claude Code, VS Code (GitHub Copilot), OpenAI Agents SDK, Google Gemini ADK, Windsurf, Cline, Continue, Roo Code, and custom agent frameworks using the MCP TypeScript or Python SDK.
Do MCP tool calls count against my API quota?
Yes, MCP tool calls count against your monthly request quota the same as REST API calls. Tool discovery (listing available endpoints) is free and does not count toward your quota. All subscription plans include access to all MCP servers across all 9 domains.
Is RoxyAPI MCP free to use?
MCP tool discovery (listing available tools) is always free. Tool calls use the same pricing as REST API calls and count toward your monthly quota. Every subscription plan includes full access to all 9 MCP servers at no extra cost. Visit roxyapi.com/pricing to see plans starting at $39/month.
Should I use MCP or the REST API?
Use MCP if you are building AI agents (Claude, OpenAI Agents, Gemini) that need to auto-discover tools at runtime. Use REST if you are building traditional apps (mobile, web, backend) where you control which endpoints to call. Both have the same response time, same pricing, and same data accuracy. MCP is simpler for AI agents; REST is simpler for custom business logic.
Can I use RoxyAPI MCP without writing code?
Yes. Platforms like Claude Desktop and VS Code handle the MCP connection via a JSON config file. Add the server URL and your API key, restart the application, and your AI agent can call all available tools immediately. No custom code, no Docker containers, no local processes required.