> ## Documentation Index
> Fetch the complete documentation index at: https://help.flickwise.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect your tool

> One MCP server. Connect any AI tool to share context.

OneLamp is **one personalized MCP server**. Every tool points at the same URL and gets its curated context.

```
https://api.onelamp.ai/mcp
```

## The universal setup

Any client that supports remote MCP servers connects the same way:

**1. Add the endpoint**

Add `https://api.onelamp.ai/mcp` to your client as a remote (HTTP /
streamable) MCP server.

**2. Authorize once**

The client opens OneLamp in your browser to sign in and authorize. OneLamp is
its own OAuth 2.1 provider with Dynamic Client Registration, so there's **no
API key and no `client_id`** to paste — the client registers itself. See
[MCP & OAuth](https://help.flickwise.app/mcp.md) for the full flow.

**3. Use the tools**

The memory tools — `save_context` / `get_context` / `list_context` /
`resume_session` / `forget_context` (plus `save_session`) — appear. That's it
— your context is now portable across every client you connect.

That universal path is all most clients need. The tabs below add the
**client-specific** bits — a packaged plugin, lifecycle hooks, one-click installs —
for the few clients that offer more than "paste the URL."

## Supported AI tools

These are the **AI tools you connect *to* OneLamp** — the assistants, IDEs, and
agents that read and write your context. OneLamp works with **any client that
speaks remote MCP**, so this isn't a gate; it's the tools people most commonly
connect. The clients with a [tab below](#client-setup) (Claude Code, Codex,
Cursor, VS Code, ChatGPT, Grok) get extra automation — everything else uses the
universal setup above.

| Category | Tools |
| - | - |
| **Assistants & chat** | Claude · ChatGPT · Gemini · Grok · Perplexity · Microsoft Copilot · Mistral (Le Chat) · DeepSeek · Qwen · Kimi |
| **Coding agents & IDEs** | Claude Code · Codex · Cursor · VS Code · GitHub Copilot · Windsurf · Gemini CLI · Cline · Devin · Antigravity · Replit · v0 · Lovable |

> [!NOTE]
>
> Don't see your tool? If it supports remote (HTTP / streamable) MCP servers, it
> already works — follow [the universal setup](#the-universal-setup). The named
> tools above just have the most usage or first-class automation.

## Data sources — 195 MCP servers

Distinct from the AI tools above, **data sources connect the other direction**:
OneLamp acts as a client connecting *out* to **195 remote MCP servers** so it can
pull their documents into your Library on demand (see
[Data sources](https://help.flickwise.app/concepts/data-sources.md)). A few of them:

> Asana · Atlassian · Airtable · Box · Canva · Cloudflare · Figma · GitHub ·
> HubSpot · Linear · Neon · Notion · Railway · Slack · Stripe · Supabase ·
> Yahoo Finance — and \~180 more.

Browse and connect the full catalog from your
[Data sources](https://app.onelamp.ai/data-sources) page in the app. Any remote
MCP server works, so you can also connect one that isn't listed by URL.

## Client setup

> [tab] Claude Code
>
> The most complete client. Instead of a raw MCP config, OneLamp ships a
> **plugin** that bundles the server *and* session hooks, so context loads and
> saves automatically — no manual tool calls.
>
> ```text theme={null}
> /plugin marketplace add https://app.onelamp.ai/marketplace.json
> /plugin install onelamp@onelamp
> ```
>
> Run these in Claude Code itself (terminal or IDE extension) — `/plugin` isn't
> available in the Claude desktop app's chat.
>
> On first use, Claude Code runs the OAuth flow. Then import this project's
> existing rules once:
>
> ```text theme={null}
> /onelamp   # or the shorter alias: /ol
> ```
>
> **What the plugin adds beyond the endpoint:**
>
> * **SessionStart hook** — Claude calls `get_context` at the start of every
>   session, so it begins with your relevant context loaded.
> * **Stop hook** — Claude is nudged to `save_context` durable learnings before
>   the turn ends (once per stop cycle, loop-safe).
> * **`/onelamp` command** (alias **`/ol`**) — manual refresh plus a one-time
>   import of an existing `CLAUDE.md`, `.cursorrules`, or `AGENTS.md` into OneLamp.
>
> The hooks are **fail-open** — they never crash or trap Claude Code. This is the
> strongest auto-load/auto-save enforcement available in any client today.
>
> > [!TIP]
> >
> > Self-hosting? The plugin's `.mcp.json` points at `api.onelamp.ai/mcp` —
> > replace it with your endpoint (e.g.
> > `https://onelamp-api.<account>.workers.dev/mcp`). As a fallback you can
> > install straight from the repo: `/plugin marketplace add onelampai/onelamp`.

> [tab] Codex
>
> At **parity with the Claude Code plugin**. [Codex](https://github.com/openai/codex)
> speaks remote (streamable-HTTP) MCP natively and runs the OAuth flow itself, so
> there's no `mcp-remote` bridge and no npx — the server is just a `url`. It also
> fires **SessionStart/Stop lifecycle hooks**, so context loads and saves
> automatically.
>
> Run the idempotent installer (safe to re-run):
>
> ```bash theme={null}
> curl -fsSL https://app.onelamp.ai/codex/install.sh | bash
> ```
>
> It does three things in `~/.codex`: installs the hook scripts, registers the
> MCP server + hooks in `~/.codex/config.toml`, and appends usage guidance to
> `~/.codex/AGENTS.md` as a backstop. To set it up by hand instead, add this
> block to `~/.codex/config.toml`:
>
> ```toml theme={null}
> [mcp_servers.onelamp]
> url = "https://api.onelamp.ai/mcp"
> startup_timeout_sec = 60
> ```
>
> **What the install adds beyond the endpoint:**
>
> * **SessionStart hook** — Codex calls `get_context` at the start of every
>   session, so it begins with your relevant context loaded.
> * **Stop hook** — Codex is nudged to `save_context` durable learnings before
>   the turn ends (once per stop cycle, loop-safe).
>
> Both hooks are **fail-open** — any error exits 0 and never blocks Codex. The
> `~/.codex/AGENTS.md` guidance stays as a backstop for the window before you
> trust the hooks.

> [tab] Cursor
>
> Cursor is at **parity with Claude Code and Codex**: it speaks remote MCP and
> supports [lifecycle hooks](https://cursor.com/docs/hooks), so context loads and
> saves automatically. One idempotent command (safe to re-run) wires both:
>
> ```bash theme={null}
> curl -fsSL https://app.onelamp.ai/cursor/install.sh | bash
> ```
>
> It registers the MCP server in `~/.cursor/mcp.json` and wires
> `sessionStart` / `stop` hooks in `~/.cursor/hooks.json`:
>
> * **sessionStart hook** — returns `additional_context` so Cursor calls
>   `get_context` at the start of every conversation.
> * **stop hook** — returns a `followup_message` nudging `save_context` for
>   durable learnings (once per conversation, loop-safe).
>
> Both hooks are **fail-open** — any error exits 0 and never blocks Cursor. The
> installer also drops a `~/.cursor/onelamp/onelamp.mdc` rule as a backstop for
> the window before the hooks are trusted.
>
> Want the MCP server only (no hooks)? Add it by hand to `.cursor/mcp.json`:
>
> ```json Cursor (.cursor/mcp.json) theme={null}
> {
>   "mcpServers": {
>     "onelamp": {
>       "url": "https://api.onelamp.ai/mcp"
>     }
>   }
> }
> ```

> [tab] VS Code
>
> The fastest path is the **one-click add** button on your OneLamp
> [Connect home](https://app.onelamp.ai) — it opens VS Code with your endpoint
> preloaded. Or add it manually to `mcp.json`:
>
> ```json VS Code (mcp.json) theme={null}
> {
>   "servers": {
>     "onelamp": {
>       "type": "http",
>       "url": "https://api.onelamp.ai/mcp"
>     }
>   }
> }
> ```
>
> VS Code doesn't expose session hooks for MCP, so saving is best-effort. Add a
> rule (`.github/copilot-instructions.md`) telling the tool to call
> `get_context` at the start of a task and `save_context` when it learns
> something durable.

> [tab] ChatGPT
>
> ChatGPT speaks remote MCP and connects to the **same endpoint** as every other
> client. It's added as a **custom connector in Developer Mode** rather than via
> a config file, and — uniquely among the first-class clients — it has **no
> lifecycle hooks**, so capture is best-effort via custom instructions.
>
> **1. Enable Developer Mode**
>
> ChatGPT → **Settings → Connectors** → enable **Developer Mode** (under
> Advanced). It's currently on **Plus, Pro, and Business** plans — OpenAI
> moves this, so verify the current gating in settings.
>
> **2. Add the custom connector**
>
> Choose **Add a custom connector** and enter the OneLamp MCP URL:
>
> ```
> https://api.onelamp.ai/mcp
> ```
>
> **3. Authorize once**
>
> ChatGPT opens OneLamp in your browser to sign in and consent. OneLamp is
> its own OAuth 2.1 provider with Dynamic Client Registration — **no API key
> and no `client_id`** to paste; ChatGPT registers itself.
>
> **Capture backstop.** ChatGPT can't run code on a session boundary, so paste
> the OneLamp **custom-instructions** block into ChatGPT → **Settings →
> Personalization → Custom instructions** (or a Project's instructions). It tells
> ChatGPT to call `get_context` at the start of a task with a personal angle,
> `save_context` proactively on durable facts, and `save_session` when a
> conversation wraps up — all stamped `source_surface: "chatgpt"`:
>
> ```markdown theme={null}
> I use OneLamp (connected via MCP) as my shared context across every AI tool.
> Always pass source_surface: "chatgpt".
> - At the START of any task with a personal angle, call get_context with a short
>   query about the work. Skip generic factual questions with no personal angle.
> - Whenever I share a durable decision, preference, fact, or convention, call
>   save_context proactively. Never save secrets.
> - When I'm picking up earlier work, call resume_session.
> - When a conversation wraps up, call save_session with a brief digest.
> ```
>
> Writes surface ChatGPT's tool-confirmation modal before they run — that's
> expected; approve them. The full block lives in the
> [ChatGPT integration](https://github.com/onelampai/onelamp/blob/main/integrations/chatgpt/custom-instructions.md).
>
> > [!NOTE]
> >
> > OpenAI renamed "connectors" → "apps" in December 2025; the settings UI may
> > say either. A first-class OneLamp **app** with inline UI (built on the OpenAI
> > Apps SDK) is in progress — it will install from the ChatGPT app directory and
> > render the context pack as an interactive card. This page will cross-link it
> > once it ships.

> [tab] Grok
>
> Grok (xAI) speaks remote MCP and connects to the **same endpoint** as every
> other client, added as a **custom connector** at
> [grok.com/connectors](https://grok.com/connectors). Like ChatGPT it has **no
> lifecycle hooks**, so capture is best-effort via custom instructions.
>
> Unlike most clients, Grok's custom-connector flow **doesn't auto-register**
> (no Dynamic Client Registration), so after you paste the MCP URL it asks for
> OAuth credentials. OneLamp publishes a shared **public** OAuth client for
> Grok — there's no secret, so the values below are safe to paste as-is. You
> still sign in and consent as yourself; PKCE keeps the flow secure.
>
> **1. Add the custom connector**
>
> Grok → [Connectors](https://grok.com/connectors) → **New Connector** →
> **Custom**. Enter the OneLamp MCP URL:
>
> ```
> https://api.onelamp.ai/mcp
> ```
>
> **2. Fill in the OAuth credentials**
>
> Grok shows an **OAuth Credentials Required** form. Enter:
>
> | Field | Value |
> | - | - |
> | Client ID | `XhCQgWAIkiIfuqZWYcGJzVLTmRopEFfJ` |
> | Client Secret | *(leave blank)* |
> | Authorization Endpoint | `https://api.onelamp.ai/auth/oauth2/authorize` |
> | Token Endpoint | `https://api.onelamp.ai/auth/oauth2/token` |
> | Scopes | `openid`, `profile`, `email`, `offline_access` |
> | Token Auth Method | **none (PKCE only)** |
>
> Then click **Save & Connect**.
>
> **3. Authorize once**
>
> Grok opens OneLamp in your browser to sign in and consent. After you
> approve, the `get_context` / `save_context` tools (and the
> [Library tools](https://help.flickwise.app/tools/library)) appear in Grok.
>
> **Capture backstop.** Grok can't run code on a session boundary, so add a
> OneLamp rule to its **custom instructions** so every task loads and saves on
> its own — stamped `source_surface: "grok"`:
>
> ```markdown theme={null}
> I use OneLamp (connected via MCP) as my shared context across every AI tool.
> Always pass source_surface: "grok".
> - At the START of any task with a personal angle, call get_context with a short
>   query about the work. Skip generic factual questions with no personal angle.
> - Whenever I share a durable decision, preference, fact, or convention, call
>   save_context proactively. Never save secrets.
> - When I'm picking up earlier work, call resume_session.
> - When a conversation wraps up, call save_session with a brief digest.
> ```
>
> > [!TIP]
> >
> > The Client ID above is a **public** client (PKCE, no secret) — it only
> > identifies Grok as the app; your data is gated by your own sign-in and
> > consent. Self-hosting OneLamp? Register your own public client against your
> > deployment's `/auth/oauth2/register` with the redirect URI
> > `https://grok.com/connectors-oauth-exchange-code/` and paste that
> > `client_id` instead.

> [tab] Other clients
>
> Any client that supports remote MCP servers connects with the
> [universal setup](#the-universal-setup) above — add the endpoint, authorize,
> done. Nothing client-specific is required.
>
> Without lifecycle hooks, saving is best-effort. Add a system prompt or custom
> instruction:
>
> ```markdown theme={null}
> Use the OneLamp MCP tools to keep my context portable:
> - At the start of a task, call get_context with a short query about the work.
> - Whenever I share a durable decision, preference, or fact, call save_context.
> ```

## How reliable is auto-save?

The connection is identical everywhere; what differs is whether the client can
**enforce** load/save. Clients with deterministic lifecycle hooks enforce it;
others are nudged or best-effort.

| Client | Auto-load / auto-save | Mechanism |
| - | - | - |
| Claude Code | Deterministic | Session hooks |
| Codex | Deterministic | Session hooks |
| Cursor | Deterministic | Session hooks |
| VS Code | Nudged | Rules files |
| ChatGPT | Best-effort | Custom instructions |
| Grok | Best-effort | Custom instructions |
| Other clients | Best-effort | System prompt |

### No hooks? Add OneLamp to the system prompt

Hookless tools — browser Gemini, Perplexity, ChatGPT, Grok — can't auto-call
`get_context` / `save_context`. The fix is to add a OneLamp rule to the tool's
**system prompt** (its always-on instructions), so every task loads and saves on
its own:

* **Editors / CLIs** (Cursor, Copilot, Windsurf, Codex): a rule in the project's
  `AGENTS.md`, `.cursorrules`, `.github/copilot-instructions.md`, or
  `.windsurfrules`.
* **Browser tools** (Gemini, Perplexity, ChatGPT web): the same rule pasted into
  the tool's **custom instructions / saved info / personalization**.

The one-time [setup prompt](https://app.onelamp.ai/setup.md) sets this up for you
(editors) or hands you the exact text to paste (browser tools) — see
[Quickstart → Seed your context](https://help.flickwise.app/quickstart.md#4-seed-your-context-one-time).

> [!NOTE]
>
> Saving is idempotent and content-addressed, so a repeated or duplicate save is
> harmless — the server dedups it.

## Beyond tools

> [card] [Chrome extension](https://help.flickwise.app/integrations/chrome.md)
>
> A different surface: capture browsing context and carry chat sessions between
> AI tools. *(Coming soon.)*

> [card] [Connect your tools](https://help.flickwise.app/concepts/data-sources.md)
>
> Pull documents *in from* Notion, Drive, and Slack — OneLamp as a client of
> *your* MCP servers.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.