Grok MCP — 에이전트 스킬 참조
이 파일을 사용하여 어떤 도구를 호출할지, 어떤 모델을 사용할지, 언제 Grok을 호출하지 말아야 할지 결정하십시오.
기본 모델은 없습니다 — 모든 호출에 model을 전달하고 의도적으로 선택해야 합니다:
작업을 수행할 수 있는 가장 저렴한 모델을 선택하고, 품질이 부족할 때만 더 높은 모델로 올라가십시오.
Grok MCP를 사용해야 하는 경우 vs. 직접 처리해야 하는 경우
| 작업 | Grok MCP 사용 | 직접 처리 |
|---|---|---|
| 사용자가 Grok을 명시적으로 요청함 | ✅ 항상 요청을 수락 | — |
| 이미지 생성 또는 편집 | ✅ 항상 | ✗ 대부분의 모델은 이미지를 생성할 수 없음 |
| 로컬 파일 이미지 분석 | ✅ agent(model=..., image_paths=[...]) | ✗ 파일이 디스크에 있어야 함 |
| 대규모 코드베이스 분석(>200K 토큰) | ✅ agent(model=<large-context>, tools=["read"]) | ✗ 컨텍스트 제한 |
| Grok의 답변과 비교 | ✅ 둘 다 호출 | ✅ 둘 다 호출 |
| 일반 텍스트/추론(요청 없음) | ✗ 불필요한 비용 | ✅ 선호 |
| 코드 생성(요청 없음) | ✗ 현재 모델을 사용할 수 없는 경우 제외 | ✅ 선호 |
기본 규칙: 먼저 직접 처리하십시오. Grok을 사용해야 하는 경우:
- 사용자가 Grok을 명시적으로 요청함 (예: "ask Grok", "use Grok", "generate with Grok")
- 현재 모델이 작업을 수행할 수 없음 (이미지 생성, 로컬 파일 비전, 컨텍스트 소진)
- 사용자가 Grok의 답변과 비교를 요청함
모델 선택 — 모든 호출에서 직접 결정
Grok 모델을 실행하는 모든 도구(agent, 질문이 있는 read, shell, search, generate_image*)는 model이 필요합니다. 역할, 기본값, auto 라우터는 없습니다. 누락되거나 알 수 없는 모델은 유효한 선택 목록과 함께 즉시 실패합니다.
선택 사항의 출처: 각 도구의 설명에는 현재 xAI 카탈로그(id, 컨텍스트 창, 1M 토큰당 가격(일반 및 캐시됨) 및 이미지 입력을 허용하는 모델의 [images])가 나열됩니다. 이 목록은 서버 시작 시 라이브 xAI API에서 채워집니다. list_models(refresh=true)는 카탈로그를 다시 가져와 변경 사항을 보고하고 도구 설명을 갱신합니다. 메모리에서 모델 이름이나 가격을 하드코딩하지 말고 목록을 읽으십시오.
역할 태그. 서버는 라이브 카탈로그에서 모델을 표시하며 이름으로 표시하지 않습니다. 따라서 아래 정책은 모델 교체에도 유효합니다: cheapest (최저 가격), flagship (최신 세대, 가장 깊고 비쌈), code (코드에 특화). 태그와 표시된 가격으로 선택하십시오.
기본 정책 — 저렴하게 시작하고, 증거가 있을 때만 상향:
- 일상 작업 (질문, 요약, 추출, 분류, 코드 편집, 파일 검토) →
cheapest모델, 모델이 허용하는 경우reasoning_effort="low". - 저렴한 실행의 답변이 명백히 불충분하거나, 작업이 여러 파일에 걸친 심층 다단계 분석인 경우에만
flagship으로 상향. "안전을 위해"가 아님. - 길거나 도구가 많은 실행:
tools=["read"]+ 지정된 파일,background=True, 아래 추정에서 선택한 명시적max_cost_usd— 서버 기본값에 의존하지 마십시오. - 결과 읽기:
cost_usd,stopped및hint.hint는 실행이 조기 종료되었거나 플래그십에서 비용이 많이 들었음을 의미합니다 — 동일한 호출을 다시 실행하는 대신 따르십시오 (가장 저렴한 모델에서 재시도, 작업 축소).
| 필요 | 선택 |
|---|---|
| 입력이 ~200K 토큰보다 큼 | 컨텍스트 창에 맞는 모델 — ctx 확인 |
| 이미지 입력 | [images] 표시된 모델 |
| 이미지 생성 | 가장 저렴한 이미지 모델에서 반복, 최종 렌더링은 품질 모델에서 |
비용 게이트 — 모든 agent() / read / shell / search 호출에 필수
1. 먼저 추정하고 말하십시오. 호출 전에 사용자에게 한 줄을 작성하십시오:
추정: ~<N>K 입력 토큰, ~<R> 라운드, <model> → ~$<X>. 아주 작은 단일 호출(짧은 질문)의 경우 한 구절로 충분합니다 ("~2K 토큰, <$0.01"). 도구 설명의 가격으로 계산하십시오 (메모리에서 계산하지 마십시오):
- 단일 샷(
tools없음):input_tokens × in-price + expected_output × out-price(1 토큰 ≈ 4자; 추론 토큰은 출력으로 청구됨). - 도구 루프: 매 라운드마다 전체 대화를 재전송하므로 비용은 라운드에 따라 증가합니다.
rounds × average_context × cached-price에 새 토큰과 각 라운드의 출력을 더하십시오. 이 세션의 과거cost_usd값이 가장 좋은 보정 기준입니다 — 이론보다 선호하십시오. - 확실하지 않습니까? 상한을 사용하십시오: 어차피
max_cost_usd로 전달할 값입니다.
2. $2 이상이면 사용자의 승인이 필요합니다. 추정이 $2를 초과하면 아직 호출하지 마십시오: 추정, 모델 및 저렴한 실행보다 얻을 수 있는 이점을 표시하고 명시적 승인을 기다리십시오. 승인은 해당 작업에만 적용되며 이후 작업에는 적용되지 않습니다. $2 이하이면 묻지 않고 진행하십시오.
3. 항상 max_cost_usd를 전달하십시오: 추정 + 약 30% 여유, $2로 제한되며 사용자가 더 많이 승인하지 않은 경우 (그렇다면 승인된 최대 금액). 서버의 GROK_MAX_COST_USD(기본값 $2.5)는 상한선이지 예산이 아닙니다: 더 높은 max_cost_usd는 이 값으로 제한되므로 더 많은 비용이 필요한 실행은 분할하거나 운영자가 상한선을 높여야 합니다.
4. 항상 작업이 사용한 비용을 보고하십시오. 완료된 모든 호출 후 — get_job으로 수집한 백그라운드 작업 포함 — 사용자에게 다음을 알리십시오: 모델, cost_usd 및 토큰(prompt / cached / completion / reasoning), 추가로 iterations 및 stopped. 비용이 아주 적더라도, 실행이 실패했거나 조기 종료된 경우에도 수행하십시오. 아직 running 상태인 작업은 비용이 없습니다 — 그렇게 말한 다음 수집될 때 보고하십시오. 실제 비용이 추정치를 약 50% 이상 초과한 경우에도 그렇게 말하십시오.
reasoning_effort (low/medium/high, 일부 모델은 none도 가능)는 호출당 설정되며 API에 전달됩니다. 모델에 따라 지원이 다릅니다 (카탈로그에는 명시되지 않음): 일부는 거부하고, 다른 일부는 none을 거부합니다. 설정하지 않으면 flagship 모델은 자체 (비싼) 기본값 대신 low로 실행되고, 다른 모델은 자체 기본값을 사용합니다. 모델이 매개변수를 거부하면 서버는 모델의 기본값을 삭제합니다. 깊이가 중요할 때 명시적으로 설정하십시오 (high) — 명시적 값은 항상 그대로 전송되며, 거부 시 API 오류로 반환됩니다.
| 작업 | 모델 |
|---|---|
| 빠른 질문, 요약, 추출, 분류 | 목록에서 가장 저렴한 모델 |
| 코드 생성 / 리팩토링 | 목록에 있는 코드 모델, 없으면 저렴한 일반 모델 |
| 심층 분석, 다단계 추론, 여러 파일 검토 | 최신 플래그십 (가장 높은 버전) |
| 입력이 ~200K 토큰보다 큼 | 컨텍스트 창에 맞는 모델 — ctx 확인 |
| 이미지 입력 | [images] 표시된 모델 |
| 이미지 생성 | 가장 저렴한 이미지 모델에서 반복, 최종 렌더링은 품질 모델에서 |
도구 → 모델 빠른 참조
agent(prompt, model, tools?, image_paths?, system?, conversation?, file_paths?, reasoning_effort?, max_iterations?, max_seconds?, max_cost_usd?, background=False)
텍스트(및 이미지)를 Grok에 보내는 하나의 도구입니다.
| 매개변수 | 기본값 | 참고 |
|---|---|---|
model | 필수 | 모델 선택 참조 |
tools | [] | Grok이 직접 호출할 수 있는 작업 공간 도구: read, write, shell, fetch, search. 알 수 없는 이름 → 즉시 오류 |
image_paths | — | 프롬프트와 함께 전송되는 로컬 이미지 (모델은 [images]여야 함); 서버에서 볼 수 있어야 함 — 경로 참조 |
max_iterations | 100 | 도구 루프의 모델 라운드 (서버 상한 — 낮출 수만 있음) |
max_seconds | 1800 | 실행의 벽시계 예산 (서버 상한) |
max_cost_usd | 2.5 | 실행의 추정 USD 예산 (서버 상한 — 더 높은 값은 제한됨) |
conversation | — (상태 비저장) | 작업 이름 "<프로젝트>/<작업>", 예: "grok-mcp/security-audit" — 하나의 작업 호출 간에 컨텍스트 유지; Grok은 필요 시 기록을 가져옴(get_recent_history/search_history). 새 작업 → 새 이름; 일회성 호출 → 생략 (기록 저장 안 함; 백그라운드 작업은 며칠 동안 결과 유지). 프로젝트 접두사가 중요합니다: HTTP를 통해 서버는 프로젝트를 구분할 수 없습니다. ≤ 200자, 제어 문자 없음 |
file_paths | — | 서버 측에서 주입된 파일 내용 (파일을 직접 선택) |
reasoning_effort | flagship에서는 low, 그 외 모델 기본값 | 호출당; 명시적 값은 그대로 전송됨 |
background | False | 즉시 {job_id} 반환; get_job(job_id)로 수집. 긴 실행에 필수는 아님 — 제한 참조 |
알 수 없는 매개변수는 거부되며 유효한 매개변수 목록이 반환됩니다.
반환 (예쁜 JSON):
{
"answer": "...",
"model": "grok-4.3",
"reasoning_effort": "low",
"tokens": {"prompt": 6909, "cached": 576, "completion": 49, "reasoning": 141},
"cost_usd": 0.0085,
"tool_calls": [{"tool": "read", "args": {"path": "README.md"}, "result_chars": 22463}],
"iterations": 2,
"stopped": "answer",
"hint": "실행이 조기 종료되었거나 플래그십에서 비용이 많이 들었을 때만 표시됩니다"
}
stopped는 루프가 종료된 방식을 나타냅니다: answer (정상), max_iterations, context (창이 거의 가득 참), loop (동일한 도구 호출 반복), time (max_seconds) 또는 cost (max_cost_usd). 모든 경우에 마지막 라운드는 도구 없이 실행되므로 answer는 항상 Grok이 수집한 내용에서 결론을 내린 내용을 포함합니다 — 작업은 절대 폐기되지 않습니다.
제한 (서버 환경 변수, 기본값)
| 제한 | 기본값 | 환경 변수 | 발생 상황 |
|---|---|---|---|
| 포그라운드 호출 지속 시간 | 60 초 | GROK_FOREGROUND_TIMEOUT | 호출이 백그라운드로 이동: {job_id, status: "running", note} 반환 — get_job으로 수집. 손실 없음; 클라이언트 시간 초과가 발생하지 않음 |
| 실행 지속 시간 | 1800 초 | GROK_JOB_MAX_SECONDS / max_seconds | 최종 답변, stopped: "time" |
| 실행 비용 | $2.5 | GROK_MAX_COST_USD / max_cost_usd | 최종 답변, stopped: "cost" |
| 모델 라운드 | 100 | GROK_MAX_ITERATIONS / max_iterations | 최종 답변, stopped: "max_iterations" |
| 입력 (프롬프트 + file_paths + 이미지) | 모델 창의 60% | GROK_INPUT_MAX_RATIO | API 호출 전에 거부, 창에 맞는 모델 이름 제시 |
| 하나의 도구 결과 | 창의 15% | GROK_TOOL_RESULT_MAX_RATIO | Grok이 "결과가 너무 큼 — 줄 범위나 grep을 읽으십시오"를 대신 받음 |
| 전체 대화 | 창의 80% | GROK_CONTEXT_MAX_RATIO | 오래된 결과가 한 번 정리된 후 새 결과가 거부되고, 그 다음 stopped: "context" |
| 셸 명령 | 240 초 | GROK_SHELL_TIMEOUT | 명령 종료, 오류가 Grok에 반환됨 |
경로
Docker 설정에서 서버는 마운트된 디렉토리(작업 공간 및 ASSETS_DIR)만 볼 수 있습니다: image_paths, file_paths 및 Grok이 읽는 경로는 여기에 있어야 합니다 — 호스트 /tmp 또는 스크래치패드 경로는 보이지 않습니다. 먼저 파일을 작업 공간에 복사하십시오. stdio 서버는 GROK_READ_ALLOWED_PATHS가 설정된 경우 사용자가 볼 수 있는 것을 제한된 상태로 봅니다. 서버가 볼 수 없는 경로는 보이는 루트 목록과 함께 즉시 거부됩니다.
자동 프로젝트 컨텍스트: 서버가 git 프로젝트 내에서 실행될 때(stdio),
agent()는 감지된 언어와 프레임워크를 시스템 프롬프트 앞에 추가합니다. Docker 설정에서는 아무것도 주입되지 않습니다.system이 이미[Project Context]로 시작하면 주입이 건너뜁니다.
Grok이 자체 컨텍스트를 수집하도록 하십시오. 파일을 직접 읽어 프롬프트에 붙여넣지 마십시오 — tools=["read"]를 전달하고 (git log/grep/테스트 실행을 위해 shell 추가) 무엇을 볼지 설명하십시오. 그러면 파일 내용이 컨텍스트에 들어가지 않습니다.
agent(prompt="src/grok_mcp/tools/agent.py 및 chat.py에서 중복된 로직을 검토하십시오.",
model="<목록에서 플래그십>", tools=["read", "shell"])
읽기 범위를 지정하십시오. 프롬프트에서 파일(또는 좁은 디렉토리) 이름을 지정하십시오 — 전체 저장소에서 "필요한 것은 무엇이든 읽으십시오"는 실행이 1.7M 토큰에 도달하는 방법입니다. 대용량 파일의 경우 shell grep -n으로 코드를 찾고 줄 범위만 읽도록 Grok에 지시하십시오 (read에 offset/limit 사용).
이미 정확히 어떤 파일이 중요한지 알고 있다면 file_paths를 대신 사용하십시오 (한 번의 왕복, 루프 없음).
긴 실행 및 비용. 각 라운드는 전체 대화를 재전송합니다. xAI는 자동으로 변경되지 않은 접두사를 캐시합니다(tokens.cached, 약 75% 저렴하게 청구됨). 따라서 라운드는 대부분 새 내용에 대해서만 비용을 지불합니다. 오래된 결과를 정리하면 한 번의 캐시 미스가 발생합니다. 세 번째 동일한 도구 호출은 거부됩니다. 다섯 번째는 루프를 종료합니다. 긴 호출은 60초 후에 {job_id}로 반환됩니다 — 그런 다음 get_job을 폴링하십시오. background=True는 그 첫 1분의 대기만 건너뜁니다.
이미지. agent(prompt="이 스크린샷에 무엇이 표시됩니까?", model=..., image_paths=["<작업공간>/shot.png"]) — 파일은 서버가 볼 수 있는 디렉토리에 있어야 합니다 (경로 참조). 호출당 하나의 특정 질문을 하십시오. 이미지를 코드와 비교해야 하는 경우 tools와 결합하십시오.
generate_image(prompt, output_path, model, aspect_ratio?, resolution?, ref_image_paths?)
model은 필수입니다 — 도구 설명에는 이미지 모델과 이미지당 가격이 나열됩니다.
비용 규율:
- 가장 저렴한 이미지 모델로 프롬프트가 올바를 때까지 반복한 다음 최종 렌더링에만 고품질 모델로 전환하십시오.
{path, model, prompt, format}을 반환합니다.
output_path는 절대 경로여야 합니다. 상위 디렉토리는 자동으로 생성됩니다.
참조 이미지 사용 시 (품질 계층 모델이 스타일을 더 잘 전송함):
- 기존 이미지와 스타일 일관성이 중요할 때
ref_image_paths를 전달하십시오. 최대 3개의 절대 경로를 순서대로 사용합니다 — 프롬프트는 위치적으로 이를 참조할 수 있습니다(예: "첫 번째에서 기하학, 두 번째에서 가장자리 캐릭터"). 전달하는 모든 경로는 전달됩니다. 아무것도 자동으로 삭제되지 않습니다. - 모델당 상한(현재 이미지 모델의 경우 3)은 xAI에 의해 적용되며, 초과 시 해당 메시지가 그대로 표시됩니다.
- 참조 파일은 매직 바이트에서 MIME 유형이 감지되므로 이전 결과를 저장된 확장자와 관계없이 참조로 다시 입력할 수 있습니다.
aspect_ratio(기본값"1:1") 및resolution(기본값"1k","2k"도 가능)은 참조 없이 적용됩니다. 출력은 참조 이미지의 비율을 상속하지 않습니다 — 16:10 참조는 명시적으로 지정하지 않으면 여전히 정사각형을 생성하므로 1k 정사각형 이상이 필요할 때마다 둘 다 명시적으로 전달하십시오.
비용 비교: 현재 모델 vs. Grok
현재 모델의 정확한 가격에 대해서는 제공업체의 현재 요금표를 확인하십시오.
...