---
slug: folder-binding
title: "Folder binding: pinning a save target per working folder"
description: "Pin a project to a folder and the switching accident disappears structurally. Per-client setup and how to read the `binding` value."
lang: en
---


# Folder binding: pinning a save target per working folder

When you work across several projects, the most common accident by far is
**forgetting to switch and saving into the wrong project**. Folder binding
removes that accident structurally. **pin a project to a working folder** and an
AI launched in that folder only ever reads and writes that project.

> This page covers the concepts (project · Main · folder project) through to
> per-client setup. The step-by-step is most detailed for **Claude** right now;
> for the rest, follow the console's "MCP config for this project". App screens
> change between versions, but **what the console hands you is always current.**

## First: project, Main, folder project

To understand folder binding you need **three layers**, in order.

### Layer 1. Project = the way into the memory

A project is **not** a warehouse holding memories separately. It's **a door you
pass through to read and write** memory the team already owns ([Teams and
projects](teams-and-projects)).

Two things follow from that.

- **To write into a different memory, you need a different project.** The way in
  is what sets the destination. One project cannot pick between memories.
- **One memory can have several projects.** If you've divided the memory into
  sub-parts (domains, groups), you can make several ways in that all point at the
  same team memory but **land in different compartments**. Each can also carry
  its own **persona** (the role the AI takes on that way in).

### Layer 2. Main = the way in your AI is using right now

**The Main project is "the project the AI is currently using."** There is
**exactly one** per account, and **only a person, in the console**, changes it,
an AI cannot change it itself (the invariant that stops prompt injection from
hijacking where data gets written).

Every connection not bound to a folder (web apps and so on) **follows that single
Main together.**

### Layer 3. Folder project = pinning a way in to a folder

Working across several projects means **constantly changing Main, which is
inconvenient, and forgetting to switch means saving into the wrong project.**

**If your client supports it**, you can **pin a project to a working folder.** An
AI launched in that folder only ever reads and writes that project. It doesn't
touch Main, and when Main changes this folder stays put, the switching accident
disappears **structurally**.

## How it differs from Main

| | Main project | Folder binding |
|---|---|---|
| Scope | One per account: shared by every unbound client | Only that folder's connection |
| When it changes | Instantly when you switch in the console, even mid-conversation | Not until you edit the config file |
| Switching accidents | Forget and it saves in the wrong place | Structurally impossible |

The two **don't interfere.** Folder binding only sets the save path for that
connection; it doesn't touch the account's Main. Conversely, changing Main in the
console leaves a bound folder alone.

---

## Which clients support it

Folder binding requires **the client to read folder config.** Web apps have no
concept of a folder, so they always follow Main.

| Client | Folder binding | Config file |
|---|---|---|
| **Claude Code** | ✅ | `.mcp.json` |
| **Gemini CLI** | ✅ | `.gemini/settings.json` (static key recommended: see below) |
| **Cursor** | ✅ | `.cursor/mcp.json` |
| **Claude Desktop** | ✅ (`</> Code` = Claude Code) | `.mcp.json`: see [Claude Desktop](desktop-binding) |
| **ChatGPT** | ✅ **API key only** (no OAuth) | `.codex/config.toml`: see [Connecting ChatGPT](chatgpt) |
| ChatGPT classic · Claude Web · Grok | ❌ (follows Main) | - |

> **Gemini CLI should use a static key (API key).** An OAuth refresh bug makes
> project switching unstable. Issue a static key bound to this project in the
> console and it saves to this project without OAuth → [Authentication](auth).
>
> **ChatGPT cannot use the OAuth folder binding in this chapter.** Neither
> `?project=` nor the `X-K2G-Project` header attaches. The one way to pin it to a
> folder is a **project-pinned API key**, and that behaves exactly like folder
> binding per the table above. Steps → [Connecting
> ChatGPT](chatgpt). What older material called **Codex** is today's
> ChatGPT.
>
> For reference, there used to be a problem where **an OAuth local MCP overlapped
> with the account connector** and tools dropped to zero mid-session. That
> combination no longer arises (OAuth doesn't work there). **The key method can
> sit alongside the account connector**; just register the two under different
> server names → [Connecting ChatGPT](chatgpt).
>
> **When using a wrapper execution mode like Claude Desktop's Code or ChatGPT's
> Work**, you must **run the CLI first and finish approval and authentication
> there.** The wrapper doesn't show the `.mcp.json` approval prompt, so without
> approval it **silently skips that connection and falls back to the account
> connector (Main)**. Desktop steps → [Claude Desktop](desktop-binding).

## Just do what the console says

You don't need to write the config by hand. **Console → Project management →
"MCP config for this project"** has a tab per format, and each tab tells you
**which AI it's for and where to save it.**

1. Open the **project** you want to bind in the console.
2. Pick the **format tab** matching your client under **"MCP config for this
   project"**.
3. Copy it and save it at the **root of your working folder** under that file
   name.
4. **Run the AI in that folder and authenticate.**
   **With the API key method there is no authentication step**: the key already
   contains it ([Authentication](auth)).

It matters that you don't type the project name yourself. Names with spaces or
non-Latin characters need URL encoding, and the copied config already has it.

## ⚠ Check the save target before you start

If you use folder binding, build the habit of **asking your AI first, before
starting work.**

```
where are you saving right now?
```

It tells you the team and project directly. Because **a binding can be quietly
wrong without anything showing on screen**, one check before you start is far
cheaper than finding misfiled memories later. How to read the answer is in
[Confirming it attached](#confirming-it-attached) below.

---

## Folder binding in Claude

### 1. Create `.mcp.json` in the folder

Create a `.mcp.json` at the top of your working folder and put the project name
after `project=` in the URL.

```json
{
  "mcpServers": {
    "AiAkiv": {
      "type": "http",
      "url": "https://mcp.aiakiv.com/mcp?project=my-project-name"
    }
  }
}
```

If you already have a `.mcp.json`, just add the `"AiAkiv"` entry inside
`mcpServers`.

> Don't write the above by hand. Copy it from **Console → Projects → Project
> management** (the reason is in [Just do what the console
> says](#just-do-what-the-console-says)).

### 2. Run the Claude CLI in that folder

`.mcp.json` is read relative to **the folder you launched in.** Start it
elsewhere and this config isn't picked up.

```bash
cd working-folder
claude
```

On first run it asks once whether to trust this folder's MCP config. You have to
approve for it to connect.

### 3. Sign in to AiAkiv with `/mcp`

Type **`/mcp`** inside the Claude CLI to list the connected MCP servers. Pick
`AiAkiv` and authenticate; a browser opens, and signing in finishes the
connection.

Authentication is **once per account**, but which project you land in is decided
by **the folder's URL.** One sign-in, many folders.

> **The wording on screen varies by version.** Even if menu names or their order
> differ from the above, the job is always the same. **`/mcp` → pick `AiAkiv` →
> sign in via the browser.** Get those three steps right and you're set.

### 4. After that, just use it

- **Claude CLI**: relaunch in the same folder and the binding is still there.
- **Claude Desktop**: open it by opening the working folder and it reads the
  same `.mcp.json`. But the built-in `</> Code` **doesn't show the approval
  prompt, so approve in advance.** Steps and verification →
  [Claude Desktop](desktop-binding).

---

## Confirming it attached

Ask the **check target** tool ("where are you saving right now?"). The single
**`binding`** value in the response tells you what it's pinned to.

| `binding` | Meaning | If Main changes in the console |
|---|---|---|
| **`folder`** | `?project=` folder binding | **Doesn't move** |
| **`api-key`** | Project-pinned key: coordinates frozen into the key → [Authentication](auth) | **Doesn't move** |
| `main` | No binding. Follows the account-wide Main | **Moves with it** (even mid-conversation) |
| `public-read` | Reading a public memory: **saving is blocked** → [Public memory](public-memory) | - |
| `link-read` | Reading a linked partner team → [Links](links) | - |
| (none) | Self-hosted single user: not applicable | - |

The top two mean a binding is in effect. **The project name is a clue too**: if
it has **`(Main)` after it**, you're following the account Main rather than a
binding.

This check is read-only and cheap. **Ask often**: when a conversation starts,
before saving, before stating where something went. Finding memories piled into
the wrong project later costs far more.

## Common problems

- **Every tool call errors** → this happens when the project name in the URL
  doesn't match a real project. The connection itself succeeds but every tool
  call is blocked. Re-copy the name from the console. (If you renamed the project
  in the console, fix `.mcp.json` too.)
- **Two copies of the same tool appear** → folder binding and an account-level
  connector are both attached. They can point at different projects, so **don't
  mix them in one conversation.** The folder binding is the more specific intent,
  so use that one.
- **I rebound to a different project but it still saves to the old one** → edit
  `.mcp.json`, then restart Claude. If it persists, re-authenticate from `/mcp`.

## Other clients

Support is per the [Which clients support it](#which-clients-support-it) table
above. Per-client detail will be added here as it's confirmed. Until then, the
console's **"MCP config for this project"** tab is the most accurate (it gives
the format and the save location together).

## Related

- What teams and projects are, and why you split → [Teams and projects](teams-and-projects)
- When a memory you expected isn't there → [Common problems](faq)
- Creating a project and copying the connection URL → [Console](console)
- OAuth vs API keys and key hygiene → [Authentication](auth)