kebab/docs/mcp-usage.md

MCP usage — agent integration guide

kebab mcp runs an MCP (Model Context Protocol) stdio JSON-RPC server. agent host (Claude Code / Cursor / OpenAI Agents / Copilot CLI 등) 가 본 binary 를 spawn 하여 KB 검색 / 답변 / ingest 를 호출.

shipped since v0.3.1 (fb-30). 6 tool 으로 확장 (v0.3.2, fb-31).

---

Quick start

binary 를 PATH 에 두고 (cargo install --path crates/kebab-cli 또는 release tarball), agent host 의 mcp config 에 등록:

{
  "mcpServers": {
    "kebab": {
      "command": "kebab",
      "args": ["mcp"]
    }
  }
}

session 시작 시 host 가 kebab mcp 를 spawn — process 가 session 동안 살아 있어 SQLite / Lance / fastembed 가 hot. 첫 tool call 만 cold-start 비용, 이후 sub-100ms.

--config 옵션 thread:

{
  "mcpServers": {
    "kebab": {
      "command": "kebab",
      "args": ["--config", "/Users/me/.config/kebab/agent.toml", "mcp"]
    }
  }
}

---

Host config 예시

Claude Code

~/.claude/mcp.json (또는 OS 별 동등 위치):

{
  "mcpServers": {
    "kebab": {
      "command": "kebab",
      "args": ["mcp"]
    }
  }
}

session 재시작 후 kebab server 가 tool list 에 등장. agent 가 mcp__kebab__search / mcp__kebab__ask 등 호출 가능.

Cursor

~/.cursor/mcp.json:

{
  "mcpServers": {
    "kebab": {
      "command": "kebab",
      "args": ["mcp"]
    }
  }
}

Cursor 의 Composer / Agent 모드에서 활성화.

OpenAI Agents (agents-sdk)

Python:

from openai_agents import Agent, MCPServerStdio

kebab = MCPServerStdio(
    name="kebab",
    params={"command": "kebab", "args": ["mcp"]},
)

agent = Agent(
    name="researcher",
    mcp_servers=[kebab],
)

Node:

import { Agent, MCPServerStdio } from "openai-agents";

const kebab = new MCPServerStdio({
  name: "kebab",
  params: { command: "kebab", args: ["mcp"] },
});

const agent = new Agent({ name: "researcher", mcpServers: [kebab] });

Copilot CLI

~/.config/copilot-cli/mcp.json (or wherever the CLI looks):

{
  "mcpServers": {
    "kebab": {
      "command": "kebab",
      "args": ["mcp"]
    }
  }
}

기타 host

stdio JSON-RPC MCP 표준을 따르는 모든 host 가 지원. 위 형식 (command + args) 만 맞추면 동작.

---

Tool catalog (6 tools)

모든 tool 의 출력은 wire schema v1 JSON 을 MCP text content block 으로 직렬화. CLI --json 모드와 byte-동일 (single source of truth).

search — corpus 검색

Input	{ "query": string, "mode"?: "lexical"|"vector"|"hybrid", "k"?: 1-100 }
Defaults	mode = "hybrid", k = 10
Output	search_hit.v1 array, ranked

예시:

{
  "name": "search",
  "arguments": {
    "query": "Kubernetes ingress controller setup",
    "mode": "hybrid",
    "k": 5
  }
}

응답 (한 hit 발췌):

[
  {
    "schema_version": "search_hit.v1",
    "rank": 1,
    "score": 0.847,
    "doc_id": "...",
    "chunk_id": "...",
    "doc_path": "k8s/ingress.md",
    "heading_path": ["Setup", "Ingress controller"],
    "snippet": "...",
    "citation": { ... }
  },
  ...
]

언제 사용: 사용자가 "문서 어디 있는지" 묻거나, agent 가 답변 전 raw chunk 가 필요할 때.

ask — RAG 답변

Input	{ "query": string, "mode"?: "lexical"|"vector"|"hybrid" }
Defaults	mode = "hybrid"
Output	answer.v1 (single object)

예시:

{
  "name": "ask",
  "arguments": {
    "query": "What's our internal Kubernetes ingress setup?"
  }
}

응답:

{
  "schema_version": "answer.v1",
  "answer": "...",
  "citations": [ ... ],
  "grounded": true,
  "refusal_reason": null,
  "model": { ... }
}

grounded: false 처리: KB 에 충분한 context 없음. refusal_reason 확인 후 사용자에게 "KB 에 정보 없음" 으로 안내, 본인 지식 fallback 또는 source 요청. paraphrase 하면 안 됨 (hallucination 위험).

schema — capability discovery

Input	{} (no args)
Output	schema.v1

예시:

{ "name": "schema", "arguments": {} }

응답:

{
  "schema_version": "schema.v1",
  "kebab_version": "0.3.2",
  "wire": { "schemas": ["answer.v1", "search_hit.v1", ...] },
  "capabilities": {
    "json_mode": true,
    "rag_multi_turn": false,
    "mcp_server": true,
    "streaming_ask": false,
    ...
  },
  "models": { "parser_version": "...", "embedding_version": "...", ... },
  "stats": { "doc_count": 128, "chunk_count": 2147, "asset_count": 130, ... }
}

언제 사용: session 시작 시 한 번 — feature gate 결정 (capabilities.streaming_ask true 면 streaming 사용 등). cheap call (no LLM, no embedder), session 동안 1 회 충분.

doctor — health check

Input	{} (no args)
Output	doctor.v1

예시:

{ "name": "doctor", "arguments": {} }

응답:

{
  "schema_version": "doctor.v1",
  "ok": true,
  "checks": [
    { "name": "config_loaded", "ok": true, "detail": "..." },
    { "name": "ollama_reachable", "ok": true, "detail": "..." },
    ...
  ]
}

언제 사용: 다른 tool 이 실패하거나 비정상 응답 줄 때 first triage. ok: false 면 checks[] 의 failed entry 가 원인 — 사용자에게 보고 후 stop (자동 retry 금지).

ingest_file — 단일 파일 저장 (mutation)

Input	{ "path": string }
Supported ext	.md / .pdf / .png / .jpg / .jpeg (unsupported extension error 그 외)
Output	ingest_report.v1 (single asset)

예시:

{
  "name": "ingest_file",
  "arguments": { "path": "/Users/me/Downloads/article.md" }
}

응답:

{
  "schema_version": "ingest_report.v1",
  "scanned": 1,
  "new": 1,
  "updated": 0,
  "unchanged": 0,
  "skipped": 0,
  "errors": 0,
  ...
}

언제 사용: 사용자가 disk 의 file 을 KB 에 저장 의향 명시 시. workspace 외부 path OK — 파일은 <workspace.root>/_external/<hash12>.<ext> 으로 copy. 동일 content 재 ingest 면 idempotent (unchanged: 1).

주의: mutation tool — 사용자 명시 의도 없을 때 자동 호출 금지.

ingest_stdin — stdin markdown 저장 (mutation)

Input	{ "content": string, "title": string, "source_uri"?: string }
v1 scope	markdown only
Output	ingest_report.v1 (single asset)

예시:

{
  "name": "ingest_stdin",
  "arguments": {
    "content": "## Article body\n\nMain text here.",
    "title": "Article X",
    "source_uri": "https://example.com/x"
  }
}

응답:

{
  "schema_version": "ingest_report.v1",
  "scanned": 1,
  "new": 1,
  ...
}

언제 사용: agent 가 web fetch 한 markdown article 을 KB 에 저장. 사용자가 "이거 나중에 또 보고 싶어" 명시 시 또는 multi-turn 대화에서 자료 누적. content 가 이미 frontmatter (--- 시작) 이면 error — ingest_file 사용.

title + source_uri 가 frontmatter 로 자동 prepend → Document.metadata 에 저장 → 후속 search 결과의 doc_meta 에 포함. agent 가 source URL 추적 가능.

주의: mutation tool. 같은 content 무한 ingest 안 함 (idempotent 보장이지만 embedding cost 낭비).

---

Troubleshooting

isError: true + error.v1 content

tool dispatch 가 Err 반환 시. content 의 error.v1 JSON 의 code 로 분기:

code	의미	조치
config_invalid	--config path missing / TOML parse 실패	path 확인 + kebab schema 로 검증. details.path + details.cause 확인.
not_indexed	kebab.sqlite 미존재 / migration 미실행	사용자에게 kebab init + kebab ingest 실행 안내. retry 자동 금지.
model_unreachable	Ollama endpoint 연결 실패	Ollama 실행 확인 (ollama serve). details.endpoint 의 host 가 reachable 한지. retry 1-2 회 후 사용자 보고.
model_not_pulled	Ollama model not found	사용자에게 ollama pull <model> 안내 — details.model 표시.
timeout	LLM stream / embed deadline 초과	일시적이면 retry 1 회. 재발 시 사용자 보고 (model 응답 느림 / Ollama load).
io_error	filesystem / 권한 / disk full	details.kind 보고 사용자에게 disk space / permission 확인 안내.
generic	catch-all	details.chain (verbose 시) 보고 사용자에게 그대로 전달. retry 금지.

hint field 가 있으면 사용자에게 그대로 보여주기 (각 code 의 가장 빠른 조치).

grounded: false (ask refusal)

isError: false (정상 응답). KB 에 충분한 context 없음. refusal_reason 확인 후:

• NoChunks — 검색 자체가 0 hit. 다른 표현 / 더 일반적인 query 시도.
• LowScores — hit 있지만 score gate 미달. kebab search (별도) 로 raw hit 확인.
• 그 외 — refusal 메시지 그대로 사용자에게 보고.

자동 paraphrase 금지. 사용자에게 "KB 에 정보 없음" 명시 후 본인 지식 또는 source 요청.

doctor ok: false

다른 tool 호출 전 doctor 부터. checks[] 의 failed entry 원인 명시 — 사용자에게 보고 후 stop.

empty search result

isError: false, content = [] (빈 array). KB 에 매칭 없음. mode 변경 (lexical → vector or vice versa) 또는 query 표현 다양화. 그래도 빈 결과면 KB coverage 부족 — 사용자에게 보고.

tool not found

tools/list 에서 본 binary 의 6 tool 확인. 0.3.1 (fb-30) 은 4 tool, 0.3.2 (fb-31) 부터 6. binary version 확인:

{ "name": "schema", "arguments": {} }

응답의 kebab_version 이 0.3.2+ 인지 확인.

---

Performance

• 첫 tool call: cold start ~1-2s (SQLite open + Lance dataset open + fastembed model load).
• 이후 tool call (same session): hot — search ~50-200ms, ask ~수 초 (Ollama LLM dominant).
• session 종료 (host 가 process kill): 모든 cache lost. 다음 session 첫 call 다시 cold.
• schema / doctor: cheap (no LLM / no embedder), 매 call ~ms.
• ingest_file / ingest_stdin: 첫 call 시 fastembed cold start. 이후 file 당 ~수 백 ms (parse + chunk + embed).

cold-start 회피하려면 host 가 long-running session 유지 (Claude Code default).

---

Security

• stdio MCP — 외부 네트워크 노출 없음. agent host 만 access.
• kebab mcp 가 호출하는 facade 는 --config 의 권한으로 동작. config 내 secret (Ollama API key 등) 은 process 환경에 한정.
• mutation tool (ingest_file / ingest_stdin) 는 사용자 명시 의도 없이 자동 호출 금지 — agent 측 가드.

---

Related

• CLI usage: kebab --help + README.md
• Wire schemas: docs/wire-schema/v1/*.schema.json
• design contract: docs/superpowers/specs/2026-04-27-kebab-final-form-design.md §10.2
• Claude Code 전용 skill: integrations/claude-code/kebab/SKILL.md
• HOTFIXES (post-merge deviations): tasks/HOTFIXES.md