How to connect Snapback to your agent: the skill, step by step

Snapback is a standard Model Context Protocol (MCP) server, so any MCP-capable agent connects and calls its tools — OpenClaw, GitHub Copilot, Hermes, Claude and Claude Code, Cursor, OpenAI Agents, or a custom client. Here's the whole flow, from zero to a diagnosed run.

Install — three ways, pick what fits

Snapback ships on three channels. The MCP server is the core; the plugin and skill make it automatic.

• MCP server (any client) — connect https://api.snapback.sh/mcp and call the tools directly. No install; works in Claude Code, Cursor, VS Code/Copilot, Windsurf, OpenClaw, Hermes. Also listed in the Official MCP Registry as io.github.ra1labsworkx-wq/snapback.
• PyPI plugin (self-heal) — pip install snapback-selfheal (zero dependencies) → wrap your calls with SnapbackInterceptor(auto_apply=True) and it auto-diagnoses + safe-heals on every error.
• ClawHub skill (OpenClaw) — clawhub install snapback-selfheal from your OpenClaw workspace (so it lands in your agent's skills dir), or import it in the Gateway.

One-click MCP config for the common clients (remote server, so it's just the URL):

# Claude Code
claude mcp add --transport http snapback https://api.snapback.sh/mcp

# Cursor / VS Code / Windsurf — an mcpServers entry:
# { "snapback": { "url": "https://api.snapback.sh/mcp", "transport": "streamable-http" } }

Step 1 — Register the MCP server

Point your agent framework at the endpoint. In OpenClaw, for example:

openclaw mcp add snapback --transport streamable-http \
  --url https://api.snapback.sh/mcp \
  --header "Authorization: Bearer $SNAPBACK_TOKEN"
openclaw mcp reload
openclaw mcp probe snapback    # confirm the tools are exposed

Other frameworks use their own MCP-add command with the same URL. The token is optional — many tools are free without one.

Step 2 — Use the free tools (no token)

• detect_loop(steps) — mid-run, is the agent repeating a tool call?
• budget_guard(...) — mid-run context / token / cost / step checks with suggested actions.
• diagnose_infra_error({error}) — a cryptic infra error → its family + verified fix; library-first (no LLM), LLM fallback on a miss.
• search_docs(query) — learn the trace format, taxonomy, or pricing.
• session_start / session_step / session_end — a live guardian that watches a run and warns in real time.

{"jsonrpc":"2.0","id":1,"method":"tools/call",
 "params":{"name":"diagnose_infra_error",
           "arguments":{"error":"unable to get local issuer certificate"}}}

Step 3 — Diagnose a failed run

When a run fails, send the trace to diagnose_trace. The format is tolerant — send what you have; steps matter most:

diagnose_trace({trace: { final_status: "failed", steps: [
  {index:1, action:"web_search", inputs:{query:"X"}, status:"success"},
  {index:2, action:"web_search", inputs:{query:"X"}, status:"success"},
  {index:3, action:"step_limit", error:"limit", status:"failed"} ]}})

// → { id, failure_class: "loop_repeated_tool_call",
//      root_cause, fix_suggestion, confidence }

Content in inputs/outputs is redacted server-side — you don't pre-redact. The verdict returns a real id you can pass to get_verdict or rate with submit_feedback.

Step 4 — Pay only when you diagnose

• Free starter allowance: self-register once — POST /v1/agents/register with {"name":"my-agent","framework":"openclaw","accepted_terms":true} → a token with 2,000 free diagnoses.
• Pay-per-call (x402): POST your trace to /mcp/x402 with no token → HTTP 402 → sign a payment → get the verdict. ~$0.0032 USDC on Solana or EVM. No account, no limits.

Step 5 — Close the self-healing loop

1. Before running: call preflight or agent_memory to see your recurring failure patterns.
2. During: stream steps to a live session, or call detect_loop / budget_guard — act on the warnings.
3. On failure: diagnose_trace, read the fix_suggestion + confidence, apply it, retry.
4. After: submit_feedback so the shared library improves for every agent.