Using project binding in Claude Desktop

`</> Code` is Claude Code. But it never shows the approval prompt: without approving in advance only the account connector is left and saves go to Main. Even when approved the account connector attaches alongside; leave it on and check where each save went.

Folder binding is known as a Claude Code thing, so people on Claude Desktop tend to assume it isn't for them. It is.

In one line. Desktop's </> Code is Claude Code. So .mcp.json folder binding works there unchanged. But the built-in Code doesn't show the approval prompt, so you have to approve in advance: and you must check the save target before starting. And your claude.ai account connector attaches alongside. Don't turn it off (that removes AiAkiv from the web and the mobile app too). The AI mostly saves through the folder connection, but that isn't enforced, so check where each save went.

What folder binding is and why it matters is in Folder binding. This page covers only the Desktop-specific part.

Why this is needed

Main, where saving points, is an account-wide pointer. Change it once in the console and every client on that account moves with it, the Desktop on your PC, the web, the CLI, all together. It can even change mid-conversation.

Binding is the only axis that escapes that. A connection with ?project= is pinned to its own project, so no matter how Main changes in the console, that connection's save target doesn't move.

Account Main  ──(global pointer)──> shared by every client, can change any time
?project=     ──(pinned to the connection)──> this one doesn't move

1. </> Code is Claude Code

The </> Code inside Claude Desktop is not a separate tool. It is Claude Code, embedded. So what works in Claude Code works here: folder binding included.

2. You can pick more than one folder

Desktop lets you select one or more working folders. Those become the session's working locations.

3. Put .mcp.json in the folder you picked

Create the project binding as .mcp.json in the selected folder and it works. The contents are identical to Claude Code's.

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

Don't type the project name: copy it from the console: Console → Projects → Project management → 'MCP config for this project'. The reason and the steps are in Folder binding.

The server name is AiAkiv-<project name>. AiAkiv-myproject in the example above is the folder connection name for a project called myproject. Copy it from the console or use Download folder ZIP and it comes with your project's name attached. Its name differs from the account connector (AiAkiv), so you can say "save through AiAkiv-myproject." The naming rule and how to rename it are in §4 of Connecting ChatGPT. If you rename it, change the name inside enabledMcpjsonServers in §4 below to match.

The folder ZIP is on both the OAuth tab and the project-pinned API key tab of the console's 'MCP config for this project'. Unzip it and put the folder where you work: it holds .mcp.json, a .claude/settings.json that approves this folder connection in advance, and the skills (.claude/skills/). The API key tab's ZIP also holds the Gemini CLI and Codex CLI config and their skills (.agents/skills/). If you haven't issued a key on that screen, the button issues one and puts it in. Once you have the ZIP, clicking 'Issue a static key for this project' revokes the key inside it.

If you picked several folders, put it in the first one if you can. That reduces confusion about which folder's config was read.

4. ⚠ You must approve in advance

This is where people get stuck most often.

Desktop's built-in Code doesn't show the .mcp.json approval prompt. In the CLI you'd be asked "do you trust the MCP servers in this folder?"; the embedded one never asks. And an unapproved MCP server is silently skipped: no error, no warning.

So what happens? Claude Code attaches the account connector you registered on claude.ai to the session separately from the server in the folder's .mcp.json. So there are two ways this fails, and in both the screen looks fine.

  • When the folder server isn't approved: the folder connection is skipped and only the account connector is left. The AiAkiv tools are still there, but saves go to Main.
  • Even when the folder server is approved: the account connector attaches alongside it, so there are two AiAkiv connections. The tool names are identical, so the AI picks which one to save through. The server tells it to prefer the folder connection, so most saves go to the folder project, but that isn't enforced and now and then a save can go to Main.

That's why you need approval first, and §8's check before you start and after your first save. Leave the account connector on: turning it off turns it off for your whole account, and AiAkiv disappears from the web and the mobile app too (When the account connector and a folder connection are both attached).

There are two ways to approve, and both write the same value to the same file.

Method A: the settings file directly

Put this in the working folder's .claude/settings.local.json.

{
  "enableAllProjectMcpServers": true
}

That auto-approves every MCP server in this project. To name servers individually, use enabledMcpjsonServers with an array of names.

{
  "enabledMcpjsonServers": ["AiAkiv-myproject"]
}

If you'd rather not edit the file, run claude once in that folder from the CLI.

cd working-folder
claude

A New MCP server found prompt appears. Approving there writes that value into the same .claude/settings.local.json: into enabledMcpjsonServers if you approve one, or enableAllProjectMcpServers: true if you approve all.

So approving once in the CLI means Desktop inherits that approval. Same result as method A, with no chance of a typo. But separately from approval, the account connector attaches alongside (in the CLI too). Read the subsection below as well.

It's convenient to finish authentication (OAuth) at the same time. In the CLI: /mcp → pick AiAkiv-myproject → sign in via the browser. Authentication is once per account, and which project you land in is set by the folder's URL: one sign-in, many folders (Authentication).

When the account connector attaches alongside

Claude Code (the terminal CLI and Desktop's </> Code) attaches your claude.ai account connector to the session separately from the server in the folder's .mcp.json. So a session that uses folder binding has two AiAkiv connections.

  • Leave the account connector on. Turning it off under the composer's + menu → Connectors turns it off for your whole account, and AiAkiv disappears from claude.ai web chat and the mobile app too.
  • With both attached, the AI saves through the folder connection first; the server tells it to. Most saves go to the folder project, but that isn't enforced.
  • So check where each save went (§8). Every save response carries its destination.
  • If saves must go to the folder only, you can also turn Main off for a while in the AiAkiv console. While it's off, the account connector refuses requests and only the folder connection works. AiAkiv on your phone and the web refuses too, so turn it back on when you use it there.

What to do when a save lands in Main, turning Main off, and the terminal setting that blocks the account connector in one folder only → When the account connector and a folder connection are both attached.

5. How approval is decided

In order:

Condition Result
Listed in disabledMcpjsonServers Rejected
Listed in enabledMcpjsonServers or enableAllProjectMcpServers: true Approved
Otherwise Pending: a prompt in the CLI, silently skipped in the embedded Code

A server you once rejected stays in disabledMcpjsonServers. If you approved it and it still doesn't attach, check whether the name is stuck there.

6. The setup with no authentication at all: API keys

Everything so far is the OAuth setup: a sign-in window once, and from then on the system verifies identity for you.

But there's also a setup with no authentication step at all: issue an API key pinned to that project in the console and paste it into the config.

{
  "mcpServers": {
    "AiAkiv-myproject": {
      "type": "http",
      "url": "https://mcp.aiakiv.com/mcp",
      "headers": { "Authorization": "Bearer <your key>" }
    }
  }
}

Copy this snippet from the console too. In Project management → 'MCP config for this project', choose the client and format and it comes out with the key already in it. Don't type it.

  • No sign-in window. Authentication is already inside the key (Authentication). Nothing to authenticate with /mcp, no browser to open. paste it and it works.
  • The project is pinned into the key. Issue one key per project and each config goes to its own project without using ?project=. The check-target tool shows binding as "api-key": isomorphic to folder binding, and it doesn't move when Main changes in the console.
  • It doesn't remove the approval issue. §4 and §5 are about whether .mcp.json is read at all, so they still apply with a key. What disappears is the authentication step.

⚠ The key is your ID card. Leaking it means handing over access to your memory wholesale: don't commit the config file. The full minimum is in Key hygiene in Authentication.

To summarize:

OAuth API key
Authentication One sign-in window None: it's in the key
Project pinning Via ?project= In the key itself
Secrets to manage None The key: you're responsible for storing it

7. ChatGPT and ChatGPT classic take a different setup

Everything above (§1–§6) is about Claude. The OpenAI side branches differently.

  • ChatGPT and ChatGPT classic both attach by installing AiAkiv Memory from the plugin directory inside the app. You sign in over OAuth, and one install applies account-wide, visible on the web and in both apps. Saves follow Main.
  • To pin a project per folder, put a project-pinned API key like §6's in the folder's .codex/config.toml, on the ChatGPT app. OAuth cannot pin a project per folder.
  • App features (asking the AI to do app work such as console management) are not supported by the official ChatGPT plugin. To use them, connect Codex with the install prompt or connect a folder with an API key.
  • The two setups can sit side by side, because their MCP server names differ (global AiAkiv / folder AiAkiv-<project name>, e.g. AiAkiv-k2g). With different names you can say which one to use. With the same name there's no way to.
  • In Claude the folder connection is named by the same rule (AiAkiv-<project name>). But in Claude the AI can still use the account connector even with different names, so leave the account connector on and check where each save went → When the account connector and a folder connection are both attached.
  • In the ChatGPT desktop app both connections show up. It sees the account-wide connection (the AiAkiv plugin, which follows Main) and the folder connection from the folder's .codex/config.toml at the same time. Name the folder side (e.g. AiAkiv-k2g) and it works pinned to that project. The Codex CLI works through the folder connection, and reads the config only once you trust the folder.

Steps and cautions are collected separately → Connecting ChatGPT

8. ⚠ Always check the save target before you start

As said above, a failed binding makes no sound. Checking is the only way to notice. Check two things in order.

First, before you start work, check that the folder connection attached. Look for the AiAkiv from the folder's .mcp.json in the /mcp list, or ask for the save target.

where are you saving right now?

The AI calls get_save_target and reports back. Two things to look at.

  • binding is "folder": pinned via ?project=. If you attached with an API key it shows "api-key": also pinned.
  • No (Main) suffix on the project name: a suffix means it's following the global Main, so the binding didn't take.

If the account connector attached alongside and there are two AiAkiv connections, this answer comes back folder or main depending on which connection it asked. Having two isn't a problem in itself. But if the folder's AiAkiv isn't in the list at all and the answer is always binding: "main" or carries (Main), the folder connection didn't attach, so go back to §4's approval.

Then, after your first save, check where it went. Every save response carries its destination (team, project, binding). Look at the project name the AI reports, or ask.

where did that just get saved?

If binding is "folder" (or "api-key") and the name has no (Main), it went to the folder project. The AI mostly saves through the folder connection, but that isn't enforced, so this check is the last safeguard. If it went to Main → When a save lands in Main in When the account connector and a folder connection are both attached.

Every value binding can take, and what each means, is in Confirming it attached in Folder binding.

Common problems

  • The tools are there but it saves to the wrong project. One of two cases. Either the folder server wasn't approved and only the account connector is left (check §4's approval), or it was approved but the account connector attached alongside and the AI used that one. In the second case, save it again through the folder connection and check where it went (→ When the account connector and a folder connection are both attached).
  • It works in the CLI but not in Desktop. The CLI gets approval through a prompt and Desktop can't. Approve once in the CLI (method B) and Desktop inherits that approval. But a setting you used in the CLI to block the account connector in one folder doesn't reach Desktop. In Desktop, work with both connections attached and check where each save went (§8).
  • I turned AiAkiv off under Connectors and it disappeared on the web and mobile too. + menu → Connectors is an account-wide setting. Turn it back on in the same menu.
  • I picked several folders and don't know which config was read. Put it in the first folder per §3, and check the actual target per §8.
  • These steps don't match ChatGPT or ChatGPT classic. Their setup differs. See §7 and go to Connecting ChatGPT.
  • It says the project name can't be found. Names are looked up only among projects you own. It may be a typo, or a project on a different account. Copy it from the console.
Full index → Docs View as Markdown