# AdaptiqAI for Claude Code, Cline, Codex and any MCP app

Your AdaptiqAI knowledge and this conversation's memory, as tools for the
agent: an MCP server, over stdio, on the AdaptiqAI core. In Claude Code and
Codex a prompt hook adds what a server can't: `/adaptiq`, and a note on each
turn of the collections the conversation reads.

## Install

**Claude Code**

Install it as a Claude Code plugin from a marketplace that lists it (the
package carries `.claude-plugin/plugin.json`): the plugin brings the server,
`/adaptiq` and the prompt hook. Or add the server alone:

```bash
claude mcp add adaptiqai -- npx -y @adaptiqai/mcp
```

and the command and the hook as a plugin of their own, for one session or
in the launcher that starts Claude Code (Connect to app's `adaptiq-claude`
does this):

```bash
claude --plugin-dir "$(npm root -g)/@adaptiqai/mcp/claude-code"
```

`claude-code/` is a plugin with `/adaptiq` and the hook only, so a Claude Code
that starts the server itself gets no second one. Both plugins run the server
and the hook from the package with a Node.js 22 or newer: Claude Code itself
needs none, and one started from the Dock often runs without a terminal's
PATH, so `bin/adaptiqai-mcp` looks in PATH, then where Volta, fnm, asdf,
mise, Homebrew and nvm put Node.js, or takes the one `ADAPTIQAI_NODE` names
(in the `env` of Claude Code's settings). With none, the AdaptiqAI tools are
missing and the agent is told why; the hook adds nothing and holds no prompt
up. The plugins start it with `/bin/sh`, so on Windows add the server with
`claude mcp add` as above.

**Cline** (the CLI, 3.0.74)

```bash
cline mcp add adaptiqai --yes -- npx -y @adaptiqai/mcp
```

That writes `~/.cline/data/settings/cline_mcp_settings.json`:

```json
{ "mcpServers": { "adaptiqai": { "transport": { "type": "stdio", "command": "npx", "args": ["-y", "@adaptiqai/mcp"] } } } }
```

**Codex** (0.166)

Connect to app in the AdaptiqAI console sets it up in the `adaptiq` profile it
writes (`$CODEX_HOME/adaptiq.config.toml`, `codex --profile adaptiq`). By
hand, add it to the profile that runs Codex on AdaptiqAI:

```toml
[mcp_servers.adaptiqai]
command = "npx"
args = ["-y", "@adaptiqai/mcp"]
env_vars = ["CODEX_HOME", "ADAPTIQAI_API_KEY"]

[mcp_servers.adaptiqai.tools.adaptiq_knowledge]
approval_mode = "approve"

[mcp_servers.adaptiqai.tools.adaptiq_memory]
approval_mode = "approve"

[[hooks.UserPromptSubmit]]
[[hooks.UserPromptSubmit.hooks]]
type = "command"
command = "npx -y @adaptiqai/mcp hook codex"
timeout = 30
```

Codex offers an MCP server's tools in a `namespace` tool of the Responses
API (`mcp__adaptiqai`), and asks before each call of a tool that does not say
it only reads, unless `approval_mode` says otherwise; saving knowledge still
asks. Codex passes a server only a few variables of its environment, so
`CODEX_HOME`, where it keeps its conversations, is named. Codex runs a hook
only once it is trusted: it asks at start, and `/hooks` shows it. The tools
check that the thread runs on AdaptiqAI (below), so a server added elsewhere
refuses rather than act on a conversation the model never reads.

**Any other MCP app**: run `npx -y @adaptiqai/mcp` as a stdio server.

## Sign in

The server signs in with the first of these that AdaptiqAI takes. The app's
own key comes first: knowledge has to be in the workspace the app's model
reads.

- **Nothing to do when the app runs on an AdaptiqAI key the server can
  see.** Claude Code set up by the console (Connect to app's `adaptiq-claude`)
  passes its environment on to the servers and hooks it starts, and the
  server uses the key Claude Code runs on when `ANTHROPIC_BASE_URL` is
  AdaptiqAI's. Cline's OpenRouter provider, pointed at AdaptiqAI, keeps its
  key in Cline's settings. Codex hands a server no key of its own: Connect to
  app's profile starts the server, and the hook, with the key Codex runs on
  as `ADAPTIQAI_API_KEY`.
- **A key**: `ADAPTIQAI_API_KEY` in the server's environment.
- **In the browser**: `npx -y @adaptiqai/mcp login`, `/adaptiq signin`, or
  simply ask the agent for your knowledge: while the computer is signed out,
  the first tool call opens the approval page and tells the agent the code.

A key AdaptiqAI refuses (revoked in the console) gives way to the next, and
the last to the browser sign-in, so an old key never hides a working one or
a sign-in made since. One browser sign-in serves every app on this computer.
It is kept in `~/.config/adaptiq/mcp/` (under `XDG_CONFIG_HOME` when set),
readable by you alone. `npx -y @adaptiqai/mcp status` says whether this
computer is signed in, and `logout` signs it out.

## What it does

- **`adaptiq_knowledge`**: what this conversation uses; find words, ids or
  names in the text of its collections, with the exact lines as
  document:line; search your saved knowledge by name; use or stop a
  collection here.
- **`adaptiq_memory`**: how full the memory is; your saved collections; opens
  Knowledge in the browser to tidy up. It can't keep a conversation private,
  as the DeepSeek Harness and Pi plugins can: Claude Code, Cline and Codex
  send their model requests themselves, so AdaptiqAI saves what they send.
- **`adaptiq_create_knowledge`**: save material (text, files, links) as a
  collection, only when you ask for it. The server checks the request
  against your own messages in the conversation, as every AdaptiqAI plugin
  does; a yes to the agent's offer to save counts, typed or (in Codex) given
  through its question.

Otherwise the tools, their words and their answers are the ones the DeepSeek
Harness and Pi plugins have (`agentTools` in `@adaptiqai/core`).

### `/adaptiq`

In Claude Code type `/adaptiq` (the plugin lists it as `/adaptiqai:adaptiq`);
Codex keeps `/` for its own commands and refuses one it doesn't know before
any hook sees it, so there type `adaptiq` and the action. Codex 0.167 takes
no commands of your own: custom prompts are gone, and a plugin's commands
become `$` skills. The prompt hook answers it to you, and the prompt never
reaches the model:

| | |
|---|---|
| `/adaptiq` | workspace, this conversation, models and memory |
| `/adaptiq knowledge` | knowledge used here, and the collections ready to use |
| `/adaptiq use <name>` | use a collection, or an earlier conversation, here |
| `/adaptiq stop <name>` | stop using it here (nothing is deleted) |
| `/adaptiq open` | this conversation in AdaptiqAI Knowledge |
| `/adaptiq diagnostics` | a report for support, without secrets |
| `/adaptiq signin`, `signout` | connect this computer in the browser, or forget it |

The words are the core's (`runCommand`), as in every AdaptiqAI plugin.
`private` and `remember` say why they can't be had here. `adaptiqai-mcp
command <action>` answers the same in a terminal, and from Codex's `!` in the
thread it is run in.

### What the hook adds to a turn

Before a turn, the hook adds what the conversation doesn't hold yet, as
additional context for that turn. Claude Code and Codex keep it in the
conversation's transcript, which is how the hook knows it was said; after a
compaction it is said again. What can't be had at once is left out, and the
next turn asks again.

- **The note**: which ready collections the conversation reads, and that find
  looks them up: on the first turn, and again when they change (the core's
  `turnNotes`). The tool and the server's instructions lead with find too.
- **Look it up with find** (Codex): the instruction every AdaptiqAI plugin
  gives the model (the core's `KNOWLEDGE_INSTRUCTIONS`). Codex hands the
  server's instructions to the model provider only as the description of the
  tools' namespace, so the hook adds it once to the thread as well. Claude
  Code puts the server's instructions in the system prompt.
- **Another model**: when a turn runs on another model than the one the
  conversation last ran on, and AdaptiqAI keeps the conversation there, you
  are told once, in the core's words, where its memory is, how to switch back
  and how to start fresh: `AdaptiqAI: This conversation's memory is on
  <model>. Switch back: /model <its id> · Start fresh on <this model>: /new`.
  The model has it too. Codex says each turn's model; Claude Code's is read
  from its transcript, where Claude Code 2.1.308 writes `/model` with the next
  message, after the hook ran: the notice comes with the second message on
  the new model. A conversation resumed in a Claude Code started on another
  model gets it with the first.

### Earlier conversations with @

**Claude Code**: type `@` and the name of an earlier conversation: the
server offers your saved conversations on the model Claude Code runs (the
newest hundred, read as Claude Code starts it) as resources. Picking one
makes this conversation read it from memory, as `/adaptiq use <name>` does:
the prompt hook adds it, in the conversation the prompt is in, and says so to
you and the model. The resource itself tells the model what you picked;
reading it changes nothing, since a resource read doesn't say which
conversation it is for. Claude Code reads a picked resource only in its
interactive app (its print and SDK modes pass no resources), and the hook
adds the conversation either way.

**Codex** (0.167): type `@` and a word of an earlier Codex chat's title:
Codex lists its own interactive chats there as tasks (not the ones
`codex exec` ran), and writes the one picked into the prompt as a link to
its thread. A Codex chat is the AdaptiqAI conversation of the same id, so the
prompt hook makes this conversation read it from memory, as
`adaptiq use <name>` does, and says so to you and the model. A chat AdaptiqAI
doesn't keep on the model this turn runs on (one that ran on another model,
or on another provider) is passed over in silence: Codex has the model read
the chat itself (its `read_thread` tool). Codex's `@` lists no MCP
resources, so a conversation from another app is added with
`adaptiq use <name>`.

## Which conversation a call is in

MCP has no conversation id, so the server reads each app where it keeps its
own:

| | Claude Code 2.1.308 | Cline 3.0.74 | Codex 0.166 |
|---|---|---|---|
| What the app hands the server | `CLAUDE_CODE_SESSION_ID`, `CLAUDE_PROJECT_DIR` and its own environment; `_meta["claudecode/toolUseId"]` on every call | nothing (no id in the environment or `_meta`) | `_meta.threadId` and `_meta.sessionId` on every call |
| What its model requests name | `x-claude-code-session-id`, the same id | body `session_id`, only on its OpenRouter provider | body `client_metadata.thread_id`, the same thread |
| How the server finds the call's conversation | the transcript (`~/.claude/projects/…/<id>.jsonl`) that holds the call's tool-use id: Claude Code keeps the server across `/clear` and `/resume`, so the starting id goes stale, and a call no transcript holds is refused rather than put there. An agent's call is in the agent's own transcript (`<id>/subagents/…/agent-<agent>.jsonl`), and is the session `<id>.<agent>`, as the gateway names an agent's requests; what an agent saves stays the chat's | the conversation whose messages file (`~/.cline/data/sessions/<id>/<id>.messages.json`) holds the call, not answered yet: Cline writes it there a few milliseconds before it makes it. Cline's hub runs every task in one process, so when two tasks make the same call at once, or no file holds it, the record started last before this server wins: Cline starts a server for each conversation | the thread `_meta.threadId` names: an agent the chat starts is a thread of its own, as its requests are; what an agent saves stays the chat's (`_meta.sessionId`). The thread's rollout (`$CODEX_HOME/sessions/<year>/<month>/<day>/rollout-<time>-<thread>.jsonl`, under the day the thread began, which a UUIDv7 says; for another id the newest days are looked through) gives its folder, the person's messages and the model provider it runs on |
| What has to be true for it to reach the model | Claude Code on the AdaptiqAI gateway with `CLAUDE_CODE_GATEWAY_HINT_HEADERS=1` (the gateway names a chat only from `x-claude-code-request-class: main`) | Cline's OpenRouter provider with its base URL set to the AdaptiqAI gateway | Codex on a model provider whose `base_url` is the AdaptiqAI gateway, in `config.toml` or a profile beside it, with a key Connect to app made for Codex (the gateway names a thread only for one) |

When that is not so, every tool says why instead of attaching knowledge to a
conversation the model never reads; a Codex thread Codex keeps no rollout of
(`codex exec --ephemeral`) can't be checked, so it is refused too. An app
other than these three names no conversation, so its tool calls are refused
the same way. The prompt hook gets the conversation's id from the app
itself, and adds nothing to a conversation that does not reach AdaptiqAI.

The transcript also holds your own messages, which `adaptiq_create_knowledge`
checks its quote against. The server reads them on this computer, only when
the agent saves knowledge, as far back as your last messages go, and keeps
nothing of them.

## Configuration

| Variable | Default |
|---|---|
| `ADAPTIQAI_API_KEY` | none. Used when the app runs on no AdaptiqAI key the server can see, or AdaptiqAI refuses that one; else the browser sign-in |
| `ADAPTIQAI_API_BASE` | `https://api.adaptiqai.com` |
| `ADAPTIQAI_CONSOLE_URL` | `https://memory.adaptiqai.com/memory` |
| `ADAPTIQAI_NODE` | the plugin looks for a Node.js 22 or newer |

The hook reads the same variables, from the app's environment.

## Development

```bash
pnpm install
pnpm --filter @adaptiqai/mcp run build      # lib/index.js, one file with core bundled in
pnpm --filter @adaptiqai/mcp run test
claude mcp add adaptiqai-dev -- node "$PWD/packages/mcp/lib/index.js"
claude --plugin-dir "$PWD/packages/mcp/claude-code"   # /adaptiq and the hook
echo '{"session_id":"…","prompt":"/adaptiq"}' | node packages/mcp/lib/index.js hook claude-code
```

MCP over stdio is a few JSON-RPC methods (`initialize`, `ping`,
`tools/list`, `tools/call`), written by hand in `src/rpc.ts` and
`src/index.ts`: the server ships as one file with no dependencies. Claude
Code 2.1.308 asks for `server/discover` (MCP 2026-07-28) first and falls back
to `initialize` when the server does not know it, as this one does not. The
hook (`src/hook.ts`) reads the UserPromptSubmit input both apps send on stdin
and answers with their JSON: Codex checks it against its own schema, so it
gets only the fields Codex knows.
