Fallback MCP server
2026년 10월 6일 커밋자율 에이전트가 실패를 진단하고, 요청을 수정하며, 데이터 소스를 찾을 수 있도록 결정론적인 복구 및 의사결정 유틸리티를 제공합니다.
다른 이름 baronsigma/fallback-agent-tools, fallback-agent-tools
- 스타
- 0
- Tools
- 4
- 다운로드, 30일
- —
- 최신 버전
- 0.1.0-beta.1
- 마지막 커밋
- 2026년 10월 6일
- 라이선스
- MIT
Fallback MCP란?
자율 에이전트가 실패를 진단하고, 요청을 수정하며, 데이터 소스를 찾을 수 있도록 결정론적인 복구 및 의사결정 유틸리티를 제공합니다. 4개 도구를 제공합니다. 예: source_route, error_route, request_repair.
프로젝트 README에서 생성된 요약
Fallback MCP server 정보
Fallback은 자율 에이전트가 실패 상황과 의사결정 지점을 헤쳐 나갈 수 있도록 설계된 결정론적 유틸리티 모음을 제공합니다. 에이전트가 정체되었을 때 비용이 많이 드는 추론 루프에 의존하는 대신, 이 도구들은 오류를 진단하거나 데이터를 찾기 위한 작고 특화된 기능을 제공합니다. 이 서비스는 hosted MCP 엔드포인트 또는 HTTP API를 통해 사용할 수 있으며, Base 메인넷에서 canonical USDC를 사용하는 x402 V2 pay-per-call 모델을 활용합니다. 사용자가 각 특정 도구 호출에 대한 결제를 승인하므로 별도의 계정이나 API 키가 필요하지 않습니다.
개발자는 기계 판독 가능 데이터 형식을 찾는 source_route, 실패한 요청을 분류하는 error_route, 증거를 기반으로 경미한 수정을 제안하는 request_repair, 추가 조사의 비용 효율성을 판단하는 stop_search와 같은 특정 도구를 사용할 수 있습니다. 이 시스템은 정밀도를 위해 구축되었으며, 특정 도메인에서 API나 데이터셋을 찾는 것과 같이 제한된 범위의 행동을 제공합니다. 각 도구 호출에는 호출당 최대 8개의 직접 HTTP 요청 및 총 실행 시간 12초와 같은 정의된 제한이 있습니다.
활용 사례
- 1기계 판독 가능 데이터 소스 위치 파악에이전트가 알려진 발행자로부터 JSON 또는 CSV 형식의 특정 데이터셋에 액세스하는 최선의 방법을 식별할 수 있습니다.
- 2요청 실패 진단 및 복구API 또는 도구 호출이 실패할 때, 에이전트는 오류를 분류하여 다음 안전한 행동을 결정할 수 있습니다.
- 3잘못된 형식의 요청 수정에이전트는 가용한 증거를 사용하여 요청을 유효하게 만들기 위한 최소한의 변경 사항을 제안할 수 있습니다.
- 4검색 비용 최적화에이전트는 현재 증거를 바탕으로 검색을 계속하는 것이 경제적으로 타당한지 결정할 수 있습니다.
프로젝트의 README를 바탕으로 작성되었습니다. 모든 활용 사례는 해당 내용의 인용문과 대조하여 확인합니다.
Fallback MCP 설치 방법
형식 확인: 2026년 11월 10일Cursor에 추가Goose에 추가Claude Code에 Fallback MCP 설치
$ claude mcp add --transport http fallback-agent-tools https://fallback.factrail.online/mcpCursor에 Fallback MCP 설치
~/.cursor/mcp.json
{
"mcpServers": {
"fallback-agent-tools": {
"url": "https://fallback.factrail.online/mcp"
}
}
}VS Code에 Fallback MCP 설치
.vscode/mcp.json
{
"servers": {
"fallback-agent-tools": {
"type": "http",
"url": "https://fallback.factrail.online/mcp"
}
}
}VS Code CLI에 Fallback MCP 설치
$ code --add-mcp '{"name":"fallback-agent-tools","type":"http","url":"https://fallback.factrail.online/mcp"}'Codex에 Fallback MCP 설치
$ codex mcp add fallback-agent-tools --url https://fallback.factrail.online/mcpCodex config.toml에 Fallback MCP 설치
~/.codex/config.toml
[mcp_servers.fallback-agent-tools] url = "https://fallback.factrail.online/mcp"
Gemini CLI에 Fallback MCP 설치
$ gemini mcp add -s user --transport http fallback-agent-tools https://fallback.factrail.online/mcpGemini settings.json에 Fallback MCP 설치
~/.gemini/settings.json
{
"mcpServers": {
"fallback-agent-tools": {
"url": "https://fallback.factrail.online/mcp",
"type": "http"
}
}
}Fallback MCP 도구 4
README에서 감지됨source_routeerror_routerequest_repairstop_search
| source_route | — | |
| error_route | — | |
| request_repair | — | |
| stop_search | — |
자동 검사
2026년 11월 15일에 실행됨전체 보고서 →아직 인증되지 않았습니다. 서버는 80점 이상의 점수, 심각한 결함 없음, 그리고 검사에 충분한 데이터를 갖추어야 합니다. 검사 방식 · 점수를 높이기 위해 수정할 항목
- 소스 저장소 연결 및 접근 가능baronsigma/fallback-agent-tools is public and reachablegithub.com/baronsigma/fallback-agent-tools ↗통과
- 패키지가 이 저장소를 소스로 명시검사되지 않음
- 빌드 출처(Sigstore 증명)검사되지 않음
- 오픈 소스 라이선스 (OSI)MITspdx.org/licenses/MIT.html ↗통과
- 최근 1년 내 커밋 또는 릴리스Last commit or release 2026-10-06github.com/baronsigma/fallback-agent-tools ↗통과
- OpenSSF Scorecard검사되지 않음
- 패키지 이름이 인기 패키지와 유사하지 않음검사되지 않음
- 패키지 및 해당 종속성에 중요한 보안 권고 없음검사되지 않음
- 모델에 대한 숨겨진 지침 없음4 tool descriptions and the README read; no override phrases, credential paths or hidden characters통과
- 파괴적인 도구에 라벨 표시됨No tool named like delete, drop or exec통과
- 원격 엔드포인트가 MCP 핸드셰이크에 응답initialize answered with protocol 2025-06-18 in 490 ms통과
README
GitHub에서 보기Fallback
______ _ _
| ____| | | |
| |__ __ _ | | |__ __ _ ___| | __
| __|/ _` || | '_ \ / _` |/ __| |/ /
| | | (_| || | |_) | (_| | (__| <
|_| \__,_||_|_.__/ \__,_|\___|_|\_\
find the route forward
Fallback
Tiny paid recovery and decision utilities for autonomous agents.
When an agent gets stuck, Fallback helps it find the next safe move without wasting a large reasoning loop.
source_route Where should I look? ($0.02)
error_route Why did this fail? ($0.002)
request_repair Can I safely fix the request? ($0.005)
stop_search Is another search worth it? ($0.003)
Use Fallback
Pay-per-call tools that help AI agents find sources, diagnose failures, repair requests, and decide when to stop searching. Fallback gives autonomous agents small, deterministic utilities for the moments where automation gets stuck: finding the right source, diagnosing a failed request, repairing a request from available evidence, and deciding whether another search or paid retrieval is worth the cost.
Hosted service
MCP endpoint: https://fallback.factrail.online/mcp\
HTTP API base: https://fallback.factrail.online\
Payment: x402 V2 pay-per-call. Check each live challenge for network, asset, amount, and recipient.
Agent skill: skill.md
OpenAPI: openapi.json
Network: Base mainnet, canonical USDC
Release: v0.1.0-beta.1
Tools
source_route($0.02): Where should I look? Find likely authoritative or machine-readable sources.error_route($0.002): Why did my call fail? Classify a failed request and recommend a bounded next action.request_repair($0.005): Can I safely fix the request? Propose the smallest change supported by caller-supplied evidence.stop_search($0.003): Is further searching worth it? Decide whether more bounded search effort is justified by the evidence and remaining cost.
These tools do not replace agent reasoning, and stop_search never proves universal absence.
When an agent should use this
Use source_route when an agent knows what it needs and which publisher (a domain or start URL), but not how to get it in machine-readable form: an API, OpenAPI spec, bulk download, dataset or feed.
- Good fit: "Get the latest population dataset from Eurostat", "Find a JSON/CSV route for this agency's statistics", before the agent starts browsing page by page.
- Not a fit: general web research, answering a factual question, or verifying a fact (for source-backed facts, see FACTRAIL MCP).
How to read the result:
status: routes_found: try routes in order.scoreis a deterministic ranking, not a probability or confidence.status: no_suitable_route_found: nothing suitable within the checked scope (seechecked.direct_probes). This is not evidence that no route exists. The agent should look elsewhere (another host, the publisher's open-data portal), not conclude "there is no API".- Always read
limitations. It says, for example, whether external search was unavailable or candidate inspection was capped.
Limits per call: at most 8 direct HTTP requests, 12 s total, 1 MiB per response, and at most 1 external search request. No LLM inference. The hosted beta currently runs deterministic discovery only (no search provider configured).
Access: hosted MCP https://fallback.factrail.online/mcp (Streamable HTTP) or the HTTP tool routes, x402 pay-per-call (each challenge declares its payment network and amount; no account or API key). To try it without payment, self-host with PAYMENT_MODE=disabled (see Local development). Machine-readable summary: llms.txt. More detail: Using Fallback with agents.
Fallback is publicly launched. See the current launch and distribution status, product rename impact audit, discovery/distribution readiness audit, and telemetry and 30-day KPI definitions.
When to use error_route
Use it after an HTTP, API, MCP, or tool request fails when the safe next action is unclear. It classifies supplied evidence and returns bounded retry guidance. Do not use it when recovery is already obvious or the task needs deeper domain reasoning; it does not execute requests or invent undocumented fixes.
Requirements
- Current Node.js LTS (Node 24 at scaffold creation; supported engine is Node 22+)
- npm
Local development
npm install
cp .env.example .env
npm run generate
npm run dev
The server exposes /, /healthz, /readyz, /catalog.json, /openapi.json, /llms.txt, /llms-full.txt, /skill.md, /.well-known/x402.json, /.well-known/mcp/server-card.json, and the Streamable HTTP MCP endpoint at /mcp. Both HTTP and MCP dispatch through the shared runtime handler registry. PAYMENT_MODE=disabled supports local development; paid deployments must explicitly select test or production and provide complete x402 configuration.
Verification
npm test
npm run typecheck
npm run lint
npm run benchmark:source-route
npm run benchmark:error-route
npm run verify:catalog
npm run release:check
30-second start
Connect an x402-compatible agent to https://fallback.factrail.online/mcp, call the matching tool after a concrete failure or search decision, and approve only the network, token, recipient, and amount shown by its payment challenge. HTTP clients can use POST /v1/tools/{tool_id} on the hosted origin. See skill.md for examples and schemas.
Architecture
src/core/registry.ts is the one canonical tool registry. Every discovery surface and distribution artifact is derived from it. Each tool gets a directory under src/tools/ with a contract and handler; future tool tests and fixtures belong alongside the matching contract test/fixture directories. HTTP and MCP adapters must call the same tool handler. Payment middleware and marketplace integrations stay outside tool logic.
The service supports x402 V2 per-call payment without accounts or API keys. The server only receives payment at X402_PAY_TO; no receiving wallet private key is required. Paid startup fails closed if the required network, receiving address, facilitator URL, or production URL is missing or invalid. See deployment and payment setup.
Example
{
"goal": "Download the latest population dataset",
"start_url": "https://ec.europa.eu/eurostat/",
"preferred_formats": ["csv", "json"]
}
Call POST /v1/tools/source_route with a goal and either start_url or domain. The result is limited to the checked scope; a missing result does not mean that no route exists. Direct site discovery runs without external search credentials. If Tavily or Brave is configured and direct discovery is insufficient, the tool can make at most one search request.
See PRODUCT, ARCHITECTURE, TOOL_ADMISSION, DISTRIBUTION, and RELEASE.
Related: FACTRAIL MCP
Fallback comes from the same author and design rule as FACTRAIL MCP: agent tools should report what they checked, not only what they found. FACTRAIL answers "what is established about this fact, and from which source?" by returning evidence envelopes with support levels, unresolved fields and receipts ("unknown is better than invented"). Fallback answers "where can I get this data?" ("absence is not proof of nonexistence"). The two are independent services with no code dependency, and you can use either one alone.
Fallback MCP 질문
Fallback MCP를 Claude Code에 추가하려면 어떻게 하나요?
터미널에서 claude mcp add --transport http fallback-agent-tools https://fallback.factrail.online/mcp를 실행합니다. 모든 프로젝트에서 사용할 수 있게 하려면 --scope user를 추가합니다.
Fallback MCP를 Cursor에 추가하려면 어떻게 하나요?
~/.cursor/mcp.json를 열고 mcpServers 아래에 서버를 추가합니다. 위 설치 섹션에 표시된 Cursor 구성을 사용합니다.
Fallback MCP는 어떤 도구를 제공하나요?
4개 도구를 제공합니다. 예: source_route, error_route, request_repair, stop_search.
source_route 도구는 어떤 기능을 수행하나요?
발행자는 알고 있지만 구체적인 데이터 경로를 모를 때, API, OpenAPI 사양 또는 데이터셋과 같이 신뢰할 수 있거나 기계 판독이 가능한 소스를 에이전트가 찾을 수 있도록 돕습니다.
error_route 도구는 에이전트에게 어떤 도움을 주나요?
요청이 실패한 원인을 분류하고, 에이전트가 복구할 수 있도록 제한된 범위 내의 다음 행동을 권장합니다.
stop_search 도구가 정보가 존재하지 않음을 증명하나요?
아니요, 이 도구는 추가 검색이 비용 대비 가치가 있는지를 결정할 뿐, 정보의 완전한 부재를 증명하지는 않습니다.
도구 사용에 대한 결제는 어떻게 처리되나요?
이 서비스는 x402 V2 pay-per-call 방식을 사용합니다. 에이전트는 결제 챌린지에 표시된 네트워크, 자산, 금액 및 수신인을 승인합니다.