{
        "mcpServers": {
          "gotcontext": {
            "url": "https://api.gotcontext.ai/mcp?profile=core",
            "headers": {
              "Authorization": "Bearer gc_your_key_here"
            }
          }
        }
      }

{
        "mcpServers": {
          "gotcontext": {
            "url": "https://api.gotcontext.ai/mcp?profile=core",
            "headers": {
              "Authorization": "Bearer gc_your_key_here"
            }
          }
        }
      }

{
        "mcp": {
          "servers": {
            "gotcontext": {
              "url": "https://api.gotcontext.ai/mcp?profile=core",
              "headers": {
      "Authorization": "Bearer gc_your_key_here"
              }
            }
          }
        }
      }

{
        "mcpServers": {
          "gotcontext": {
            "url": "https://api.gotcontext.ai/mcp?profile=core",
            "type": "http",
            "headers": {
              "Authorization": "Bearer gc_your_key_here"
            },
            "timeout": 30000
          }
        }
      }

# gotcontext.ai Compression

      This project uses gotcontext.ai for semantic compression via MCP.

      ## When to compress
      - Before sending large files or docs to the AI context window
      - When terminal output is verbose (git diff, test results, logs)
      - When reviewing code across many files
      - Before reviewing a PR or explaining a diff — compress the changed
        files or run `gc_blast_radius` to see only transitively-touched code

      ## Compression workflow
      1. Use `ingest_context` to add a document (give it a unique file_id)
      2. Use `read_skeleton` to get an adaptive structural skeleton.
         Compression adapts to size: small/medium docs stay faithful (most
         sections kept, with meaningful savings); large docs compress hard.
         Drill into any referenced section with `modulate_region`.
      3. For a targeted read, pass `selection_mode="evidence_aware"` + a
         `query` (and optional `top_k`) to anchor the relevant sections.
      4. Use `search_semantic` to find specific sections by query.
      5. Use `filter_cli_output` to compress git diffs, pytest output, etc.

      ## Code understanding (Pro+)
      - `compress_codebase` — AST-aware digest of an entire repo; function
        and class signatures only, bodies stripped
      - `gc_blast_radius` — ranked context for a focus symbol: tensor-grep
        blast-radius + BM25 fusion. Best for PR review and bug triage
      - `gc_compress_manifest` — compress an MCP tools/list response so
        downstream agents see shorter tool descriptions without losing
        inputSchema semantics (v1.8.0+)
      - `batch_ingest_documents` — submit up to 50 docs as one async job;
        poll status via `GET /v1/batch-queue/{id}`

      ## Tips
      - Use `estimate_tokens` first to see if compression is worthwhile
      - For code files, the compressor understands function/class boundaries
      - Use `get_compression_presets` to see available fidelity levels
      - Call `tool_help` for documentation on any specific tool

1. Check whether compression is worthwhile

For any file or output larger than ~1,500 tokens (roughly 6,000 bytes), call estimate_tokens first. If the result is below that threshold, send as-is. The compression overhead is not worth it.

2. Call gc_pre_flight first — it routes you to the right tool

gc_pre_flight is the recommended entry point before any gotcontext operation. It returns a verdict (one of four actions) and a mode field that tells you which gotcontext tool to reach for next: scout (use read_skeleton / search_semantic), compress (ingest + read_skeleton), read or write (KB operations), or idle (nothing needed).

gc_pre_flight()
      # verdict — what to do:
      #   send_as_is       — context is small; no action needed
      #   send_compressed  — ingest + read_skeleton before sending
      #   warn_context_limit — approaching limit; compress or summarize
      #   clear_first      — context is saturated; clear before proceeding
      # mode — which tool to reach for next:
      #   scout   → read_skeleton / search_semantic
      #   compress → ingest + read_skeleton
      #   read    → gc_kb_get / gc_kb_query
      #   write   → gc_kb_ingest / gc_kb_edit
      #   idle    → nothing needed

3. Compress if recommended

If the verdict is send_compressed:

ingest_context(file_id="my-doc", content="...")
      read_skeleton(doc_id="...")
      # Use the adaptive skeleton in your prompt instead of the raw content.
      # Drill into any referenced section with modulate_region, or pass a
      # selection_mode="evidence_aware" + query for a targeted read.

For verbose CLI output

Pipe pytest output, fly logs, or git diff through filter_cli_output before passing to the model. Typically 70 to 90% smaller with failure signal preserved.

For code review questions

When asking “what does changing X affect?” or reviewing a diff, call gc_blast_radius with the focus symbol. It returns ranked context (callsites, callers, transitively-touched code) without you reading every file manually.

Key bound to the wrong project

Per-project budget alerts fire against the project the key is bound to. If your key is bound to Default (or to a different project), every compression call increments the wrong counter, budget thresholds trigger at the wrong time, and per-project usage charts show nothing. Rebind via Settings → API Keys.

Key with no project binding (project_id NULL)

Legacy keys minted before the per-project update carry a project_id of null and fall back to the user-scoped Default rollup. All traffic appears under Default, polluting that project’s stats. Verify with project_stats(): if project_name returns "Default" but you created a dedicated project, the key needs rebinding.

.mcp.json environment variable not set before launching Claude Code

The .mcp.json substitution reads the shell environment at session start, not from .env.local or any dotenv file. If GOTCONTEXT_KEY is only in .env.local the MCP server will fail to authenticate. Run export GOTCONTEXT_KEY=gc_... in your shell before launching Claude Code, or add it to your shell profile.

Per-project counts not incrementing after rebind

The plan cache has a 5-minute TTL (Upstash). After rebinding a key to a new project, allow up to 5 minutes before project_stats() reflects the new attribution. Counts already attributed to the old project do not retroactively move.