Recipes — gotcontext.ai

Recipe 1 — PR diff review with minimal token spend#

Review a pull request that touches 10+ files without loading every file into context. Two tool calls replace a full corpus read that would otherwise consume 60–80% more tokens.

Tools used: filter_cli_output · gc_blast_radius (Pro+)

1.Compress the raw diff

Pass the output of git diff main..HEAD to filter_cli_output. It strips unchanged context lines, preserves changed signatures, and returns a skeleton of what actually moved.

filter_cli_output(
  text="<paste output of: git diff main..HEAD>",
  command_hint="git_diff"
)
# Returns: compressed diff — changed signatures highlighted, bodies stripped
# Typical savings: 60–80% on a multi-file PR

2.Get ranked context for the load-bearing symbol

Take the symbol most changed in step 1 and pass it to gc_blast_radius. It returns callers, callees, and related files ranked by relevance — replacing N separate file reads with a single structured response.

gc_blast_radius(
  files=[
    { "path": "api/app/mcp_gateway.py", "content": "<file contents>" },
    { "path": "api/app/middleware/auth.py", "content": "<file contents>" }
  ],
  focus_symbol="record_mcp_usage",
  query="auth attribution changes in the MCP gateway"
)
# files and focus_symbol are required; query is optional (defaults to focus_symbol)
# Returns: ranked caller/callee map + related file list
# One call replaces reading every file that touches the symbol

Why this works

Round 5 of the gotcontext.ai dogfood loop (2026-05-02) read ~10K lines across 21 files in a single cursor pass. Routing through gc_blast_radius + filter_cli_output cut the read budget by an estimated 60–80%, matching the live /v1/global-savings ratio.

Recipe 2 — Compress verbose test or CI output#

Make pytest output, gh run view --log, or flyctl logs fit in context without losing the failure signal. One call, one tool.

Tools used: filter_cli_output

1.Pass the raw output and name its source

Set command_hint to match your tool: "test_output" for pytest / Jest / Vitest, "log_output" for Fly logs or GitHub Actions output. Failures and errors are preserved; passing lines are stripped.

# pytest
filter_cli_output(
  text="<full pytest -v output>",
  command_hint="test_output"
)
# Returns: failures + error tracebacks only — typically 70–90% smaller

# fly logs
filter_cli_output(
  text="<output of: flyctl logs --no-tail>",
  command_hint="log_output"
)
# Returns: errors + warnings preserved, info spam stripped

# gh run view
filter_cli_output(
  text="<output of: gh run view --log>",
  command_hint="log_output"
)

flyctl logs cap

flyctl logs --no-tail is hard-capped at ~100 lines. For production 5xx, use Sentry first — it returns source-mapped frames in under 5 minutes without the cap. Use filter_cli_output on the Fly output you do have, then pivot to Sentry if the root cause isn't visible.

Recipe 3 — Ingest a large file and query it semantically#

Work with a large source file (for example, api/app/mcp_gateway.py at ~5,000+ lines) without loading the full text into context. Ingest once, query many times.

Tools used: estimate_tokens · ingest_context · read_skeleton · search_semantic

1.Check if it's worth compressing

Run estimate_tokens first. Compression adds structural overhead (headers, anchor lines) that costs more than it saves on inputs under ~200 tokens. Skip this step if you already know the file is large.

estimate_tokens(text="<file content>")
# If the estimate is under 200, skip compression — overhead exceeds savings
# If it's over 500, proceed with ingest

2.Ingest with the file path as the stable ID

Use the relative file path as file_id — it stays stable across sessions and lets you re-ingest in place when the file changes.

ingest_context(
  file_id="api/app/mcp_gateway.py",
  text="<file content>",
  metadata={"title": "MCP Gateway"}
)
# Returns JSON:
# {
#   "status": "success",
#   "file_id": "api/app/mcp_gateway.py",
#   "total_tokens": 64000,
#   "skeleton_tokens": 9200,
#   "compression_ratio": 6.96,
#   "token_savings": 54800,
#   ...
# }

3.Read the compressed skeleton

read_skeleton returns function signatures, class definitions, and section headings with bodies stripped. Use this when you need a structural overview before reading a specific section.

read_skeleton(file_id="api/app/mcp_gateway.py")
# Returns: compressed structural outline
# Typically 60–85% fewer tokens than the original

4.Find a specific section by query

Use search_semantic when you know what you're looking for but not where. Scope the search to one document with file_id, or omit it to search across everything you've ingested.

search_semantic(
  query="where is the budget cron loop",
  file_id="api/app/mcp_gateway.py"
)
# Returns: top-N semantically matching chunks
# Omit file_id to search the full ingested corpus

Re-ingest on file change

Call ingest_context again with the same file_id after editing a file. The previous index is replaced in place — your downstream search_semantic calls immediately see the updated content.

Recipe 4 — Pre-flight check before a large prompt#

Before sending an expensive prompt, know in one call whether to compress it, send it as-is, or clear context first. gc_pre_flight replaces three separate decisions (context check, compression check, cost preview) with a single verdict.

Tools used: gc_pre_flight · gc_session_summary (conditional)

1.Run pre-flight on the prompt

Pass your full prompt text. The tool returns one of four verdicts that tell you exactly what to do next.

gc_pre_flight(
  prompt="<the full prompt text you are about to send>"
)
# Verdicts:
#   send_as_is        — fits comfortably; no action needed
#   send_compressed   — compressed prompt included inline; cost preview attached
#   warn_context_limit — approaching the limit; compress or summarize
#   clear_first       — context is saturated; call gc_session_summary, then /clear

2.If verdict is clear_first: snapshot and reset

gc_session_summary exports a portable summary of the current session state. Run /clear in your MCP client, then re-inject the summary as the first message of the new context window.

gc_session_summary()
# Returns: portable summary of session state — paste this after /clear
# Then: /clear in your MCP client
# Then: paste the summary to re-anchor the new window

Available on all plans

gc_pre_flight and gc_session_summary are free-tier tools. No Pro subscription required.

Recipe 5 — Batch-ingest multiple documents before a multi-file audit#

Load context for an entire audit scope — for example, 20 files before a PR review — without N sequential ingest_context calls blocking your session. One async job, then query across the full corpus.

Tools used: estimate_tokens · batch_ingest_documents (Pro+) · search_semantic

1.Estimate and filter before batching

Run estimate_tokens on each file. Skip files under ~200 tokens — compression overhead on small inputs wastes the batch quota without improving retrieval.

estimate_tokens(text="<file content>")
# Repeat per file; skip the file if the estimate is under ~200 tokens
# Build your documents array from the files that pass the threshold

2.Ingest several documents in one call

batch_ingest_documents ingests multiple documents in a single call and returns the results synchronously — one round-trip instead of one call per file.

batch_ingest_documents(
  documents=[
    {
      "file_id": "api/app/mcp_gateway.py",
      "text": "...",
      "metadata": { "title": "MCP Gateway" }
    },
    {
      "file_id": "api/app/services/plan_gating.py",
      "text": "...",
      "metadata": { "title": "Plan Gating" }
    }
    // each document needs file_id + text
  ]
)
# Returns synchronously:
# {
#   "total": 2, "successful": 2, "failed": 0,
#   "results": [
#     { "file_id": "api/app/mcp_gateway.py", "success": true, "processing_time": 1.2 }
#   ],
#   "summary": "Batch complete: 2/2 succeeded"
# }

3.Query across the ingested corpus

Once the documents are ingested, call search_semantic without a file_id to search everything you just ingested. The response returns ranked chunks across all documents in one call.

search_semantic(
  query="where does quota enforcement happen"
)
# Searches across all ingested documents in the project
# Returns: ranked chunks from whichever files match best

Pro+ required

batch_ingest_documents is gated to Pro and above. Free-tier keys can achieve the same result with sequential ingest_context calls — use Recipe 3 repeated for each file instead.

Troubleshooting#

Quick diagnosis for the most common issues across these recipes. Full error code reference is at Error Codes.

Tool not in tools/list

Cause A — wrong profile

The plugin bundle defaults to ?profile=core (7 tools). Platform tools like gc_blast_radius, gc_kb_*, and batch_ingest_documents only appear on ?profile=full. Add ?profile=full to your MCP URL in .mcp.json.

Cause B — plan gating

gc_blast_radius and batch tools require a Pro+ key. Check /dashboard/billing for your current plan. A rejected tools/call returns an upgrade URL inline in the error body.

401 on every call

The gateway requires Authorization: Bearer gc_your_key. Omitting Bearer, using Token, or passing the raw key without a scheme all fail at auth middleware. Check your .mcp.json headers block. Also verify that the key's monthly quota hasn't been exceeded at /dashboard.

Negative savings on small inputs

Compression adds structural overhead (section headers, anchor lines) that exceeds the savings on inputs under ~200 tokens. Run estimate_tokens first and skip compression when the count is under 200. Compression becomes reliably beneficial at 500+ tokens; the GTM benchmarks validate 9.5× ratios on large documents.

421 Invalid Host header

The MCP SDK's DNS rebinding protection rejects requests whose Host header is not in the allowlist. Allowed hosts on the SaaS endpoint: api.gotcontext.ai and gotcontext-api.fly.dev. If a proxy is rewriting your Host header, configure it to pass the original through.