AI 에이전트가 MCP 도구를 사용할 때 소비하는 토큰을 최대 98%까지 절감합니다 — 아무것도 잃지 않으면서요.
서버 | 도구 수 | 이전 | 이후 | 감소율 |
filesystem (Anthropic) | 14 | 1,892 tok | 236 tok | −88% |
sequential-thinking | 1 | 926 tok | 20 tok | −98% |
Google Calendar | 5 | 5,010 tok | 660 tok | −87% |
Enterprise (Cal + Gmail + Drive) | 12 | 8,649 tok | 882 tok | −90% |
sample_app.js (JavaScript) | — | 799 tok | 284 tok | −64.5% |
sample_app.ts (TypeScript) | — | 378 tok | 266 tok | −29.6% |
ast_extractor.py (Python) | — | 3,633 tok | 890 tok | −75.5% |
전송되는 토큰이 적어지면 API 비용이 낮아지고 응답 속도가 빨라집니다. 그리고 아무것도 잃지 않습니다. 모든 검사에서 압축 후에도 도구가 100% 사용 가능함을 확인했습니다.
직접 재현해 보세요 — 모든 입력은 저장소에 정적 픽스처로 있으며, 토큰은 tiktoken cl100k_base로 계산했습니다:
python benchmarks/run_benchmark.py # the table above
python benchmarks/run_benchmark.py --json # machine-readable
python benchmarks/run_benchmark.py --fixture path/to/your_schemas.jsonRelated MCP server: Bifrost-MCP Gateway
한 줄 설치 (macOS / Linux) — 패키지를 설치하고 Claude Desktop을 구성합니다:
curl -sSL https://raw.githubusercontent.com/LoudiliMed/Refract/main/install-refract.sh | sh인터넷에서 셸로 스크립트를 파이핑하는 것은 먼저 빠르게 확인해 보세요: GitHub에서 install-refract.sh 검사. sudo를 사용하지 않습니다.
또는 pip로 직접 설치:
pip install refract-mcp선택적 추가 기능:
pip install refract-mcp[semantic] # semantic tool routing with embeddings
pip install refract-mcp[multilang] # JavaScript, TypeScript, JSX, TSX support에이전트와 MCP 서버 사이에 위치합니다. 도구 스키마를 실시간으로 압축하여 에이전트가 매 요청마다 전체 카탈로그를 로드하지 않도록 합니다.
로컬 서브프로세스 (stdio):
refract-proxy --target "npx @modelcontextprotocol/server-filesystem /tmp" --verbose원격 HTTP/SSE 서버:
# --url implies SSE transport (explicit, recommended for remote endpoints)
refract-proxy --url https://my-mcp-server.com/sse
# or with --transport flag (auto-detection can be overridden)
refract-proxy --target https://my-mcp-server.com/sse --transport sse프록시 플래그:
플래그 | 기본값 | 설명 |
| 필수 | MCP 대상: stdio 명령어, HTTP URL 또는 JSON 파일 |
| — | stdio 명령어용 |
| — | 원격 SSE/HTTP 엔드포인트 — |
| 자동 | 대상으로의 전송 방식 강제: |
| 30 | SSE 대상 연결 타임아웃 (3회 재시도) |
| stdio | 프록시가 에이전트에 서비스를 제공하는 방식 |
| 8080 |
|
| 꺼짐 | 요청당 토큰 수 출력 |
| WARNING | DEBUG / INFO / WARNING / ERROR |
Claude Desktop에 추가:
{
"mcpServers": {
"my-server-via-refract": {
"command": "/path/to/refract-proxy",
"args": [
"--target",
"npx @modelcontextprotocol/server-filesystem /path/to/folder",
"--verbose"
]
}
}
}원격 MCP 서버(SSE)의 경우:
{
"mcpServers": {
"remote-via-refract": {
"command": "/path/to/refract-proxy",
"args": ["--url", "https://my-mcp-server.com/sse"]
}
}
}항목을 하나씩 편집하거나 서버마다 refract-install을 실행하는 대신, refract-wrap-all은 claude_desktop_config.json에 있는 모든 stdio 서버를 단일 명령어로 refract-proxy를 통해 실행되도록 다시 작성합니다:
# Preview what would change — writes nothing
refract-wrap-all --dry-run
# Wrap every stdio server not already going through refract
refract-wrap-all
# Restore the original commands
refract-wrap-all --unwrap예: 이 항목이
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["@modelcontextprotocol/server-filesystem", "/tmp"],
"env": {"MY_VAR": "1"}
}
}
}다음과 같이 바뀝니다
{
"mcpServers": {
"filesystem": {
"command": "/path/to/refract-proxy",
"args": ["--stdio-cmd", "npx @modelcontextprotocol/server-filesystem /tmp"],
"env": {"MY_VAR": "1"}
}
}
}보장 사항:
설정 파일의 백업은 매 쓰기 전에 생성됩니다 (claude_desktop_config.json.bak, 그 다음 .bak2, .bak3… — 기존 백업은 절대 덮어쓰지 않습니다).
env, cwd 및 기타 서버 필드는 보존됩니다.
이미 refract-proxy 또는 refract-server를 통해 실행 중인 서버는 건너뜁니다 (already wrapped).
원격 SSE/HTTP 서버(url 항목)는 건너뜁니다 — stdio 서버만 래핑됩니다.
--unwrap은 정확한 왕복입니다: 래핑 후 언래핑하면 모든 원래 명령어, 인수 및 필드가 복원됩니다.
플래그 | 값 | 설명 |
| Streamable HTTP | 현재 표준 (MCP 사양 2025-03-26). 원격 MCP 서버와 함께 사용. |
| SSE | 레거시 전송 방식, 호환성을 위해 유지. 서버가 Streamable HTTP를 지원하지 않는 경우 사용. |
| stdio 서브프로세스 | 로컬 명령어 ( |
(생략) | 자동 감지 |
|
sse와 http 모두 --target에 HTTP(S) URL이 필요합니다.
# Connect to a remote MCP server via Streamable HTTP (recommended)
refract-proxy --target "https://my-mcp-server.com/mcp" --transport http
# Connect via SSE (legacy)
refract-proxy --target "https://my-mcp-server.com/sse" --transport sse
# Local subprocess (auto-detected, --transport stdio optional)
refract-proxy --target "npx @modelcontextprotocol/server-filesystem /tmp"코드베이스를 MCP 서버로 노출합니다. 에이전트가 저장소를 인덱싱하고, 압축된 파일 컨텍스트를 가져오고, 특정 함수를 확장하고, 영향을 분석하고, 변경 사항을 감지하고, 보안 위험을 매핑할 수 있습니다.
refract-server --root /path/to/your/repoClaude Desktop에 추가:
{
"mcpServers": {
"refract-code": {
"command": "/path/to/refract-server",
"args": ["--root", "/path/to/your/repo"]
}
}
}50권의 책이 있는 도서관을 상상해 보세요.
Refract 없이: 에이전트는 모든 질문에 대해 50권의 책에 대한 상세 요약을 받습니다. 답변에 단 한 권만 필요하더라도 말이죠.
Refract와 함께: 에이전트는 먼저 제목 목록(색인)을 받습니다. 필요한 책을 알게 되면, 그 책의 내용만 받습니다.
기술적으로:
색인 (항상 전송): 도구 이름과 각 도구에 대한 짧은 설명만 포함.
세부 정보 (필요할 때만 전송): 실제로 사용되는 도구의 전체 설명, 올바르게 사용하는 데 필요한 모든 것, 그 이상은 없음.
검증: 매 압축 후, Refract는 중요한 내용이 제거되지 않았는지 자동으로 확인합니다. 의심스러운 점이 있으면 위험을 감수하지 않고 전체 버전을 전송합니다.
이 과정에는 AI 모델이 관여하지 않습니다. 완전 자동, 빠르고 결정적입니다.
도구 | 기능 |
압축 | 도구 스키마를 실시간으로 압축, 최대 98% 감소 |
신호 확인 | 매 압축 후 호출 가능 계약 검증 |
의미 라우팅 | 임베딩을 사용하여 올바른 도구 식별 (선택 사항) |
프롬프트 캐싱 | 반복 요청에 Anthropic cache_control 주입 |
도구 | 입력 | 출력 |
index_repo | 저장소 경로 | 모든 Python, JS, TS 파일의 집계된 색인 |
get_compressed | 파일 경로 | 압축된 구조 + 토큰 통계 |
expand | 파일 경로 + 함수 이름 | 원본 소스 + 의존성 컨텍스트 |
blast_radius | 파일 경로 + 함수 이름 | 대상이 변경될 때 깨지는 모든 함수 |
semantic_diff | 파일 경로 + 이전 소스 + 새 소스 | 변경 사항이 API를 깨는지 vs 본문만 변경하는지 |
semantic_diff_branches | 저장소 경로 + 파일 + 함수 + 기준/대상 git 참조 | 두 브랜치/커밋 사이 한 함수의 semantic_diff |
security_surface | 저장소 경로 | 위험한 호출 맵 (subprocess, eval, pickle, requests) |
refract-status --root /path/to/repo
refract-status --root /path/to/repo --json플래그 | 설명 |
| 분석할 경로 (기본값: 현재 디렉터리) |
| 기계가 읽을 수 있는 출력 |
표시: 언어별 파일 수, 원시 vs 압축 토큰, 인덱싱된 함수/클래스, 카테고리별 위험한 호출, tree-sitter를 지원하지 않는 언어.
Claude에게 대상 함수를 변경하면 어떤 함수가 깨지는지 물어보세요.
예시 결과:
{
"target": "authenticate",
"direct_callers": ["login_user"],
"all_impacted": ["login_user", "verify_session", "admin_access"],
"impacted_count": 3,
"risk_level": "MEDIUM"
}위험 수준: LOW (02개 영향), MEDIUM (35개), HIGH (6개 이상).
함수 본문이 아닌 인터페이스를 비교하여 API 변경 사항을 감지합니다. CI 게이트로 사용하세요.
예시 결과:
{
"breaking": ["authenticate"],
"body_only": ["logout"],
"added": ["new_function"],
"removed": [],
"unchanged": ["hash_password"],
"is_breaking": true
}is_breaking이 true이면 PR이 공개 API를 변경한 것이므로 검토가 필요합니다.
저장소 전체에서 위험한 기본 요소를 호출하는 모든 함수를 매핑합니다.
HIGH 위험: subprocess, os.system, eval, exec, pickle, ctypes
MEDIUM 위험: open (쓰기 모드), socket, requests, httpx, urllib
예시 결과:
{
"high_risk": [
{
"file": "src/llm_client.py",
"function": "run_command",
"calls": ["subprocess.run"]
}
],
"summary": {
"high_risk_count": 1,
"medium_risk_count": 3,
"total_functions_scanned": 87,
"clean_files": 8
}
}Python (ast 모듈 사용), JavaScript, TypeScript, JSX, TSX (tree-sitter 사용, pip install refract-mcp[multilang]로 선택 설치).
언어는 파일 확장자에서 자동 감지됩니다. tree-sitter가 설치되지 않은 경우 우아하게 대체됩니다.
Refract는 Anthropic 프롬프트 캐싱과 통합됩니다. as_anthropic_tools()는 압축된 카탈로그를 자동으로 캐시 가능으로 표시하여 반복 요청 시 비용을 더욱 절감합니다.
30일 동안 하루 100회 요청, 스키마 5,000 토큰 기준 예시:
시나리오 | 비용 |
Refract 없음, 캐시 없음 | $45.00 |
Refract + 캐시 사용 | $1.49 |
Claude Desktop에서 "Failed to spawn process: No such file or directory" 오류
Claude Desktop이 PATH에서 refract-proxy를 찾을 수 없습니다. 절대 경로를 찾아 직접 사용하세요:
which refract-proxy그런 다음 claude_desktop_config.json에서 전체 경로를 사용하세요:
{
"mcpServers": {
"my-tool-via-refract": {
"command": "/full/path/to/refract-proxy",
"args": [
"--target",
"npx @modelcontextprotocol/server-filesystem /path/to/folder"
]
}
}
}Claude Desktop, Cursor, MCP 표준을 따르는 모든 클라이언트, 모든 기존 MCP 서버.
MIT — 상업적 사용을 포함하여 자유롭게 사용 가능합니다.
Hosted MCP server for LLM cost estimation, model comparison, and budget-aware routing.
Free public MCP for AI agents — 193 tools, 44 workflows. No API key.
SaaS intelligence for AI agents. 5 unified tools cover 1,000+ services with 91-96% token savings.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/LoudiliMed/Refract'
If you have feedback or need assistance with the MCP directory API, please join our Discord server