MCP / LLM Integration

Overview

AstroMCP supports two common integration styles:

• MCP servers — connect from mcp-compatible clients (IDEs and agent hosts)
• HTTP + tool/function calling — define AstroMCP endpoints as tools for your model runtime

Our API returns structured JSON designed to be easy to validate, cache, and summarize.

• Function calling – Direct tool invocation from LLMs
• MCP (Model Context Protocol) – Native action support
• Stable schemas – predictable field names and enums

Why LLMs Need AstroMCP

Large language models struggle with precise astronomical calculations:

• Training data contains errors and inconsistencies
• Ephemeris calculations require specialized algorithms
• Timezone and calendar edge cases cause errors

AstroMCP solves this by providing a computation layer your LLM can call directly.

Function Calling Integration

OpenAI Function Calling

Define AstroMCP endpoints as tools:

const tools = [
  {
    type: "function",
    function: {
      name: "compute_natal_chart",
      description: "Compute an astrological natal chart for a given birth datetime and location",
      parameters: {
        type: "object",
        properties: {
          datetime: {
            type: "string",
            description: "Birth datetime in ISO 8601 format"
          },
          latitude: {
            type: "number",
            description: "Birth location latitude"
          },
          longitude: {
            type: "number",
            description: "Birth location longitude"
          },
          timezone: {
            type: "string",
            description: "IANA timezone identifier"
          }
        },
        required: ["datetime", "latitude", "longitude"]
      }
    }
  }
];

Tool Implementation

async function computeNatalChart({ datetime, latitude, longitude, timezone }) {
  const response = await fetch('https://api.astromcp.dev/charts/natal', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.ASTROMCP_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ datetime, latitude, longitude, timezone })
  });
  
  return response.json();
}

MCP Server Integration

The Dev astroMCP Workflow

AstroMCP can be exposed as an MCP server for direct agent integration using a five-step discovery and execution pattern:

1. Discover — Use dev.list_allowed to see available endpoints
2. Understand — Use dev.get_schema to fetch request/response shapes
3. Seed — Use dev.fetch_lab_preset to get pre-built payloads
4. Learn — Use dev.search_docs to find integration guidance
5. Execute — Use dev.call with your confirmed payload

This "test-first" approach reduces errors and token usage by eliminating guesswork.

Interactive Testing First

Before deploying with Dev astroMCP, test your payloads interactively in Astro Lab:

• Build requests visually in the Control Deck
• See results in the Canvas (studio, code, or LLM view)
• Copy the JSON payload to use with dev.call
• Compare formats with the Diff Lens to optimize for token usage

Practical Setup Guide

If you want a complete setup guide and full tool reference, see Dev astroMCP:

• /docs/dev-astromcp

MCP Server Definition

import { Server } from "@modelcontextprotocol/sdk/server";

const server = new Server({
  name: "astromcp",
  version: "1.0.0"
});

server.addTool({
  name: "natal_chart",
  description: "Compute a natal chart with Swiss Ephemeris precision",
  inputSchema: {
    type: "object",
    properties: {
      datetime: { type: "string" },
      latitude: { type: "number" },
      longitude: { type: "number" }
    },
    required: ["datetime", "latitude", "longitude"]
  },
  handler: async (input) => {
    // Call AstroMCP API
    const chart = await astroClient.charts.natal(input);
    return chart;
  }
});

Response Optimization

AstroMCP responses are structured for LLM consumption:

Compact Format

Request specific fields to reduce token usage:

{
  "datetime": "1990-06-15T14:30:00",
  "latitude": 40.7128,
  "longitude": -74.0060,
  "include": ["bodies", "houses"],
  "bodyFields": ["sign", "degree"]
}

Simplified Output

{
  "sun": { "sign": "gemini", "degree": 24.15 },
  "moon": { "sign": "scorpio", "degree": 8.42 },
  "ascendant": { "sign": "libra", "degree": 12.33 }
}

Best Practices

1. Cache Responses

Natal charts are immutable—cache them:

const chartCache = new Map();

async function getOrComputeChart(key, params) {
  if (chartCache.has(key)) {
    return chartCache.get(key);
  }
  
  const chart = await astroClient.charts.natal(params);
  chartCache.set(key, chart);
  return chart;
}

2. Provide Context to LLM

Include relevant chart data in the system prompt:

The user's natal chart shows:
- Sun in Gemini (24°15') in the 10th house
- Moon in Scorpio (8°42') in the 3rd house
- Ascendant in Libra (12°33')

Use this information when discussing their astrological profile.

3. Handle Errors Gracefully

try {
  const chart = await astroClient.charts.natal(params);
  return { success: true, chart };
} catch (error) {
  return {
    success: false,
    error: "Could not compute chart. Please verify the datetime and location."
  };
}

Example: Astrology Chatbot

async function handleUserMessage(message, userContext) {
  const response = await openai.chat.completions.create({
    model: "gpt-4",
    messages: [
      {
        role: "system",
        content: `You are an astrology assistant. Use the compute_natal_chart 
                  tool to get accurate chart data. Never guess planetary positions.`
      },
      { role: "user", content: message }
    ],
    tools: astroMCPTools,
    tool_choice: "auto"
  });
  
  // Handle tool calls
  if (response.choices[0].message.tool_calls) {
    const toolResults = await executeTools(response.choices[0].message.tool_calls);
    // Continue conversation with tool results...
  }
}

Coming Soon

• Official MCP Server Package – Drop-in MCP server for any Claude-compatible agent
• Streaming Responses – For large time series queries
• Webhook Events – Notify your agent of astronomical events