Hosted MCP
Hosted MCP
Connect FreeAstroAPI directly to AI tools through a hosted MCP server. You do not need to install a local server, run a script, or build anything first. Add one URL, add your API key, reconnect your AI tool, and it can start calling astrology endpoints as tools.
MCP Server URL
https://api.freeastroapi.com/mcp1. Add the server
In your AI app, create a new remote MCP server and paste the URL from this page.
2. Add your API key
Send your key as the x-api-key header. The MCP server uses the same key and limits as the normal API.
3. Start asking
Once connected, your AI can discover tools and call them directly instead of guessing astrology data.
Quick Setup
Name: FreeAstroAPI
Type: Remote / Hosted MCP server
URL: https://api.freeastroapi.com/mcp
Header:
x-api-key: YOUR_API_KEYWhat Your AI Gets
Lookup and utility tools
- City Search
- Moon Phase
- Moon Phase Timeline
- Ephemeris
- Daily horoscope endpoints
Chart and astrology tools
- Natal chart calculation
- Transits
- Western synastry
- Vedic chart endpoints
- Chinese BaZi endpoints
Authentication, billing, admin, webhooks, and account-management endpoints are intentionally excluded from MCP.
Good Prompts To Try
Authentication
| Field | Value | Notes |
|---|---|---|
| Header | x-api-key | Use the same API key you already use for REST requests. |
| Tier behavior | same as REST | MCP is included on every tier, but calls still count against your normal usage and RPS limits. |
| Transport | Streamable HTTP | Choose a remote or hosted MCP option in your AI tool. |
Advanced: Raw MCP Calls
Most users will never need this. It is here for advanced tools, testing, and debugging.
Initialize
curl -X POST "https://api.freeastroapi.com/mcp" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "initialize",
"params": {
"protocolVersion": "2025-03-26",
"capabilities": {},
"clientInfo": {
"name": "example-client",
"version": "1.0.0"
}
}
}'Call a Tool
curl -X POST "https://api.freeastroapi.com/mcp" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"name": "v2_geo_search",
"arguments": {
"q": "paris",
"limit": 3
}
}
}'Sample Response
{
"jsonrpc": "2.0",
"id": 2,
"result": {
"content": [
{
"type": "text",
"text": "{\n \"results\": [ ... ],\n \"count\": 3\n}"
}
],
"structuredContent": {
"results": [
{
"name": "Paris",
"country": "FR",
"lat": 48.85341,
"lng": 2.3488,
"timezone": "Europe/Paris",
"population": 2138551
}
],
"count": 1
},
"metadata": {
"status_code": 200,
"path": "/api/v2/geo/search",
"method": "GET"
}
}
}Troubleshooting
I only see “command” setup, not URL setup. That app expects a local stdio MCP server. Use an app that supports remote or hosted MCP.
The server connects but tools fail. Check that your API key is valid and has not expired. MCP uses the same key and limits as the normal API.
My AI says rate limited. MCP calls count exactly like direct API requests. Check Rate Limits.
I need coordinates first. Ask the AI to use City Search before requesting a natal, transit, or synastry chart. The AI can do that through MCP automatically.