Troubleshooting

Cause A — wrong profile

The plugin bundle defaults to ?profile=core, which exposes exactly 7 tools: ingest_context, read_skeleton, search_semantic, modulate_region, get_stats, list_documents, and delete_document. Platform tools only appear on the full profile.

Fix

Append ?profile=full to the MCP URL in your .mcp.json:

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

Cause B — plan gating

Free-plan keys see only free-tier tools. gc_blast_radius, gc_kb_*, batch_compress_queue, and all advanced compression tools require Pro or above.

Fix

Check your plan at /dashboard/billing. The gateway returns an upgrade URL inline in any tools/call response for a gated tool, e.g. "Tool 'gc_blast_radius' requires a Pro plan. Upgrade at https://gotcontext.ai/dashboard/billing".

Cause C — SaaS filesystem lockdown

Filesystem-touching tools (ingest_directory, diff_cached_file, compress_codebase run from a local path, and similar) are removed from tools/list on the production SaaS endpoint because the API server has no access to your filesystem.

Fix

These tools only work on a self-hosted deployment with filesystem access. On the SaaS endpoint, use ingest_context with text content instead of a file path.

Cause A — wrong bearer format

The gateway requires exactly Bearer gc_<key> in the Authorization header. Omitting the Bearer prefix, using Token, or passing the raw key without a scheme prefix all fail.

Fix

{
  "gotcontext": {
    "url": "https://api.gotcontext.ai/mcp",
    "headers": { "Authorization": "Bearer gc_your_key_here" }
  }
}

Cause B — quota exceeded

When a key has per-key quota enforcement enabled and the monthly limit is exceeded, the gateway rejects new calls at the auth layer. There is no separate 429 path in the MCP protocol — quota exhaustion looks like a 401.

Fix

Check /dashboard for your current month's count. Free tier resets monthly at midnight UTC on the 1st. Upgrade from /dashboard/billing if you need more capacity before reset.

Cause C — OAuth 2.1 JWT with wrong aud claim

If you are using OAuth 2.1 JWT auth rather than a gc_ key, the token's aud claim must match the MCP resource URL. On the production SaaS endpoint that is https://api.gotcontext.ai/mcp.

Fix

Re-issue the JWT with aud : ["https://api.gotcontext.ai/mcp"]. The discovery document at /.well-known/oauth-protected-resource lists the canonical resource identifier.

Cause

A gc_ key is created without a bound project by default. The Knowledge Hub tools read the project context from the key's bound project, not from a request parameter — a key with no project ID cannot resolve which knowledge base to query.

Fix — dashboard

Go to /dashboard/settings, select the key, and bind it to a project from the inline rebinder.

Fix — MCP tool (Pro+)

Use gc_rebind_api_key from an authenticated MCP session:

{
  "name": "gc_rebind_api_key",
  "arguments": {
    "key_id": "gc_...",
    "project_id": "<uuid from /dashboard/projects>"
  }
}

Cause

The compression engine adds structural overhead: a === SEMANTIC SKELETON === header, RAG anchor lines, and section markers. On inputs below roughly 200 tokens, this overhead exceeds the content reduction. A 58-token paste through /v1/demo/compress was observed to return 67 compressed tokens (ratio ≈ 0.9×).

Fix

Call estimate_tokens first. If the token count is under ~200, skip compression — the overhead will cost more than it saves. Compression becomes reliably beneficial at 500+ tokens; the documented benchmark ratio of 13× applies to large documents, not short snippets.

Cause

The MCP SDK's DNS rebinding protection rejects requests whose Host header is not in the explicit allowlist. This fires when a proxy rewrites the Host header, when connecting via an IP address directly, or when using a non-standard hostname.

Allowed hosts on the production SaaS endpoint:

• api.gotcontext.ai
• gotcontext-api.fly.dev
• localhost variants (local development only)

Fix

Point your MCP client at https://api.gotcontext.ai/mcp without a proxy that rewrites the Host header. For self-hosted deployments, add your hostname to TransportSecuritySettings.allowed_hosts in your fork of mcp_gateway.py.

Cause

Plan-level monthly compression quotas: Free 1,000/month, Pro 50,000/month, Team 100,000/month, Enterprise 500,000+/month. Per-key quota enforcement is opt-in; when enabled and the limit is exceeded, the gateway rejects at the auth layer (see T2 — Cause B).

Fix

Monitor /dashboard for current cycle consumption. The check_budget MCP tool returns remaining quota in-session without leaving your agent workflow. Monthly limits reset at midnight UTC on the 1st of each month. When you hit a per-minute rate limit, the API responds with HTTP 429 and a Retry-After header; back off exponentially before retrying.

Problem A — public SaaS keys authenticate against your private instance

Any gotcontext.ai Pro subscriber can authenticate against your self-hosted instance because MCP_OAUTH_RESOURCE is unset or still equals the production default. The startup check emits CRITICAL for this condition but does not abort the process by default.

Fix

Set a unique resource URL before exposing the instance:

flyctl secrets set MCP_OAUTH_RESOURCE='https://your-domain/mcp'

Problem B — self-hosted OAuth JWT tokens rejected with 401

The OIDC issuer (CLERK_JWKS_URL) or audience is misconfigured. The JWT aud claim must match your MCP_OAUTH_RESOURCE value exactly.

Fix

Confirm that your identity provider issues tokens with aud matching the value set for MCP_OAUTH_RESOURCE. The assert_env_sanity startup check logs config-drift details on boot — check Fly logs after a fresh deploy.

Problem C — license validation fails on startup

The Ed25519 license JWT is verified on every boot via bootstrap_self_hosted_runtime(). If theLICENSE_KEY_* environment variable is missing or was issued with a mismatched private key, startup fails with a license validation error.

Fix

Set the LICENSE_KEY_* environment variable on your deployment and that the JWT was issued with the private key matching the public key at public_key_test.pem. Do not commit keys.json — the private signing key must never appear in source control.