エージェントの設定

MCP (Model Context Protocol) を通じて AstroWay API を AI エージェントに接続します。カタログは 2 つの方法で利用でき、どちらもお手持ちの aw_test_* / aw_live_* キーで動作します。

Hosted (HTTP): https://mcp.astroway.info/mcp。インストール不要で、Bearer トークンで認証します。
Stdio (npx): npx @astroway/mcp。ローカルのサブプロセスとして動き、環境変数で認証し、オフラインでも動作します。

ダッシュボードで無料のキーを取得し、続けてお使いのクライアントを選んでください。

カタログ全体ではなく 1 つのドメインを

783 個のツールを 1 つのレスポンスで返すと 2.9 MB になり、エージェントは 1 つを選ぶ前にそのすべてを読まなければなりません。ほとんどのクライアントはそのずっと手前で諦めます。

https://mcp.astroway.info/mcp/<ドメイン> はカタログ全体ではなく 1 つの分野だけを返します。設定は同じで、変わるのは URL だけです。

ドメイン	URL	ツール数	`tools/list` のサイズ
占星術コア	`/mcp/core`	104	389 KB
ヴェーダ	`/mcp/vedic`	192	970 KB
中国形而上学	`/mcp/chinese`	60	202 KB
ヘレニズムと伝統	`/mcp/hellenistic`	59	240 KB
タロット	`/mcp/tarot`	79	209 KB
数秘術	`/mcp/numerology`	64	158 KB
Human Design	`/mcp/human-design`	27	125 KB
予測	`/mcp/forecast`	43	209 KB
人間関係	`/mcp/relationships`	42	247 KB
心理占星術	`/mcp/psychological`	28	107 KB
占いと秘教	`/mcp/divination`	79	185 KB
応用リーディング	`/mcp/applied`	45	148 KB
レポート	`/mcp/reports`	42	209 KB
プラットフォーム	`/mcp/platform`	42	119 KB

2026-09-21 に本番環境で計測しました。/mcp は引き続きカタログ全体を返すため、以前に設定したものは何も壊れていません。残高の確認と呼び出しコストの見積もりはすべてのドメインに含まれています。ヴェーダ占星術に限定されたエージェントでも、呼び出しにいくらかかるかは知っておく必要があるからです。

GET /domains は同じ一覧を JSON で、キーなしで返します。存在しないドメインは、黙って 783 個すべてを返すのではなく、実在するドメインの一覧付きの 404 になります。

キー不要のドキュメント: `/mcp/docs`

エージェントの最初の質問は決して「チャートを計算して」ではありません。「この API は何ができるのか、呼び出しはどんな形か、いくらかかるのか」です。この 3 つにはキーなしで答えられます。https://mcp.astroway.info/mcp/docs はクレジットを一切消費しないため、認証も求めません。

ツール	内容
`find_endpoint`	770 件すべてのオペレーションから検索します。それぞれについてメソッド、URL、クレジット価格、プラン、必須のボディフィールド、リファレンスへのリンクを返します
`search_docs`	ウクライナ語と英語の 281 ページのガイドを、各ページのセクション一覧付きで検索します
`read_doc`	1 ページを markdown として返します
`list_docs`	セクションごとにまとめた索引全体です

770 件のオペレーションのうち 700 件に価格があり、さらに 37 件はキーなしで応答するものとして示されています。つまり、アカウントを作る前にシナリオのコストを計算できます。

curl https://mcp.astroway.info/mcp/docs \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"find_endpoint","arguments":{"query":"solar return","limit":2}}}'

read_doc が読むのは索引にあるページだけです。それ以外のパスは拒否され、その際に外部へのリクエストも発生しません。

レスポンス全体より少なく要求する

どのツールも、固有のパラメータに加えて 2 つのパラメータを受け付けます。fields (data からの相対パスをカンマ区切りで並べたもの) と precision (小数点以下を何桁残すか) です。これらは REST と同じ API に渡され、トークンの差は誇張ではありません。

MCP 経由の出生図の呼び出し	バイト数
パラメータなし、2026-09-21 以前	91 737
パラメータなし、現在	72 484
`precision: 2`	61 356
`fields: "planets.name,planets.longitude,houses.cusp"` と `precision: 2`	1 182

2026-09-21 に本番環境で計測しました。クレジットは 4 行すべてで同じです。差額を払うのはレスポンスを読む側です。

どのフィールドにも一致しなかったパスは _fields_unmatched で返されます。何も一致しなかった一覧は、空のレスポンスではなく、一覧付きの 400 FIELDS_UNKNOWN になります。両パラメータの詳しい説明: API の規約。

クライアントを選ぶ

Claude Desktop 設定ファイルで Hosted MCP

Claude Code CLI コマンド 1 つ

Cursor 設定ファイルで Hosted MCP

VS Code Copilot Chat、Agent mode

Windsurf Cascade MCP

Cline npx stdio パッケージ

Codex CLI npx stdio パッケージ

CI / raw HTTP

クライアントがまったくなくても、hosted エンドポイントは HTTP 上の JSON-RPC で通信します。Bearer トークンでツール一覧を取得する例:

curl https://mcp.astroway.info/mcp \
-H "Authorization: Bearer aw_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

MCP なしの Function calling

エージェントが MCP ではなく OpenAI や Anthropic の function calling で動いている場合は、API から既成のツール定義を取得してそのままモデルに渡してください。定義は OpenAPI ドキュメントから生成されるため、モデルが埋めるスキーマはエンドポイントが検証するスキーマと同じです。

curl "https://api.astroway.info/v1/agent/tools?format=openai" \
-H "X-Api-Key: aw_live_YOUR_KEY"

レスポンスは 2 つの部分に分かれています。tools はベンダーの契約に正確に従い、こちら独自のものは何も含まないため、そのままモデルの呼び出しに渡せます。ツールオブジェクト内に余分なキーがあると、ベンダー側で 400 になります。executors は各ツールの実行方法を示し、モデルが返すのと同じキーを持っています。

{
"tools": [
  { "type": "function", "function": { "name": "astroway_post_chart", "description": "Natal chart...",
    "parameters": { "type": "object", "required": ["date", "time", "latitude", "longitude"], "properties": { "...": {} } } } }
],
"executors": {
  "astroway_post_chart": { "method": "POST", "path": "/v1/chart", "credits": 20, "group": "Core" }
},
"count": 26, "totalMatched": 26, "totalAvailable": 751, "truncated": false
}

あとは実行側のコードが 5 行あれば済みます。executors で名前を探し、モデルの引数を JSON ボディとしてそのパスへ自分の X-Api-Key 付きで送り、レスポンスをモデルに返すだけです。どのツールにも認証情報は含まれないため、この一覧は安全にキャッシュできます。

モデルに何を見せるかはあなたが決めます。 デフォルトはカタログ全体ではなく、厳選した 26 ツールのスターターセットです。OpenAI はリクエストあたり 128 関数に制限しており、モデルの選択精度はその上限よりずっと手前で落ち始めます。select=all、select=group:Vedic、select=paths:/chart,/synastry で絞り込みや拡張を行い、q= で中身をフィルタし、limit= (最大 128) で上限を設けます。黙って消えるものはありません。totalMatched と notes が、範囲外に残ったものを示します。format=anthropic を付けると { name, description, input_schema } 形式で取得できます。

この呼び出しは無料で、クレジットを消費しません。

モデルに自分のキーを使う

テキストを生成するエンドポイントでは、トークン代をご自身で支払うことができます。ヘッダーは 2 つで、両方送るか、どちらも送らないかです。

curl https://api.astroway.info/v1/ai/explain-aspect \
-H "X-Api-Key: aw_live_YOUR_KEY" \
-H "X-Provider: anthropic" \
-H "X-Provider-Key: sk-ant-YOUR_PROVIDER_KEY" \
-H "Content-Type: application/json" \
-d '{"planet1":"Saturn","planet2":"Moon","aspectType":"Square"}'

X-Provider は openai、anthropic、google、groq、mistral、openrouter、deepseek、together のいずれかです。それぞれの接続先アドレスはこちら側で固定されており、リクエストから取られることはありません。X-Provider-Model は任意で、デフォルトのモデルを上書きします。

こちらのチェーンへのフォールバックはありません。 キーが機能しなかった場合は、こちらが費用を負担したレスポンスではなく、プロバイダーのステータスとメッセージが返ります。黙ってフォールバックすると、あなたが自分のものだと考えていたリクエストにこちらのトークンが使われ、しかもそれに気づく手段がありません。

この呼び出しはエンドポイントの価格ではなく 5 クレジットです。 チャートの計算、プロンプトの組み立て、安全チェックは引き続きこちらで行い、生成部分はあなたが購入した形になります。

あなたのキーはどこにもログされず、保存もキャッシュもされません。 リクエストボディは 2 つのキャッシュキーにハッシュされ、こちらのリクエストログはヘッダーを一切記録しないため、キーはヘッダーで送ります。プロバイダーのエラーがあなたのキーを引用していた場合、こちらのログやあなたへのレスポンスに入る前に伏せ字にされます。自分のキーを使った呼び出しは、両方のキャッシュを双方向でバイパスします。こちらが作ったレスポンスを受け取ることはなく、そのレスポンスが他の誰かに渡ることもありません。

ヘッダーは仕様に記載されています。 これらを受け付けるすべてのパスは /v1/openapi.json で X-Provider、X-Provider-Key、X-Provider-Model を宣言しているため、生成されたクライアントは他のパラメータと同じように扱え、このページを参照する必要はありません。宣言されているのは実際にモデルを呼び出す箇所だけです。/chart に送ることもできますが、何も起こらず、通常のエンドポイント価格が課金されます。

機械可読な仕様

REST API に直接接続したい、または独自のエージェントに仕様を読み込ませたい場合:

AGENTS.md: /AGENTS.md、エージェント向けの手引き (キーなしで呼び出せるもの、リクエストの契約、レスポンスのエンベロープ、制限ヘッダー)
OpenAPI: /v1/openapi.json
llms.txt: /llms.txt · 全文版 /llms-full.txt
Postman: /postman/astroway-api.json
SDK: TypeScript, Python, PHP