---
slug: app-actions
title: "The app action tool: run_aiakiv_app_action and which connections have it"
description: "The tool your AI uses to ask an AiAkiv app (such as the console app) to do something. Folder connections, API key connections and plugin installs have it; connections installed from an app directory or registered on an account (the official ChatGPT plugin, Claude on the web and mobile) do not. What you can do without it, and which connections have it. In ChatGPT you get it by connecting directly in Developer mode or by connecting a folder with an API key."
lang: en
---


# 27. The app action tool: run_aiakiv_app_action and which connections have it

When an AI creates a team, sends an invitation or takes down a card you made, it
goes through one tool: **`run_aiakiv_app_action`**. Not every connection has
this tool. This document explains what the tool is, which connections have it
and which do not, and what to do when it is missing.

> **In one line.** `run_aiakiv_app_action` is the tool an AI uses to ask an
> AiAkiv app to do something. Folder connections, API key connections and
> connections installed as a plugin in Claude Code or Cursor have it.
> Connections installed from an app directory or registered on an account (the
> plugin directory install in ChatGPT, the account connector in Claude on the
> web and in the mobile apps) do not. On those connections, saving, searching
> and creating cards still work, and you do console management in the web
> console yourself.
>
> Asking the AI to do app work such as console management through this tool is
> called **app features**. **The official ChatGPT plugin does not support app
> features.** To use app features in ChatGPT, connect directly in Developer mode
> or connect a folder with an API key (§3).

Humans and AIs read this document together. Sections 1 to 5 are for people;
**section 6 is the reference for AIs.**

---

## 1. What it is

`run_aiakiv_app_action` is **the way to ask an AiAkiv app to do something**. The
AI picks which app (`app`) and which task (`action`), and calls this tool.

- The main one is the **console app** (`app="console"`). From the conversation it
  handles teams, invitations, links, the audit trail, save target history,
  projects, the save target (Main), and the listing, deletion, search visibility
  and filing tags of cards you made → [Asking your AI to do console
  work](console-actions).
- Other AiAkiv apps are called through the same tool.

Roughly, the console app does the following.

- **Teams**: listing your teams, creating a team, sending an invitation,
  accepting or declining invitations addressed to you
- **Team links**: issuing and redeeming an invite code, accepting or rejecting a
  link, pausing and resuming it
- **Records**: reading a team's permission audit trail and your save target
  (Main) switch history
- **Projects**: creating one, setting the default project, editing a persona,
  deleting one
- **Save target**: switching and clearing Main, turning Main off and on, listing
  and hiding public targets
- **Cards**: listing the cards you made, filing tags, search visibility, taking
  one down
- **AI permissions**: checking which AI permissions you turned on

**All of this can also be done by hand in the web console (the dashboard,
[app.aiakiv.com](https://app.aiakiv.com)).** Asking the AI is a convenience.
People on a connection without this tool can do every one of these in the web
console. Deleting an account, deleting a team, transferring ownership and issuing
API keys have always been web console only.

**It is not saving.** Keeping a memory is `save_memory`, and happens only when
the user asks explicitly with `ak` ([Saving](saving)).
`run_aiakiv_app_action` does not keep memories; it runs the work an app is
responsible for. Creating a team through the console app does not create a
memory.

**Creating cards does not use this tool.** Cards are made with the dedicated
tool `create_aiakiv_card` (§4).

---

## 2. Which connections have it

There is one AiAkiv server. Which tools the AI sees depends on how the
connection was attached. Your account, your permissions and the memories you can
read are the same on every connection.

| Connection | Examples | `run_aiakiv_app_action` |
|------|-----|------|
| **Folder connection**: a connection attached with a project chosen | The `.mcp.json` in Claude Code and Claude Desktop's `</> Code`, Cursor's `.cursor/mcp.json` | **Yes** |
| **API key connection** | Gemini CLI, the ChatGPT folder connection (`.codex/config.toml`), Antigravity | **Yes** |
| **Connection installed as a plugin** | AiAkiv installed as a plugin in Claude Code or Cursor | **Yes** |
| **Direct connection in Developer mode in ChatGPT** | Developer mode turned on at the chatgpt.com web page and the address in §3 registered by hand | **Yes** |
| **Connection installed from an app directory or registered on an account** | AiAkiv Memory installed from the plugin directory in ChatGPT and ChatGPT classic, the account connector used in Claude on the web and in the mobile apps | **No** |

Any other connection attached by sign-in with only the address and no project
chosen is the same as the last row.

**The official ChatGPT plugin does not support app features.** The official
AiAkiv Memory plugin in the ChatGPT plugin directory does not support app
features (asking the AI to do app work such as console management). There are
two ways to use app features in ChatGPT: connect directly in Developer mode, or
connect a folder with an API key (§3).

The only difference between the two lists is this tool. Saving, searching,
reading full text, reading linked teams, graph queries and creating cards are
the same on every connection.

Claude Code and Claude Desktop's `</> Code` can attach a folder connection and
the account connector to the same conversation. In that case only the folder
connection has this tool → [Account connector and folder
connection](account-connector).

If you installed the plugin and this tool does not show up, the plugin may be an
older version. Update the plugin to the latest version.

### Calling it where it is missing

It does not appear in the tool list at all. If an AI remembers the name and
calls it anyway, the call is refused with the text below and **nothing happens.**

```
This tool is not available on this connection.
```

### What you can do on that connection

| What you want | On a connection without this tool |
|-------------|--------------------------|
| Save, search, correct or hide memories | Works as usual |
| Create a card | Works as usual (`create_aiakiv_card`) |
| List, delete, search visibility and filing tags for cards | Do it yourself in the web console under **Data → Cards** |
| Teams, invitations, links, projects, the save target, turning Main off and on | Do it yourself in the web console ([app.aiakiv.com](https://app.aiakiv.com)) |
| Change the save target (Main) | Change it in the console, or click the switch link (`switch_url`) the AI hands you with the project list |

---

## 3. When you need this tool

Asking an AI to do console management works on a connection that has
`run_aiakiv_app_action`: a folder connection, an API key connection, a
connection installed as a plugin, or a direct connection in Developer mode in
ChatGPT. Connections installed from an app directory or registered on an
account do not have this tool, so on those connections you manage things in the
web console yourself.

The connections that have this tool, by client:

- **Claude**: Claude Code and Claude Desktop's `</> Code` connect with a
  `.mcp.json` in the folder → [Folder binding](folder-binding),
  [Claude Desktop](desktop-binding). A connection installed as the AiAkiv
  plugin in Claude Code has it too. The account connector used in Claude on the
  web and in the mobile apps does not. When an account connector and a folder
  connection are attached together, see [Account connector and folder
  connection](account-connector).
- **ChatGPT**: the official ChatGPT plugin does not support app features. A
  connection installed with the official AiAkiv Memory plugin from the plugin
  directory does not have this tool. There are two ways to get it in ChatGPT.
  - **Connect directly in Developer mode**: at the chatgpt.com web page, turn on
    Developer mode and register the address
    `https://mcp.aiakiv.com/mcp?apps=all` yourself. It applies to your whole
    account and follows the Main project. The steps are in
    [ChatGPT](chatgpt) §6.
  - **Connect a folder with an API key**: connect with a project-pinned API key
    in the working folder's `.codex/config.toml`. That folder is pinned to one
    project. It can sit next to the plugin install, and the folder side shows up
    under a different name, `AiAkiv-<project name>` →
    [ChatGPT](chatgpt) §2 and §4.

  The plugin-installed connection and the direct connection have the same tool
  names, so turn on only one of them in a conversation.
- **Cursor**: a connection attached with the folder's `.cursor/mcp.json` and a
  connection installed as the AiAkiv plugin both have it →
  [Folder binding](folder-binding).
- **Clients that take only an API key** (Gemini CLI, Antigravity and others) →
  [Authentication](auth).

For an AI to **change** anything through the console, an API key must have been
issued with **"Allow console management by AI (manage)"** checked
([Authentication](auth)).

---

## 4. Cards have their own tool

Cards are made with **`create_aiakiv_card`**, which every connection has. Its
input fields are fixed, so there is no separate format lookup step →
[Cards](cards).

Cards used to be made with `run_aiakiv_app_action(app="card", action="create")`.
That path **still works for now**, but its response carries a note saying to use
`create_aiakiv_card` from the next request on. If an older AiAkiv skill still
uses that path, you will see the note. The card was already made, so there is
no need to ask again.

---

## 5. Permissions live in the console document

Console work through this tool has its own permissions. The **AI permissions**
attached to each action (reads on by default, edits off by default), the
**manage scope** for API keys, and the full table of actions are in [Asking your
AI to do console work](console-actions).

---

## 6. Reference for AIs

This section is read by an AI connected to AiAkiv.

### Is it there

- **Decide by whether `run_aiakiv_app_action` is in your tool list.** If it is
  not, do not call it.
- If a call returns `This tool is not available on this connection.`, **nothing
  happened.** Do not call it again.
- When asked for console work (teams, invitations, links, projects, the save
  target, managing cards) on a connection without this tool, say it cannot be
  done on this connection and point to the matching menu in the web console
  (`https://app.aiakiv.com`). Card management is under **Data → Cards**.
- When one conversation has two AiAkiv connections, check the tool list of each
  connection separately. This tool may be on the folder connection only.

### How to call

| Task | Tool |
|----|------|
| Create a card | `create_aiakiv_card(title=…, bullets=[…], conclusion=…, source_count=…, tags=[…], body=…)` → [Cards §8](cards) |
| Console work | `run_aiakiv_app_action(app="console", action="<name>", data={...})`. The action table is `action="describe"` → [Asking your AI to do console work §8](console-actions) |
| Save a memory | `save_memory`. Do not save through this tool |

- Do not create cards with `run_aiakiv_app_action(app="card", …)`. If a response
  on that path carries `next_request_note`, the card is already public. **Do not
  repeat the call.**
- On a console permission error (`console_permission_disabled`), hand the user
  `settings_url` and stop ([Asking your AI to do console work §8](console-actions)).

### Connections in short

| Connection | `run_aiakiv_app_action` |
|------|----------|
| Folder connection (a connection with a project chosen) | Yes |
| API key connection | Yes |
| Connection installed as a plugin (Claude Code, Cursor) | Yes |
| Direct connection in Developer mode in ChatGPT (§3) | Yes |
| Connection installed from an app directory or registered on an account (the plugin directory install in ChatGPT, the account connector in Claude on the web and in the mobile apps) | No |
| Any other connection attached by sign-in with no project chosen | No |

`create_aiakiv_card` is on every connection. How a connection was attached
changes only the tool list, never the account, the permissions or what can be
read.

---

## Related documents

- Console work and AI permissions → [Asking your AI to do console work](console-actions)
- Creating and managing cards → [Cards](cards)
- The tool map for AIs → [For AI agents](for-ai-agents)
- OAuth, API keys and the manage scope → [Authentication](auth)
- Folder connections → [Folder binding](folder-binding)
- Connecting ChatGPT → [ChatGPT](chatgpt)