# Dify astrology chatbot, MCP and OpenAPI tool setup

> Give a [Dify](https://dify.ai/) agent, chatflow, or workflow live access to astrology, forecasting, human design, numerology, tarot, I Ching, dreams and 18+ insight domains, in about ten minutes and with no backend of your own.

Dify has three ways to reach an outside API, and for RoxyAPI they are not equal. Connect our Remote MCP servers and the tools arrive already named, typed and updatable. Use an HTTP Request node when you want exactly one endpoint. Import the OpenAPI schema only when you want a fixed tool surface, and read the server URL note before you do.

## Give the agent the truth sources

Whatever path you pick, put this in the system prompt of the LLM or Agent node so the model stops guessing at endpoints and fields:

```
RoxyAPI is one REST API for astrology, Vedic astrology, forecasting, human design, numerology, tarot and 18+ insight domains. Base URL https://roxyapi.com/api/v2, auth is the X-API-Key header.

Where the truth lives, in this order:
1. The docs MCP server at https://roxyapi.com/mcp/docs. Streamable HTTP, no key, one tool: search_docs.
2. https://roxyapi.com/AGENTS.md. Auth rules, the location-first rule, request body shapes, the error contract, field formats, domain gotchas.
3. The OpenAPI spec, one per domain at https://roxyapi.com/api/v2/{domain}/openapi.json, where the paths are relative to the domain.
4. No MCP available? https://roxyapi.com/llms.txt.

Every chart, horoscope, panchang, dasha and compatibility call needs latitude, longitude and timezone. Resolve them with the location search tool first and pass its timezone through. Never ask a person for coordinates.
A 200 is clean JSON with no wrapper. Errors are { error, code }, and a 400 carries issues[] with every field problem at once.
```

You can also add `https://roxyapi.com/mcp/docs` as a tool in its own right, using the MCP steps below with no authentication, so the model looks up an endpoint mid-conversation instead of being told about it.

## Path 1, Remote MCP: the whole domain as tools

The best fit for an agent that picks its own endpoint. Every operation in a domain arrives as a named tool with its parameters already described, and you can refresh the list later without touching a schema.

1. Open **Integrations**, **Tools**, and pick the **MCP** tool type.
2. Add a server with its **URL**, a **name**, and a unique **server identifier**.
   ```
   https://roxyapi.com/mcp/astrology
   ```
3. Under **Advanced Options**, **Custom Headers**, add `X-API-Key` with your key from [your account](/account). Our servers authenticate with that static header rather than OAuth, so there is no sign-in step.
4. Add the tools to an Agent app, or to an Agent node inside a workflow.

One server per domain, all on the same key:

```
https://roxyapi.com/mcp/{domain}
```

`astrology`, `vedic-astrology`, `forecast`, `human-design`, `chinese-astrology`, `feng-shui`, `mesoamerican-astrology`, `vastu`, `numerology`, `kabbalah`, `tarot`, `biorhythm`, `ayurveda`, `iching`, `crystals`, `dreams`, `angel-numbers`, `location`.

**Tip: Start with two or three domains plus `location`, not all of them. Every connected tool is a definition in front of the model on every turn, and a smaller surface means fewer wrong picks, especially on smaller models. Full setup notes are in the [Remote MCP guide](/docs/mcp).**

**Warning: Apps reference an MCP server by its identifier. Change the identifier later and the tools stop working in every app that used the old one, so pick it once. The same applies when you move an exported app to another workspace: recreate the servers there with matching identifiers.**

## Path 2, HTTP Request node: one endpoint, no tools

Right when the workflow already knows what it needs, such as a daily horoscope or a Life Path lookup.

1. In **Studio**, click `+` between nodes and pick **HTTP Request**.
2. Set the **Method** and **URL**, for example `GET https://roxyapi.com/api/v2/astrology/horoscope/aries/daily`.
3. Under **Authentication**, choose **API Key**, then the **Custom** subtype. Header name `X-API-Key`, value your key.

**Warning: The single most common failure here is leaving the subtype on **Bearer**. RoxyAPI uses `X-API-Key` as its own header, not `Authorization: Bearer`. A 401 with `code: "api_key_required"` means the subtype, nine times out of ten.**

Store the key as an **environment variable** of the secret type rather than typing it into the node. Secret values are masked in workflow run logs and in the request log of the node, and they stay out of the app DSL when you export or share it.

Variables interpolate anywhere in the node: `{{sign}}` inside a URL, a JSON body value, or a header. Deep access works too, so a later node can read `{{api_response.data.items[0].id}}`.

## Path 3, Swagger API: import the schema

Dify calls this tool type **Swagger API**. Open **Integrations**, **Tools**, pick **Swagger API**, and fill the **Schema** field by pasting the specification, importing it from a URL, or starting from the provided example. Dify generates one tool per operation and keeps our `operationId` as the tool name, so a tool reads as `generateNatalChart` rather than a mangled path.

One edit is required before it will call anything:

**Warning: **Set an absolute server URL.** Our per-domain specs ship a relative server (`/api/v2`) with paths relative to the domain, because each spec is served beside the API it describes. Dify joins `servers[0].url` to each path as plain text and does not resolve a relative base, so the request would have no host. In the Schema field, replace the `servers` block with the absolute base for that domain:**

```json
"servers": [{ "url": "https://roxyapi.com/api/v2/astrology" }]
```

Then `POST /natal-chart` resolves to `https://roxyapi.com/api/v2/astrology/natal-chart`, which is the URL you can curl. Import Path 1 instead and none of this applies.

Finish with **Authentication Method**, **API Key**, header name `X-API-Key`, and your key.

Import one domain at a time. The combined spec at `https://roxyapi.com/api/v2/openapi.json` is 259+ endpoints, which is far more tool surface than any model should carry.

## Worked example: an AI tarot reader

Start node captures a question, HTTP Request draws the spread, the LLM node reads all three cards together instead of one at a time.

1. **Start** node, input `question`.
2. **HTTP Request** node: `POST https://roxyapi.com/api/v2/tarot/spreads/three-card`, JSON body `{"question": "{{question}}"}`, authentication **API Key, Custom, X-API-Key**.
3. **LLM** node, with the three positions bound by name.
4. **Answer** node returns the reading.

The response carries `spread`, `question`, `seed`, `summary` and `positions`, and each entry in `positions` has `position`, `name`, `interpretation` and a `card` object with `id`, `name`, `arcana`, `suit`, `keywords`, `meaning`, `reversed` and `imageUrl`. So a prompt binds `{{api.positions[0].card.name}}` and `{{api.positions[0].interpretation}}` and nothing has to be invented.

```bash
curl -X POST "https://roxyapi.com/api/v2/tarot/spreads/three-card" \
  -H "X-API-Key: $ROXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question": "What should I focus on this quarter?"}'
```

Pass `seed` to make a reading reproducible, and `?lang=` for any of the ten languages.

## Anything with a birth chart needs a place first

Every chart, panchang, dasha, compatibility and synastry call needs `latitude`, `longitude` and `timezone`. `GET /location/search?q={city}` returns `{ total, limit, offset, cities }`, each city carrying `city`, `province`, `country`, `iso2`, `latitude`, `longitude`, `timezone` and `utcOffset`.

Wire it as the node before any chart node, or connect `https://roxyapi.com/mcp/location` so the agent resolves the city itself. `timezone` takes an IANA name such as `"Europe/London"`, resolved server side to the daylight-saving-correct offset for that date, or decimal hours such as `5.5`.

## Gotchas

- **Backend only key.** A Dify workspace runs server side, so the key is safe in a secret environment variable or a tool credential. It must never appear in a prompt that gets logged or travels inside an exported DSL.
- **Custom, not Bearer.** The `X-API-Key` header is a custom header. This is the single most common integration failure on Dify.
- **Tool surface discipline.** Give an agent the domains the conversation actually needs. Every extra tool is a definition the model reads on every turn and one more thing it can pick wrongly.
- **Rate limits.** An agent that reaches for a tool on every turn eats a month of quota in hours. Add a decision node that only calls RoxyAPI when the question is on topic.
- **Billing.** Listing tools costs nothing. Every tool call and every HTTP Request is one billable RoxyAPI request.
- **Prefer IANA timezones.** A decimal offset knows nothing about daylight saving; an IANA name resolves correctly for the birth date.
- **Refreshing an MCP tool list can break an app** if a tool it used was removed or renamed upstream. Re-add the tool in each affected app.

## What to build next

- **Domain guides**, for which endpoints to call in what order:
  - [Western Astrology](/docs/guides/astrology), [Vedic Astrology](/docs/guides/vedic-astrology), [KP Astrology](/docs/guides/kp), [Forecast](/docs/guides/forecast), [Human Design](/docs/guides/human-design), [Chinese Astrology](/docs/guides/chinese-astrology), [Feng Shui](/docs/guides/feng-shui), [Mesoamerican Astrology](/docs/guides/mesoamerican-astrology), [Vastu](/docs/guides/vastu), [Numerology](/docs/guides/numerology), [Kabbalah](/docs/guides/kabbalah), [Tarot](/docs/guides/tarot), [Biorhythm](/docs/guides/biorhythm), [Ayurveda](/docs/guides/ayurveda), [I Ching](/docs/guides/iching), [Crystals](/docs/guides/crystals), [Dreams](/docs/guides/dreams), [Angel Numbers](/docs/guides/angel-numbers)
- [Remote MCP](/docs/mcp): the full server reference, including which client speaks which transport.
- [AI chat widgets](/docs/tutorials/ai-chat-widgets): turn a tool result into a drawn chart or spread in a chat interface you control.
- [AI prompts](/docs/prompts): whole-app prompts when you outgrow a workflow and want a real app around it.
- [API reference](/api-reference): the human playground, where you can try any endpoint in the browser.