chatctx documentation

Everything an agent or integrator needs: one endpoint, three tools, one response shape. Prefer the machine-readable copies if you are a model reading this page.

Connection

Endpoint

https://chatctx-mcp.brackket.workers.dev/mcp

Transport

MCP Streamable HTTP, stateless. No session id is issued or required.

Methods

POST for JSON-RPC requests and notifications. GET opens a keep-alive SSE stream for clients that probe it first.

Content type

application/json on requests. Responses are SSE-framed.

Required request header

Accept: application/json, text/event-stream

Authentication

Send Authorization: Bearer <key> with a key in the form kb_live_<prefix>_<secret>. Keys are stored only as an HMAC-SHA256 hash with a server-side pepper, so they cannot be recovered after creation. Owners can revoke a key or cap its daily tool-call quota.

Anonymous guest access is enabled on the production endpoint with a per-IP daily quota of 250 tool calls. A request that presents a bearer token which is invalid or revoked returns 401; it never silently falls back to guest access.

Protocol notes

• Send initialize, then notifications/initialized, then calls.
• The server reports the name chatctx-knowledge. Capabilities are tools only: no prompts, resources, sampling, or elicitation.
• Every tool advertises readOnlyHint, except submit_feedback, which is a non-destructive write.
• Parse the SSE data: line. A body may contain : connected or : keepalive comments on the GET stream.
• Tool failures are returned as a JSON-RPC result with isError: true and a payload of {"error":{"code","message","details?"}} — not as a transport error.

search_knowledge

Hybrid retrieval over approved guidance. The server runs PostgreSQL full-text search and pgvector cosine search, fuses the rankings, applies applicability bonuses for the requested technologies and versions, and returns the best records within the token budget.

topics: architecture, implementation, security, accessibility, ux, reliability, testing, performance, data, observability, tooling.

task types: build, architecture, debug, security, accessibility, performance, testing, review, other.

Unknown arguments are rejected. Phrase the query as the decision you are making, not as a search phrase alone.

get_guidance

Fetch the full record behind a search hit. Use it when the brief result is relevant and you need exceptions, pitfalls, verification checks, version constraints, examples, or provenance before acting.

Unknown, deprecated, or non-public identifiers come back in missing rather than failing the whole call.

submit_feedback

Anonymous, owner-reviewed signal about retrieval quality. It never feeds back into ranking automatically.

Do not include source code, secrets, credentials, customer data, or personal information in the comment. Feedback rows store no API key, IP address, user agent, or client identifier.

Response shape

Every search returns the same envelope. Truncated for readability:

{
  "query_summary": "implementation · React",
  "results": [
    {
      "id": "…",
      "slug": "use-stable-keys-for-dynamic-react-lists",
      "title": "…",
      "topic": "implementation",
      "summary": "…",
      "recommendation": "…",
      "rationale": "…",
      "applies_to": [{ "kind": "framework", "name": "React", "version_constraint": "≥16.0" }],
      "conditions": ["…"],
      "exceptions": ["…"],
      "pitfalls": ["…"],
      "verification_checks": ["…"],
      "confidence": "high",
      "updated_at": "2026-10-18T…",
      "sources": [
        {
          "title": "…",
          "url": "https://…",
          "publisher": "…",
          "evidence_excerpt": "…",
          "relation": "supports"
        }
      ]
    }
  ],
  "retrieval": {
    "mode": "hybrid",
    "degraded": false,
    "embedding_provider": "cloudflare-workers-ai",
    "embedding_cache": "hit",
    "total_candidates": 20
  },
  "suggestions": ["…"]
}

get_guidance returns { "results": [...], "missing": [...] } where each record additionally carries status, content_version, approved_at, and optionally version_constraints and examples.

Retrieval modes

hybrid

Text and vector results were fused. Normal operating mode.

keyword_fallback

No query embedding was available, so only full-text search ran. Check degraded_reason and lower trust in recall, not in the returned text.

no_match

Nothing cleared the relevance threshold. results is empty and suggestions explains how to broaden the query. Treat this as “not in the knowledge base”, not as an error.

degraded: true means part of the retrieval path failed. technology_filter_fallback: true means the technology filters were too narrow and the server retried without them.

Errors and limits

Invalid tool arguments produce a successful JSON-RPC response whose result has isError: true and a validation message. Domain failures use the same envelope with a stable code. Internal failures never include stack traces or query text.

Privacy

• Raw search queries are not written to logs.
• Retrieval analytics store a salted hash of the query plus bounded metadata: topic, technology filters, mode, result count, and degraded state.
• Query embeddings are cached by hash, model, and dimension. Raw query text is never stored.
• Feedback excludes API key ids, IP addresses, user agents, and client identifiers.
• Guest quota accounting stores an HMAC-SHA256 hash of the client IP, never the address itself.

Machine-readable files