# UseMyContext - Deep SDK + MCP Reference > The long-form companion to /llms.txt, written for AI coding assistants building with the UseMyContext SDK and MCP tools. Every signature, type, and example below is grounded in the shipped source. For the high-level site map, see https://usemycontext.ai/llms.txt. UseMyContext.ai is a structurally-blind, third-party service for one person's personal context. A user curates their compiled context once, then connects any AI client (Claude, ChatGPT, or coding tools like Gemini CLI and Cursor) or your own app over MCP. The public surface is structurally blind: it declares no data bindings, so it holds no readable user data. You ship the integration; UseMyContext holds and serves the user's context, and the user controls and can revoke it. There are two ways to build: - The MCP surface (13 tools over Streamable HTTP at https://mcp.usemycontext.ai/mcp). Any MCP-speaking client can use it directly. - The npm SDK (`usemycontext`), a typed client + React hook that wraps all thirteen of those tools for JS/TS apps. Scope is ALWAYS the authenticated user. It is resolved server-side from the token, never passed as a tool argument. Every tool is read-only except `suggest_update`, which only files a PENDING proposal for the user to review - nothing is ever written to the user's files. -------------------------------------------------------------------------------- ## Install ```bash npm i usemycontext ``` - Package: `usemycontext` (version 1.4.2 at time of writing). - Source and plugins live on GitHub: https://github.com/usemycontext (org), with a Claude Code plugin (usemycontext/claude-code-plugin), a Cursor plugin (usemycontext/cursor-plugin), and a plain-markdown docs mirror (usemycontext/docs; the rendered canonical is https://usemycontext.ai/docs). - ESM + CJS, with bundled TypeScript declarations. - The core entry is framework-free. The React hook + button live behind the `usemycontext/react` subpath, gated by an OPTIONAL `react` peer dependency (>=17), so importing the core entry never pulls React in. - Exports: - `usemycontext` -> the framework-free client factory + types + errors. - `usemycontext/react` -> the React hook and the drop-in button. - The package also ships a bin: `usemycontext` (the session-starter CLI below). -------------------------------------------------------------------------------- ## Session-starter CLI - `npx usemycontext pull` One command turns the user's curated context into a local file any AI session can read at startup - no SDK integration, no MCP client setup. This is the path for file-reading AI tools: Claude Code SessionStart hooks, agent frameworks with bootstrap files, CLIs, automations. Full guide: https://usemycontext.ai/docs/cli-pull ```bash export UMC_TOKEN= npx -y usemycontext pull # writes ./UMC-CONTEXT.md npx -y usemycontext pull --out me.md # or any path ``` - Auth: `UMC_TOKEN`, or a `token=` line in `~/.usemycontext`. The token is never accepted as a CLI flag (flags land in shell history) and is never written anywhere by the CLI. - What it writes: the user's compiled composite only - never raw facts, files, or audit - wrapped in a short fixed preamble telling the consuming AI it is human-curated ground truth that must not be rewritten or appended to, then a date stamp and a live pointer (`usemycontext.ai/@`). - Honesty on failure: bad token, no network, or no compiled profile yet exits non-zero with one plain-English line and never leaves a partial file. If the compiled context is not current at the source, the CLI keeps the previous session-starter file it wrote (a foreign file is never adopted), says so, and exits 0. - Deadlines: 15s per network call, 30s per run - a stalled connection fails fast instead of hanging a startup hook. - Attribution: pulls appear as their own client in the user's activity feed, separate from Claude or ChatGPT. Feed receipts are day-guarded per action, actor and project, so a run of pulls does not fill the feed with one entry each; the live last-read time updates on each one. - Exit codes: 0 ok (including kept-previous), 1 auth/network/profile failure, 2 usage error. Claude Code recipe - refresh on every session start (`.claude/settings.json`): ```json { "hooks": { "SessionStart": [ { "hooks": [ { "type": "command", "command": "npx -y usemycontext pull" } ] } ] } } ``` Then one line in `CLAUDE.md`: `Read UMC-CONTEXT.md at session start: it is my curated personal context.` Agent frameworks that read fixed bootstrap files at startup consume the pulled file the same way: `npx -y usemycontext pull --out ~/my-agent/UMC-CONTEXT.md`, then list it among the files the agent reads. The overwrite is idempotent, so a cron line or the agent's own startup script keeps it fresh. The session-starter frame itself is exported from the SDK as `renderSessionStarter` - the ONE renderer every surface uses, so the FRAME (title, preamble, markers, pointer line) of a file written by the CLI and a starter copied from the web app can never drift apart. The admission policies differ deliberately at one edge: with a composite that is not current at the source, the CLI keeps the previous file it wrote rather than overwriting it, while the web copy hands you the last compiled text and says so in its confirmation. -------------------------------------------------------------------------------- ## Quickstart - React The React hook is `useMyContextReact()` (imported from `usemycontext/react`). It creates one stable client per component instance and re-renders on every connection-state change. ```jsx import { useMyContextReact } from "usemycontext/react"; // The user supplies their UseMyContext token (they grab one at // usemycontext.ai/#/connect). This component connects, then drops the user's // compiled context + relevant passages into a system prompt. function Assistant({ token }) { const { state, connected, connect, client } = useMyContextReact(); async function run() { await connect({ token }); // v1 is TOKEN-IN const { composite } = await client.profile(); // the user's compiled context const { passages } = await client.ask("what should I keep in mind?"); const systemPrompt = `You are helping a specific person. Their context:\n${composite}\n\n` + `Relevant notes:\n${passages.map((p) => p.text).join("\n")}`; console.log(systemPrompt); // -> hand this to your LLM } return ( ); } ``` `useMyContextReact(options?)` returns: ```ts interface UseMyContextReactValue { state: ConnectState; // re-renders on change connected: boolean; // state === "connected" token: string | null; // the held token, else null client: UseMyContextClient; // the 13 tool wrappers live here connect: (args: { token: string }) => Promise; disconnect: () => void; } ``` There is also a zero-config drop-in button. It renders one `