Skip to content

MCP Integration

Welcome to the DestinyOracle Model Context Protocol (MCP) Integration guide. Build agents and clients that interface directly with astrological calculations and reasoning systems.

Hosted Endpoint

  • Production URL: https://destinyoracle.app/api/mcp/sse

SSE Transport

Hosted MCP is served using server-sent events (SSE) transport. Make sure your MCP client supports HTTP/SSE transports.

Authentication Contract

Send the Bearer key in the request headers. Hosted MCP uses the same developer key as REST.

Authorization: Bearer YOUR_API_KEY

API Key Header

Always send your API key in the Authorization header as Bearer YOUR_API_KEY. Do not append the key as a query string parameter.

Hosted MCP Tools

calculate_chart

Computes the complete 12-palace Zi Wei Dou Shu chart containing palace layout, star placements (major/minor), mutagens (化祿, 化權, 化科, 化忌), and current energy cycle periods.

  • Access Tier: Basic / Free (No charges).

Input Parameters (JSON Schema)

Parameter Type Required Description
birthDate string Yes Birth date in YYYY-MM-DD or DD/MM/YYYY format (e.g., 1995-10-15).
birthTime string Yes Birth time in HH:mm format (24-hour, e.g., 08:30 or 14:00).
gender enum Yes Biological gender: "male" or "female".
timezone string Yes Birth location IANA timezone (e.g., Asia/Taipei, America/New_York).
language enum No Language preference: "zh" or "en". Defaults to "en".

Response Format

Returns the chart as JSON text content. Palace-level branch and stem metadata plus several chart-level summary fields are intentionally omitted to keep the developer payload compact:

{
  "palaces": [
    {
      "id": 0,
      "name": {
        "en": "soul",
        "zh": "命宮"
      },
      "stars": [
        {
          "name": {
            "english": "emperor",
            "chinese": "紫微"
          },
          "type": "major",
          "brightness": "brightness_level",
          "mutagen": null
        }
      ],
      "description": "The soul palace represents your core personality, potential, and innate characteristics.",
      "oppositePalace": {
        "name": { "en": "surface", "zh": "遷移" },
        "stars": []
      },
      "ageRange": [2, 11]
    }
  ],
  "sign": {
    "zh": "天秤座",
    "en": "libra"
  }
}

analyze_destiny

Generates detailed fortune-telling analysis. If a premium DestinyOracle API key is provided and the account meets the premium balance floor, it returns deep AI-generated interpretations. Otherwise, it provides structured static interpretations and guidelines for basic local LLM analysis.

  • Access Tier: Hybrid (Basic offline static templates, or Premium hosted AI interpretations if billing/pricing balance floor is met).

Input Parameters (JSON Schema)

Parameter Type Required Description
birthDate string Yes Birth date in YYYY-MM-DD or DD/MM/YYYY format.
birthTime string Yes Birth time in HH:mm format.
gender enum Yes Biological gender: "male" or "female".
timezone string Yes Birth location IANA timezone.
palaces array Yes Array of palace names to analyze (e.g., ["soul", "career", "wealth"]). Use ["all"] to analyze everything.
language enum No Language preference: "zh" or "en". Defaults to "en".

Response Format (Premium Mode)

Returns the hosted MCP premium analysis response as JSON text content. The MCP analysis wrapper uses the top-level key analyses; the REST version of the same capability uses result.

{
  "success": true,
  "accessTier": "premium",
  "premiumAvailable": true,
  "analyses": {
    "soul": "Detailed professional interpretation paragraph..."
  },
  "traitInsights": {
    "soul": [
      {
        "key": "actionIndex",
        "name": "Action",
        "tooltip": "Behavioral momentum and execution power.",
        "score": 75,
        "tierLabel": "High",
        "description": "Action is high in this palace, making it a clear strength and a frequent behavioral tendency here."
      }
    ]
  },
  "billing": {
    "premium": true,
    "chargedUsd": 0.08,
    "chargedDisplayUsd": "$0.08",
    "reservedUsd": 0.08,
    "reservedDisplayUsd": "$0.08",
    "remainingBalanceUsd": 12.42,
    "remainingBalanceDisplayUsd": "$12.42",
    "pricingVersion": "developer-v1-2026-06-27"
  }
}

Response Format (Basic / Fallback Mode)

Returns explanatory text followed by serialized fallback data:

[Offline Mode / Free Tier] Below is the raw Zi Wei Dou Shu configuration and static interpretations for the requested palaces...

[
  {
    "palaceName": {
      "en": "soul",
      "zh": "命宮"
    },
    "stars": [
      {
        "name": { "english": "emperor", "chinese": "紫微" },
        "type": "major"
      }
    ],
    "staticDescription": "Static text detailing the traditional meaning of this palace."
  }
]

Premium Offline Fallback

If the request is authorized with a premium API key but falls back to offline mode (e.g. server timeout), the resulting palace objects will also contain a traitInsights property containing calculated metrics: json "traitInsights": [ { "key": "actionIndex", "name": "Action", "tooltip": "Behavioral momentum and execution power.", "score": 75, "tierLabel": "High", "description": "Action is high in this palace, making it a clear strength and a frequent behavioral tendency here." } ]

get_energy_metrics

Calculates the user's astrological energy metrics for a given year across 8 key dimensions (action, innovation, leadership, cooperation, affinity, learning, thinking, and tolerance), comparing innate capacity against the current year's fortune cycle.

  • Access Tier: Premium (Requires prepaid balance before execution begins).

Input Parameters (JSON Schema)

Parameter Type Required Description
birthDate string Yes Birth date in YYYY-MM-DD or DD/MM/YYYY format.
birthTime string Yes Birth time in HH:mm format.
gender enum Yes Biological gender: "male" or "female".
timezone string Yes Birth location IANA timezone.
targetYear integer No The 4-digit calendar year to query (e.g., 2026). Defaults to the current calendar year.

Response Format

Returns the hosted MCP response as JSON text content:

{
  "accessTier": "premium",
  "premiumAvailable": true,
  "result": {
    "targetYear": 2026,
    "metrics": [
      {
        "key": "actionIndex",
        "name": { "en": "Action", "zh": "行动力" },
        "innate": 78,
        "thisYear": 82,
        "variance": 4,
        "innateTier": "High",
        "thisYearTier": "Extreme High"
      }
    ]
  },
  "billing": {
    "premium": true,
    "chargedUsd": 0.04,
    "chargedDisplayUsd": "$0.04",
    "reservedUsd": 0.08,
    "reservedDisplayUsd": "$0.08",
    "remainingBalanceUsd": 12.38,
    "remainingBalanceDisplayUsd": "$12.38",
    "pricingVersion": "developer-v1-2026-06-27"
  }
}

Client Config Pattern

To connect your Claude Desktop or other MCP client, use the following configuration in your claude_desktop_config.json:

{
  "mcpServers": {
    "destinyoracle": {
      "transport": "http",
      "url": "https://destinyoracle.app/api/mcp/sse",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Session Behavior

Hosted MCP uses a stateless transport. After initialization, subsequent requests should continue the session with either:

  • mcp-session-id request header
  • sessionId query parameter

Most SDK-backed clients handle this automatically. If you are implementing a custom MCP client, persist the session ID returned during initialization and send it on follow-up requests.

Behavior Notes

  • calculate_chart is available as free/basic developer access.
  • analyze_destiny can return a basic fallback if the account does not meet the premium balance floor.
  • get_energy_metrics requires a premium balance before execution begins.
  • Hosted MCP and REST are limited to 10 calls per second per API key.

Premium Billing

Hosted premium requests reserve a conservative amount before premium execution begins. On success, the reservation is settled to the final charge and any unused reserved amount is released automatically. Failed premium requests are not billed. Cached premium responses remain billable.