Skip to content
HEB SDK (Unofficial) Docs

Architecture

Request flow, auth layers, and session storage

This is the high-level flow for heb-mcp-unofficial in local and hosted modes. It mirrors MCP SDK patterns while layering H‑E‑B auth and sessions.

Trace requests

Hosted mode accepts Streamable HTTP at /mcp and spins up a per-request MCP server tied to a user session. Local mode uses STDIO with the same tool registry.

Handle sessions

Local sessions load from HEB_SAT/HEB_REESE84 or ~/.heb-sdk-unofficial/cookies.json, and the file watcher reloads automatically. Hosted sessions are stored per user and can use cookies or bearer tokens.

Bearer sessions can refresh with saved refresh tokens.

Secure access

Hosted mode wraps /mcp with MCP OAuth and uses Clerk to identify users. Cookie ingestion and H‑E‑B OAuth exchanges require Clerk auth as well.

Return tool data

Each tool returns markdown for chat-friendly responses. Pass response_format: "json" to include structured JSON in structuredContent.

Know endpoints

These endpoints are available in hosted mode.

  • /mcp — Streamable HTTP MCP endpoint for tool calls
  • /connect — web UI to link H‑E‑B OAuth
  • /authorize — OAuth authorize endpoint used by MCP clients
  • /api/cookies — cookie ingestion with Clerk bearer tokens
  • /api/heb/oauth/* — H‑E‑B OAuth config, exchange, refresh, status
  • /health — status and version