에이전트 설정

Last updated 2026년 11월 6일 Markdown으로 보기 에이전트 설정

**MCP (Model Context Protocol)**로 AstroWay API를 AI 에이전트에 연결하세요. 카탈로그는 두 가지 방식으로 제공되며, 둘 다 여러분의 aw_test_* / aw_live_* 키를 사용합니다:

Hosted (HTTP): https://mcp.astroway.info/mcp, 설치 불필요, Bearer 토큰으로 인증.
Stdio (npx): npx @astroway/mcp, 로컬 하위 프로세스, 환경 변수로 인증, 오프라인에서도 작동.

대시보드에서 무료 키를 받은 뒤 클라이언트를 선택하세요.

카탈로그 전체 대신 도메인 하나

843개 도구를 응답 하나에 담으면 3.4 MB가 되며, 에이전트는 하나를 고르기 전에 이를 모두 읽어야 합니다. 대부분의 클라이언트는 그보다 훨씬 전에 포기합니다.

https://mcp.astroway.info/mcp/<도메인>은 전체 대신 주제 하나만 제공합니다. 설정은 같고 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으로, 키 없이 반환합니다. 알 수 없는 도메인은 843개 전체를 조용히 반환하는 대신 실제 도메인 목록과 함께 404를 반환합니다.

키 없는 문서: `/mcp/docs`

에이전트의 첫 질문은 결코 “차트를 계산해 줘”가 아닙니다. “이 API는 무엇을 할 수 있고, 호출은 어떻게 생겼으며, 비용은 얼마인가”입니다. 이 세 가지 모두 키 없이 답할 수 있습니다. https://mcp.astroway.info/mcp/docs는 크레딧을 전혀 쓰지 않으므로 인증도 요구하지 않습니다.

도구	하는 일
`find_endpoint`	770개 작업 전체를 검색합니다. 각 작업의 메서드, URL, 크레딧 가격, 요금제, 필수 본문 필드, 참조 문서 링크를 반환합니다
`search_docs`	우크라이나어와 영어로 된 가이드 281페이지를 각 페이지의 섹션 목록과 함께 검색합니다
`read_doc`	페이지 하나를 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은 색인에 있는 페이지만 읽습니다. 다른 경로는 거부되며, 이때 외부로 요청이 나가지 않습니다.

응답 전체보다 적게 요청하기

모든 도구는 자체 파라미터 외에 두 파라미터를 받습니다: fields(data 기준 상대 경로를 쉼표로 구분한 목록)와 precision(소수점 이하 몇 자리를 남길지). 이들은 REST와 같은 API로 전달되며, 토큰 차이는 말뿐이 아닙니다.

MCP를 통한 출생 차트 호출	바이트
파라미터 없음, 21.09.2026 이전 방식	91 737
파라미터 없음, 현재	72 484
`precision: 2`	61 356
`fields: "planets.name,planets.longitude,houses.cusp"`와 `precision: 2`	1 182

2026-09-21 프로덕션에서 측정했습니다. 네 줄 모두 크레딧은 같습니다. 차이의 비용은 응답을 읽는 쪽이 치릅니다.

어떤 필드와도 일치하지 않은 경로는 _fields_unmatched로 되돌아옵니다. 아무것도 일치하지 않은 목록은 빈 응답이 아니라 목록이 담긴 400 FIELDS_UNKNOWN입니다. 두 파라미터의 전체 설명: API 규칙.

클라이언트 선택

Claude Desktop 설정 파일로 Hosted MCP

Claude Code CLI 명령 하나

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"

응답은 두 부분으로 되어 있습니다. 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
}

그러면 실행기는 다섯 줄이면 됩니다. executors에서 이름을 찾고, 모델의 인자를 JSON 본문으로 해당 경로에 자신의 X-Api-Key와 함께 보내고, 응답을 모델에 돌려줍니다. 어떤 도구에도 자격 증명이 들어 있지 않으므로 이 목록은 안전하게 캐시할 수 있습니다.

모델이 무엇을 볼지는 여러분이 정합니다. 기본값은 전체 카탈로그가 아니라 엄선한 26개 도구의 시작 세트입니다. OpenAI는 요청당 함수를 128개로 제한하며, 모델은 그 한계에 훨씬 못 미쳐서부터 선택을 잘 못하기 시작합니다. select=all, select=group:Vedic, select=paths:/chart,/synastry로 좁히거나 넓히고, q=로 내부를 필터링하고, limit=(최대 128)로 제한하세요. 조용히 사라지는 것은 없습니다. totalMatched와 notes가 범위 밖에 남은 것을 알려 줍니다. { name, description, input_schema }를 받으려면 format=anthropic을 추가하세요.

이 호출은 무료이며 크레딧을 쓰지 않습니다.

모델에 자신의 키 사용

저희가 텍스트를 생성하는 엔드포인트에서는 토큰 비용을 직접 낼 수 있습니다. 헤더 두 개, 둘 다 보내거나 둘 다 보내지 않습니다:

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 크레딧입니다. 저희는 여전히 차트를 계산하고, 프롬프트를 구성하고, 안전 장치를 실행합니다. 완성(completion)은 여러분이 구매한 것입니다.

여러분의 키는 어디에도 기록, 저장, 캐시되지 않습니다. 키는 헤더로 전달됩니다. 요청 본문은 캐시 키 두 개로 해시되며, 저희 요청 로그는 헤더를 전혀 기록하지 않기 때문입니다. 여러분의 키를 인용한 제공업체 오류는 저희 로그나 여러분의 응답에 들어가기 전에 가려집니다. 여러분의 키를 쓴 호출은 두 캐시를 양방향으로 모두 우회합니다. 저희가 만든 응답을 받지 않으며, 그 응답이 다른 누군가에게 전달되지도 않습니다.

헤더는 명세에 있습니다. 이 헤더를 받는 모든 경로는 /v1/openapi.json에 X-Provider, X-Provider-Key, X-Provider-Model을 선언합니다. 따라서 생성된 클라이언트는 다른 파라미터처럼 이를 연결하며, 이 페이지가 필요하지 않습니다. 헤더는 저희가 실제로 모델을 호출하는 곳에서만 선언됩니다. /chart로 보낼 수는 있지만 아무 일도 일어나지 않고 엔드포인트의 일반 가격을 내게 됩니다.