# Dify

Dify gives agents and workflows two ways to AstroWay. **MCP** pulls in ready tools with descriptions and schemas, so the agent needs nothing explained. **Swagger API** builds a tool from a small OpenAPI schema, for when you need one or two specific calls and full control over what the model sees.

## Way 1. Hosted MCP

### Which server to connect

The whole-catalogue server, https://mcp.astroway.info/mcp, carries 843 tools, and their descriptions together take 3.4 MB: too much to hand a model on every step. Connect a domain server for the task. The full list with descriptions is at [mcp.astroway.info/domains](https://mcp.astroway.info/domains), for example:

| Task | URL |
|---|---|
| Natal chart, horoscopes, Moon phase | `https://mcp.astroway.info/mcp/core` |
| Vedic astrology and Vastu | `https://mcp.astroway.info/mcp/vedic` |
| Tarot | `https://mcp.astroway.info/mcp/tarot` |
| Human Design | `https://mcp.astroway.info/mcp/human-design` |
| Documentation search, no key | `https://mcp.astroway.info/mcp/docs` |

### Connecting

1. **Integrations → Tools → MCP → Add MCP Server (HTTP)**.
2. **Server URL**: an address from the table, **Name**: `AstroWay core`, **Server Identifier**: `astroway-core`. Apps refer to the server by that identifier, so do not change it later.
3. Authentication, one of two options:
   - **OAuth (the default).** Leave **Dynamic Client Registration** on. Dify registers itself with our authorization server and opens an AstroWay sign-in window; calls are charged to the credits of the account that approved access.
   - **A key.** Turn Dynamic Client Registration off and under **Advanced Options → Custom Headers** add `Authorization` with the value `Bearer aw_live_...`. Use a **Server only** key: Dify calls from its own servers. The MCP server accepts a key only in `Authorization: Bearer`; an `X-Api-Key` header gets `401` here.
4. Save. Dify imports the tools, and in an agent or an Agent node you can pick just the ones you need, for example `astroway_western_chart` and `astroway_calendar_moon_phase`.

Every tool carries a `[Cost: ...]` line with its price in credits in its description, and the model sees it before the call. Tools marked Heavy or Premium are worth allowing only with the user's confirmation.

## Way 2. An HTTP tool from an OpenAPI schema

The full API specification is too big for a tool, so we made a minimal schema for two endpoints that spend no credits: today's horoscope for a sign and the Moon phase.

1. **Integrations → Tools → Swagger API → Create**.
2. Import the schema from `https://api.astroway.info/integrations/dify-astroway-openapi.json` or paste [its content](/integrations/dify-astroway-openapi.json). Dify shows two actions: `dailyHoroscope` and `moonPhase`.
3. In the tool's authorization pick an API Key in a header, header name `X-Api-Key`, the value your **Server only** key scoped to `public/horoscope/*` and `public/moon-phase`.
4. Test the `dailyHoroscope` action with `sign=leo`.

To add another endpoint, write it into the schema: its path and parameters are on the endpoint's page in the [API reference](/docs/api/). For a natal chart pass `?fields=` with the fields you need, or the model gets tens of kilobytes: `/v1/chart?fields=planets.name,planets.longitude,houses.ascendant` returns about half a kilobyte.

**Caution:**
A Free key on `/v1/public/*` counts against the same limit as a call with no key: 30 requests an hour per IP. Dify Cloud calls from addresses shared by many customers, so a tool on the public endpoints in Dify Cloud needs a paid-plan key or a self-hosted Dify. A wrong key gives no `401` here; it quietly gets the anonymous limit.

**Note:**
Checked on 2026-11-07 against production: the `/mcp/core` server accepted a key in `Authorization: Bearer` and ran `astroway_calendar_moon_phase`, answered `401` with `WWW-Authenticate` without sign-in, and `401` to a key in `X-Api-Key`; the OpenAPI schema passed validation, and both requests it describes returned `200`. The steps in the Dify interface follow its documentation and were not carried out in this check.