---
title: Setup for each app
nav: Setup for each app
group: Guides
order: 1.5
---
# Setup for each app

Just want to connect? [Pick your assistant](/docs/) and copy one thing. This
page is the full detail for each app, for your agent or whoever sets it up.

Already connected? Try [your first task](/docs/first-task), or check the
connection with [the thin-client prompt](#try-a-thin-client-now). The
[architecture diagram](/mainmind-harnesses.svg) shows the two paths below.

## Technical setup and working paths

The sections below are for the acting agent or a person configuring an AI app.
Read an applicable Process when a task needs one; an empty space does not need
a business Process invented merely to connect or save basic work. Keep secrets
out of prompts and saved knowledge. Mainmind supplies context and records;
it does not start a host or schedule the agent.

Choose by the tools actually enabled in this session, not its product name.
A chat host can have other execution capabilities; here **MCP-only** means
deliberately using only Mainmind's exposed MCP tools.

| Path | What the agent uses | Start here |
|---|---|---|
| MCP-only | Knowledge, runs, governed knowledge changes and feedback; granted provider calls for an Owner | Any client with remote MCP enabled and no checkout |
| Git plus MCP | The same Mainmind connection, plus a permitted checkout and a terminal for local tool code | A terminal-capable host |

Host-specific connect steps are below, because those commands differ.

Live ops boards (Slack, cron health, a vendor dashboard) stay out of Mainmind
until they are deposited into the space's knowledge or reached via `call_provider`
on a connected account. Mainmind does not mirror those boards.

**Owner provider access:** Use the exposed
`list_provider_connections`, then `call_provider` for an installed, granted
provider — unless the System record's `tool-route` names a CLI for that act,
in which case follow the CLI and do not invent a gateway call. To attach a write to an open task, pass that task's `run_id` and
`control_key`. Omit `run_id` for an independent operation receipt, with
no `run_start` or `run_finish`. Before a write, choose a unique
`operation_key`; repeating that key returns recovery information without
sending again, including after a timeout. Do not mint a new key to recover.
Inspect the receipt and verify the provider object. Recovery
is not a cached response or proof of success. This uses the same gateway as local tools without a checkout,
terminal or extra credential. It does not execute local tool code. Read the
Process and provider instructions before a call; written knowledge and a
connection list are not live business evidence. If a required manual or tool
is unavailable, report the gap instead of guessing.

Terminal-capable hosts can use installed, granted provider adapters through
Mainmind's HTTP gateway. Check the issued capabilities: tool files do not
grant provider access. A teammate's member lease currently carries no vendor
capabilities; a co-owner's carries what the Owner's carries. Neither path has a blanket promise that every provider operation
or fresh client installation has passed acceptance.

## Connect once per client

Use the complete space URL from **Accounts** in [your space](/app):

```text
https://mainmind.app/mcp/<space>
```

If any space placeholders remain, replace them with the identifier
shown in Accounts before copying commands or prompts. This page fills them in
when you are signed in to exactly one space; if you hold several,
choose the intended one yourself.
Name the connection `Mainmind — <space>`.

The relative path `/mcp` alone is not a complete URL. The full address
`https://mainmind.app/mcp` is the one to use if you keep more than one
space: it asks which space to connect, then lists the others this
connection could reach so you can tick the ones it should. It holds the ones
you tick and serves one at a time, switched with `use_organization`; tick none
and it is fixed to one space, like the URL above. Prefer the complete
space-specific URL when a connection should never reach anything else.
Do not use a Git clone URL, an app page, or a GitHub URL. Pasting the URL into
a conversation does not install a connection. Verify the returned identity
rather than trusting the display name you typed.

Complete Mainmind's authorization in the browser your harness opens: continue
with GitHub. An invited member does this too, not a repository token — the
first time, open the Owner's invitation link once to bind this GitHub
account to the membership; every connection after that is the same GitHub
sign-in. No GitHub repository access or vendor credential belongs in a
consumer setup.

Keep existing client configuration; add one entry rather than replacing a
configuration file. If Mainmind is already configured by a plugin, reuse that
connection instead of adding a duplicate. Never copy tokens, invite codes or
lease exports into chat, screenshots, Git or shared configuration.

A connection that names no scopes follows that person's live role, including
team administration for an Owner; the consent screen shows the role before
anything is granted. Existing limited grants stay limited until reauthorized. The
[authentication guide](/docs/using-the-api#choose-personal-connection-access)
explains consent and migration.

For persistent agents, authenticate the person once and use distinct stable
profiles through that role-following connection. Each supported call selects
the exact profile; the profile adds no permission and never turns into a
separate login. [Persistent agents](/docs/persistent-agents) owns registration,
sync and presence. Ordinary chats and temporary helpers do not create profiles.

Legacy machine members with independent `mmkey_` credentials remain supported
for static-bearer and API runners through the
[machine connection flow](/docs/using-the-api#connect-a-standing-bot). Never
copy a person's OAuth token into such a runner. Do not reuse an MCP session ID
across sessions; a run and its private control key stay with the session that
opened them.

Reads overlap. Knowledge tools marked read-only (`boot`, `search`,
`read_node`, and the others with `readOnlyHint`) prove they read one
projection generation and do not take the exclusive workspace lease. Two
agents can read at the same time. If a publication lands mid-read, Mainmind
discards the mixed result and retries once. You may still see "the projection
was republished while this read was in flight"; retry the call.

Notes and routine task work overlap. You can save or retract a note, record an
event, start a task, send its heartbeat, or finish it while another agent lands
or deposits knowledge. Each save checks the publication and your live access.
A task cannot finish while one of its own writes is still in flight.
Completed calls with uncertain effects remain partial evidence in its closing
receipt. An unrelated task does not block it.

A refusal can report that no handler started while its receipt cancellation
remains unconfirmed. Retain the private recovery token from that response and
pass it as `receipt_recovery` to `run_finish` for the named run. A declared
task still requires your `control_key`. For a task-free call, supply the
`control_key` if the refusal returned one; otherwise use its original session. Keep the token if recovery is also unconfirmed. This settles only the
refused reservation; it cannot cancel an effect that actually started.

Canonical writes can still conflict. While a landing, deposit or other governed
change holds the workspace lease, a competing call waits a bounded time for
that holder. If the lease is still held it returns
`Another organizational knowledge call is still finishing: projection is busy with mcp:<tool>`.
Wait for that call, then inspect before retrying. If a ledger response says the
change was saved or its outcome is unconfirmed, inspect its note, event or run
first. Retain any returned task receipt and private control key. Mainmind never
replays a write automatically. A typed deposit releases its lease after Git
confirms the save, while knowledge refresh admission continues separately.
Keep the saved receipt: it does not yet prove the new knowledge is readable.
Separate machine members preserve ownership; they do not bypass conflicts on
the same canonical repository. A pending canonical landing releases the lease
while Git finishes and returns a `landing_id`. Poll `checkout_change_status`
with that id; Git still checks for competing changes before saving.

A rebuild pauses knowledge. While a projection refresh is in progress,
knowledge-dependent tools refuse with
`projection refresh in progress for <commit>; no partial knowledge was returned`.
Wait until the new commit is serving. Do not answer from memory.

Provider calls are not that lease. `list_provider_connections`,
`call_provider`, `issue_tool_permit` and `feedback` do not take the
knowledge-projection lease. `call_provider` writes still use `operation_key`.
Error shapes are on [Sign-in and errors](/docs/using-the-api).

### Codex

Codex supports plugins. Before changing MCP configuration, run:

```sh
codex plugin list
```

If it lists `mainmind@mainmind`, reuse that installation and skip the direct MCP
and manual-skills setup below. The plugin packages a Mainmind server entry and
the boot skills. Do not add the same server or copy the same skills again.

If the plugin is absent, install it. Codex reads the Claude Code marketplace in
[codeyogi911/mainmind-plugins](https://github.com/codeyogi911/mainmind-plugins)
and installs `plugins/mainmind` with its skills. The first two commands were
run in a clean home with Codex CLI 0.156.1; the third opens Mainmind's sign-in
in your browser:

```sh
codex plugin marketplace add codeyogi911/mainmind-plugins
codex plugin add mainmind@mainmind
codex mcp login mainmind
```

If `codex mcp login` stops with "missing required issuer", your Codex is older
than 0.156.1. Upgrade Codex and run the login again.

For the connection alone, without the skills, run
`codex mcp add mainmind --url https://mainmind.app/mcp` in place of the two
plugin commands, then the same `codex mcp login mainmind`.

The plugin's server entry is named `mainmind` and uses the general address,
so sign-in asks which space to connect. To pin one space, add the remote
server yourself on the host where Codex runs instead:

```sh
codex mcp list
codex mcp add "mainmind-<space>" --url "https://mainmind.app/mcp/<space>"
codex mcp login "mainmind-<space>"
```

You do not choose permissions. Mainmind's sign-in page shows your role in
that space, and after you allow it the connection can do what your role can
do, and follows your role if it changes. To give an assistant less than your
role on purpose, see [limited connections](/docs/using-the-api#oauth-scopes).

Alternatively, merge this entry into your Codex configuration, then run the
login command. Use this instead of adding the same server twice:

```toml
[mcp_servers."mainmind-<space>"]
url = "https://mainmind.app/mcp/<space>"
```

Codex's local clients share configuration on the same host; a separate remote
host is a separate setup. A cloud task must actually expose the connection;
local settings alone do not prove that.
[Official Codex MCP guide](https://developers.openai.com/codex/mcp).

To add the boot discipline without a plugin, copy the *contents* of
[codeyogi911/mainmind-plugins](https://github.com/codeyogi911/mainmind-plugins)
`.agents/skills/` into the repository's `.agents/skills/`, or into
`~/.agents/skills/` for every project. Each skill must end up at
`.agents/skills/<name>/SKILL.md`; copying the directory onto itself gives
`.agents/skills/skills/<name>/SKILL.md`, which Codex does not read.
[Official Codex plugin guide](https://developers.openai.com/plugins/build/plugins).

Installation, account connection and intended persistent work are separate.
After either setup route, open a fresh task, check `/mcp` in the CLI or the app's
connection controls, complete OAuth if needed, then call `whoami` and `boot`.
Those calls prove that this task reached the intended Mainmind account and
space. Installing a plugin alone does not authenticate an account or
establish persistent work. The task keeps the account's real identity and
permissions; a standing agent's identity and activity require separate
verification. See [Persistent agents](/docs/persistent-agents).

### Claude Code

Add a user-scoped HTTP server, then open Claude Code and use `/mcp` to complete
its authentication flow:

```sh
claude mcp add --transport http --scope user "mainmind-<space>" "https://mainmind.app/mcp/<space>"
```

User scope makes this entry available across your local projects. A shared
project entry is a different choice; do not distribute authentication material
with it. No Mainmind plugin is required for the plain remote MCP path.
[Official Claude Code MCP guide](https://code.claude.com/docs/en/mcp).

The plugin is the other route, and it adds what the Mainmind connection cannot: the skills
that tell an agent to try a checkout before working through Mainmind, and how to
read a start-of-day brief.

```sh
/plugin marketplace add codeyogi911/mainmind-plugins
/plugin install mainmind@mainmind
```

From a terminal, the same two steps are
`claude plugin marketplace add codeyogi911/mainmind-plugins && claude plugin install mainmind@mainmind`.

For the connection alone, without the plugin, run
`claude mcp add --transport http mainmind https://mainmind.app/mcp`, then use
`/mcp` to sign in. It asks which space to connect.

The `@mainmind` suffix names the marketplace the plugin came from. The bare
`/plugin install mainmind` usually resolves too, but only once that marketplace
has been refreshed, so the qualified form is the one to follow.

It ships no secrets; you still authenticate as yourself. The plugins live in
[codeyogi911/mainmind-plugins](https://github.com/codeyogi911/mainmind-plugins),
a separate public MIT repository. **They used to live in Mainmind's own
repository.** If you installed from that path, point the marketplace at the
line above instead; the old location no longer carries them.

### Cowork and Claude chat

In Claude's **Customize → Connectors**, add a custom connector with the full
space URL, connect it and complete Mainmind authorization. A Claude Team or
Enterprise owner may need to add the connector first.
Enable it for the particular conversation, then use the thin-client prompt.
These are account-managed remote connectors, not a local server entry in a
desktop configuration file. Network reachability from your laptop alone does
not prove the remote connector can connect.
[Official Claude connector guide](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp).

### ChatGPT and ChatGPT Work

Where your plan and workspace allow custom plugins, OpenAI's current documented
setup is **Settings → Security and login → Developer mode**, then the plus
button in [ChatGPT Plugins](https://chatgpt.com/plugins). Create a connection
using the full Mainmind space URL and complete authorization. In a new
conversation, select the plugin from the composer's **+ → More** menu.
[Official connection instructions](https://developers.openai.com/plugins/build/app-quickstart#connect-your-mcp-server-in-chatgpt).

For a Work task, verify that Mainmind is available in that task's actual tool
list before starting. Availability depends on plan, workspace policy and
surface; a successful setup in Chat does not prove Work access. If the custom
connection option or tools are absent, ask the workspace administrator to
enable the supported route. Do not substitute a local secret or another
provider connector and call that an MCP-only Mainmind test.
[Official Work access guidance](https://learn.chatgpt.com/docs/enterprise/work-admin-faq).

### Hermes

Merge the following into `~/.hermes/config.yaml`, then start `hermes chat` and
complete the first connection's OAuth flow:

```yaml
mcp_servers:
  mainmind-<space>:
    url: https://mainmind.app/mcp/<space>
    auth: oauth
```

A remote/headless host may need the callback setup described by Hermes; do
not paste authorization callbacks into an agent prompt. Verify the connection, then
use the terminal prompt below if that Hermes session has a terminal.
[Official Hermes MCP guide](https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp/).

### Cursor

The plugin is the first route, because it brings the skills with the
connection. [codeyogi911/mainmind-plugins](https://github.com/codeyogi911/mainmind-plugins)
lists `plugins/mainmind-mount` in `.cursor-plugin/marketplace.json`, and that
directory carries both Cursor's `.cursor-plugin/plugin.json` and the
[Agent Plugins](https://agent-plugins.org) 1.0.0 `plugin.json`, sharing one
`mcp.json` and one `skills/`. It is public and MIT, so using it needs no access
from us.

- **On a Cursor team.** An admin opens **Dashboard → Plugins & MCPs**, chooses
  **Add Marketplace**, then **Import from Repo**, and pastes
  `https://github.com/codeyogi911/mainmind-plugins`. Members then add
  Mainmind from **Plugins**. This is also the route for
  [Grok Bot](#grok).
- **On your own.** Copy that directory to
  `~/.cursor/plugins/local/mainmind`, then restart Cursor or run
  **Developer: Reload Window**, and check **Customize** lists it:

  ```sh
  d=$(mktemp -d) && git clone --depth 1 https://github.com/codeyogi911/mainmind-plugins "$d" && mkdir -p ~/.cursor/plugins/local/mainmind && cp -R "$d/plugins/mainmind-mount/." ~/.cursor/plugins/local/mainmind
  ```

  On Windows, copy the contents of that same directory, including the
  `.cursor-plugin` folder, into `%USERPROFILE%\.cursor\plugins\local\mainmind`,
  so that `plugin.json` sits directly in that folder.

Mainmind is not in Cursor's public Marketplace yet.
[Official Cursor plugins guide](https://cursor.com/docs/plugins).

For the connection alone, use this button on a computer where Cursor is
installed:

[Add Mainmind to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=mainmind&config=eyJ1cmwiOiJodHRwczovL21haW5taW5kLmFwcC9tY3AifQ==)

Or merge a remote MCP entry into `.cursor/mcp.json` for
a project or `~/.cursor/mcp.json` for your user, then authenticate through
Cursor's OAuth controls:

```json
{
  "mcpServers": {
    "mainmind-<space>": {
      "url": "https://mainmind.app/mcp/<space>"
    }
  }
}
```

Other clients implementing the Agent Plugins standard can load the same
directory; [agent-plugins.org](https://agent-plugins.org)
has the install route for each. Cursor is
reported to prefer its own OAuth flow over a configured `headers` entry when a
server publishes authorization metadata, which Mainmind does; treat OAuth as
the route here rather than planning on a static header. Anyone who
connects with the entry above is offered their own role on Mainmind's consent
screen; for an Owner that covers `list_members` and team management. An older
limited grant without `mainmind:team.read` cannot call `list_members`. Mainmind cannot silently widen
that grant. Disconnect and [connect again](/docs/using-the-api#choose-personal-connection-access)
without naming scopes to follow your role. Then register or reuse the intended profile
through [Persistent agents](/docs/persistent-agents). A static-bearer runner
still uses the separate
[machine-member flow](/docs/using-the-api#connect-a-standing-bot).
[Official Cursor MCP guide](https://cursor.com/docs/mcp).

### Grok

Four surfaces, four setups, one Mainmind connection. A limited grant without
`mainmind:team.read` cannot call `list_members`. Signing in offers your own
role on the [consent screen](/docs/using-the-api#choose-personal-connection-access).
Grok web or Build can register or reuse an owner-connected profile through
[Persistent agents](/docs/persistent-agents). A custom API runner without OAuth
uses the separate [machine-member flow](/docs/using-the-api#connect-a-standing-bot).

**Grok on the web.** Open **grok.com/connectors**, choose **New Connector**,
then **Custom**, enter the complete space URL, and complete Mainmind's
authorization in the flow Grok opens. xAI's custom-MCP page says a server
requiring OAuth or API keys completes that flow in Grok after the URL is given,
and that the server must be reachable over the public internet, which Mainmind
is. xAI documents this screen for the web; whether the iOS and Android apps
expose the same one is not something its docs state, so this guide does not
claim it. On Grok Business and Enterprise a team admin with Team Read-Write
adds the connector before members can use it.
[Official Grok connector guide](https://docs.x.ai/grok/connectors).

**Grok Bot in Cursor.** Grok Bot is Cursor's assistant, and it adds tools
only as plugins: from Cursor's public Marketplace, or from a team marketplace
an admin set up. It inherits the team's Cursor connector policy. So on a Cursor
Teams or Enterprise plan, the admin imports Mainmind as described under
[Cursor](#cursor), and each person then selects **Plugins** in Grok Bot, adds
Mainmind and authorizes it in the browser. On a personal plan Grok Bot cannot
add Mainmind until it is listed in Cursor's public Marketplace, which it is not
yet. [Official Grok Bot plugin guide](https://cursor.com/help/grok-bot/connect-plugins).

**Grok Build, the coding agent.** The plugin is the first route, because it
brings the skills with the connection. Grok Build loads plugins from
`~/.grok/plugins/`, so copy `plugins/mainmind-grok` there as `mainmind`,
restart Grok Build, check `/plugins` lists it, then open `/mcps` and sign in:

```sh
d=$(mktemp -d) && git clone --depth 1 https://github.com/codeyogi911/mainmind-plugins "$d" && mkdir -p ~/.grok/plugins/mainmind && cp -R "$d/plugins/mainmind-grok/." ~/.grok/plugins/mainmind
```

Grok Build also reads Claude Code plugins, so if Mainmind's Claude Code plugin
is installed on that computer, `/plugins` may list it already.
[Official Grok Build plugins guide](https://docs.x.ai/build/features/skills-plugins-marketplaces).

For the connection alone, add the remote server, then complete the browser
flow it opens on first use:

```sh
grok mcp add --transport http "mainmind-<space>" "https://mainmind.app/mcp/<space>"
```

The Grok plugin lives at `plugins/mainmind-grok` in
[codeyogi911/mainmind-plugins](https://github.com/codeyogi911/mainmind-plugins),
public and MIT. It carries the server entry and the `skills/` that give a Grok
Build session the same boot discipline the Claude Code plugin installs —
including trying a checkout before working through Mainmind, which matters here
because Grok Build has a shell and the connector surfaces do not. It is its
own directory rather than shared with the Agent Plugins one under Cursor
above, because the two
ecosystems spell this server's transport differently and one directory holding
both spellings is a trap rather than a saving; that repository's README is the
file that tracks what each Grok surface actually reads. xAI indexes plugins in
its own catalogue,
[xai-org/plugin-marketplace](https://github.com/xai-org/plugin-marketplace).

An entry there names a repository and a full 40-character commit `sha`, and
may add a `path` naming the directory inside it that holds the plugin, which
is how a plugin in a subdirectory is listed. Several live entries are that
shape, one of them a plugin under `plugins/<name>` in a multi-plugin
repository — the layout the repository above uses. So listing Mainmind needs
no second repository and no copy vendored into xAI's own: the entry points at
`plugins/mainmind-grok` in the repository above, at a pinned commit, and the
skills stay single-sourced there.

That `path` key is absent from xAI's written schema, which documents `path`
only for vendored entries. It is validated for remote sources by the
catalogue's own validator and honoured by its index generator, and the entries
using it are the evidence; this is read from that code, not from xAI's
documentation.

Mainmind is not listed there yet, so today you copy
`plugins/mainmind-grok` as above, or use the `grok mcp add` command.

Grok Build keeps the resulting tokens itself and also reads Cursor's
`.cursor/mcp.json`. If you already configured Cursor on that host, look for the
entry you have before adding a second one.
[Official Grok Build MCP guide](https://docs.x.ai/build/features/mcp-servers).

**A bot you build on the xAI API.** Pass the Mainmind connection as a remote MCP tool with
`server_url`, `server_label` and `authorization`. That field takes the **raw**
credential, not a header value: xAI writes the `Authorization` header itself, so
a value beginning `Bearer ` arrives doubled and Mainmind refuses it. That
surface runs no OAuth, so it cannot use an owner-connected profile through a
person's connection. It needs its own scoped legacy machine identity. Use the
[machine-member flow](/docs/using-the-api#connect-a-standing-bot), then configure
the runner with that member's credential. Never
Mainmind's deployment credential, and never a person's token. Start by naming
the read set and widen it once the bot behaves — the field is `allowed_tools`
on the OpenAI-compatible Responses API shape and `allowed_tool_names` in xAI's
own SDK, so check which one your client speaks rather than assuming.
[Official remote MCP tools guide](https://docs.x.ai/developers/tools/remote-mcp).

### Muse

[Muse](https://muse.ai) is Meta's assistant, and it takes connectors. Add one
yourself with the complete space URL. The Mainmind connection is an OAuth 2.1 server,
so connecting means completing a browser authorization; Meta documents nothing
about what its connector screen supports, so treat that step as unverified
until you have done it once. Meta does not review connectors added this way,
so you are trusting the service directly.

Muse is a connection-only surface: no shell, no filesystem, no Git client, so no
checkout. `read_node`, `search` and `call_provider` are the whole surface, and
an agent there should say plainly that it is working only through the Mainmind connection. The space's
own command-line tools, under `tools/`, are invisible from it — which is not
the same as absent.

Meta publishes no connector manifest format and no developer documentation for
the directory programme, so
[codeyogi911/mainmind-plugins](https://github.com/codeyogi911/mainmind-plugins)
carries `plugins/mainmind-muse` as the connection itself plus the submission
dossier, rather than a file shaped like a manifest nobody reads.
[Muse platform](https://muse.ai/platform).

### Set up by pasting one prompt

In a host that can edit its own configuration — Grok Build, Cursor, Claude Code,
Codex — paste this and let the agent verify the connection. Then continue
with [one useful task](/docs/first-task). Replace
the space placeholder first if this page has not filled it in for you.

```text
Add Mainmind as a remote MCP server in this client, then verify it.

Add one entry named "mainmind-<space>" pointing at
https://mainmind.app/mcp/<space> over Streamable HTTP. Use this
client's own documented MCP configuration. Do not invent a configuration
format and do not replace a configuration file: merge one entry. If an entry
for this URL already exists, keep it and go straight to verification.

Authentication is OAuth. Open the sign-in flow this client provides and let me
complete it in the browser. Never ask me to paste a token, an invite code or
any credential into this conversation, and never write one into a
configuration file, a commit or a log.

Then verify and report exactly what you find. Call whoami and state the
space and my live role. Call boot and state the commit it names. If the
space is not <space>, stop and say so without reading its
knowledge.

Do not read or summarize knowledge in this task: making the connection
and proving the identity is the whole job. If a step fails, report the exact
failure and what remains unverified instead of working around it.
```

A chat surface cannot install its own connector. On Grok web, Cowork, Claude
chat or ChatGPT, add the connection through the settings screen named above
first, then use [the thin-client prompt](#try-a-thin-client-now).

### Other harnesses

For any other host, use its documented **remote Streamable HTTP MCP + OAuth**
setup with the same URL. This guide does not claim universal compatibility. If
a host supports only a static bearer, it needs a separately provisioned scoped
legacy machine identity (`mmkey_`) and can start over HTTP (`GET /api/boot`);
owner-connected profile selection is not an HTTP bearer contract. Never use
Mainmind's deployment credential. If it cannot
connect, report that limit and use a supported host rather than weakening
authentication.

## Try a thin client now

Paste this into a fresh MCP-only session. It tests
knowledge, the run ledger and an optional permitted provider read; it does not authorize invoice, stock or other
business-system changes, or a test Record in the knowledge repository.

```text
Use only the connected Mainmind MCP for this task. Do not use a terminal,
local files, web searches, other connectors or remembered facts.

Verify with whoami that the space is <space> and state my
live role. If it differs, stop without reading knowledge. Boot.
Find and read the current Process for reviewing the catalog and closing a
wholesale order. If there is no matching Process,
follow the space's unmatched-task rule; do not invent one.

If my role and tools permit, label this session's run as a read-only
catalog readiness check. From the written Process, explain what evidence
proves an order fully closed, which systems must be checked, and which
actions need human approval. Cite the exact source paths and freshness.

Distinguish written procedures from live business data. Do not claim the
catalog is current or any current invoice, refund or stock balance is correct
unless you actually read the required live evidence through Mainmind.
If I am the Owner and the provider tools are exposed, discover the granted
connections for this run. When the Process and accessible provider manual
establish a safe, small GET request, make one through call_provider and keep
its result and receipt. Do not guess a route, make provider writes or use a
local secret. If a tool, grant or required manual is unavailable, say exactly
what remains unverified.

If Mainmind fails, submit sanitized feedback if available: tool, expected
behavior and actual failure, with no customer data or credentials. Keep
the receipt. If even feedback fails, say it was not recorded.
Close only this session's run truthfully if one was labelled. Return:
what worked, what is blocked, evidence references, and the next safe step.
```

Success is verified identity, a freshly read Process and a cited readiness
check with honest limits. Refusing to invent current business data is correct
behavior, not failure. If a tool returns only a card, ask for its text result;
if essential fields are missing, report the portability gap. A healthy URL or
visible tool list alone is not success.

## Try a terminal-capable session

### Owner: keep one knowledge checkout

For ordinary knowledge and tool-code work, use the Owner's standing checkout.
You do not need to start a business run just to clone or edit files. Paste:

```text
Use Mainmind for <space>. Call whoami and verify that I am the Owner
in that space before reading knowledge. Boot.

Call checkout_canonical_repo without a run id. Follow its returned clone and
credential-setup instructions privately. If this exact knowledge checkout is
already present, keep it; do not clone again or discard uncommitted work.
Read its entry instructions and report the permitted change/landing route.
For this first check, read only: do not change files or call business systems.

Do not display credentials or .git/config. The checkout credential is Git-only,
not a provider permit. Do not close the standing checkout run: that revokes
the reusable checkout. Report what is verified and any exact blocker.
```

Later, for an authorized change: use an isolated worktree/branch below the
returned prefix, review and test it, push, then call `land_canonical_change`
with that branch. If the result is pending, poll `checkout_change_status` with
the returned `landing_id`; a host timeout is not a failed landing. If the host
timed out before any receipt, call `land_canonical_change` again with the same
branch. Verify landing and a fresh read; pushing alone is not done.

Mainmind accepts a push only when it carries one branch, below the
`agent/<run>/` prefix the checkout returned, whose name uses only `- . _ /`,
lower-case letters and digits. A push that breaks any of those — `main`, a tag,
two refs at once, or `agent/<run>/Fix-403` — comes back as a bare HTTP 403 with
no explanation. That is the branch rule, not a broken credential. Pushing from a
clone that carries another checkout's credential returns the identical bare 403;
that one is the wrong credential, and is cleared by rewriting that clone's
credential with its own checkout's. A branch already pushed only takes new
commits on top: a rebase or force-push to it is refused by name
(`append-agent-branches`), so push the rebased commits to a new branch name below
the same prefix and land that one.

Keep the knowledge checkout for the next session. Calling
`checkout_canonical_repo` again renews access to the same URL without
invalidating another issued credential. Its Git-only credential lasts up to
30 days and is stored privately in the clone; never copy `.git/config` into
chat or a shared artifact. Rules still need the space's human ruling.

### Provider-read preflight: use the files you already have

The standing Git credential cannot call business systems. An Owner with
permitted local tool files, or a task that only needs a provider call, can use
`issue_tool_permit` without `run_id` when that tool is exposed
by the live connection. It returns gateway exports, not a repository: nothing
needs to be cloned. Use `checkout_member_repo` only when you actually need the
scoped knowledge or tool files.

Check the returned capabilities before calling a provider. A teammate's permit
currently grants no provider adapter; a visible tool is not an access grant.
This is still local execution through the HTTP gateway, not a provider call
performed by an MCP-only client. Paste:

```text
Use Mainmind for <space>. Verify identity; if the space differs,
stop without reading knowledge. Boot, find and read the Process for a
read-only business capability preflight. No task declaration is needed.
If no Process fits, follow the space's unmatched-task rule.

Discover the tools on this live connection. If I am the Owner, use the
exposed issue_tool_permit without run_id when the permitted local files
are already present or the task only needs a provider read. Apply only its
returned gateway exports privately in the tool's shell; do not clone just to
get a permit.

If scoped knowledge or tool files are actually needed, use the exposed
run_start to declare an independent task, retain its private control_key,
then checkout_member_repo with that run_id and control_key. Follow the returned instructions.
Preserve existing files and uncommitted work. Read any checkout's entry
instructions. Never call an absent tool, borrow another member's access, or
use GitHub credentials, vendor .env files or another provider connector.
Keep all permit and lease values private.

Inspect the actual provider read/write capabilities. Run one Process-permitted
read through Mainmind's gateway, only if granted. Record the evidence and
limitations; make no provider writes. If no provider capability is granted,
report that boundary rather than attempting a call.

If a standalone tool permit expires, use issue_tool_permit without run_id
for a fresh independent permit and replace its exports. If a scoped checkout
lease needs renewal, keep the files and use renew_checkout_lease with its
task run_id and control_key instead.
Neither action extends the other credential or the Owner's standing Git
credential. Never reopen or relabel another session's run to gain access.

Report sanitized product failures through feedback and retain the receipt.
If you declared a task, finish only that task with its control_key and a
truthful judgment. Independent operations need no finish. Distinguish permit issue,
clone if needed, knowledge read, provider read and renewal results; do not
call missing evidence a pass.
```

## How work survives the session

Both paths return knowledge to one canonical history. A checkout is a
scoped copy, not a second source of truth. In migrated spaces Mainmind's
own Git service holds that history and GitHub is a mirror; spaces not
yet migrated keep their GitHub-backed path. Neither a local commit nor a push
to a run branch alone means a change is on canonical main.

| Change | Use the route returned by the live Mainmind connection | Proof to keep |
|---|---|---|
| Evidence-backed Record or Lesson | Typed deposit from an eligible open run, within the existing Kind and scope | Returned path plus a successful fresh read; a pending response is not readability |
| Scoped ledger file in a checkout | Push the permitted run branch, then use the eligible scoped landing route | Canonical landing result and a new-session read |
| Standing rule or conserved knowledge | Governed proposal and the required human decision | Exact approved change, confirmed landing, fresh read |
| Shared executable tool | Owner reviews and pushes from the canonical checkout, then calls `land_canonical_change`; other members raise the request with `ask_founder` | Canonical landing, inventory renewal after projection, and a fresh member checkout containing the permitted tool |
| Personal tool | Its permitted owner's private work | Private is not shared; do not promise unimplemented private sync or automatic promotion |

Only the Owner controls shared executable publication, including tools shared
with a smaller scope. Others may use permitted shared tools and prepare local
experiments, but a local edit is not permission to publish. Owner control of
code does not bypass gateway grants or business Authority. Shared-tool proposals
and the separate tools-only checkout are retired; do not follow old instructions
for `submit_tool_change` or `checkout_tools`. Private tool synchronization and
automatic promotion are not implied by the Owner landing path.

Read-after-deposit and slow-checkout failures are known limitations. Never
retry an uncertain write blindly: inspect the exact path, receipt and run
state first. If knowledge is stale or unavailable, preserve that failure;
do not substitute an old clone and call it a fresh MCP result.

To test compounding later, explicitly authorize a synthetic Record in a test
space and an existing test Kind. Have one session deposit it, then a
fresh session read the returned path through Mainmind. Reverse the direction
with a permitted checkout ledger change. Do not invent business evidence or
use a customer invoice as a write canary.

## Login, renewal and approval are different

| Prompt or expiry | What it means | What to do |
|---|---|---|
| Mainmind sign-in and OAuth consent | Connect one client to one member and space | Check the role shown before you allow it; do not reconnect on every business task |
| Short-lived access token | The client's renewable connection credential | A compatible client refreshes it without another human login |
| Owner standing Git credential | Reusable Git-only access, up to 30 days | Keep the clone; obtain another credential for the same checkout when needed. Closing its standing run revokes all credentials it owns |
| Standalone tool permit expiry | Gateway access for an independent operation, at most one hour; no Git access | Call the exposed `issue_tool_permit` without `run_id` for a fresh permit and replace its exports. This does not renew a checkout credential |
| Scoped checkout lease expiry | The particular open run's Git and granted gateway access | Use `renew_checkout_lease` for that run; keep local files and replace the old exports. This does not renew a separate tool permit or standing Git credential |
| Harness tool confirmation | The host's own execution policy | Use its supported per-tool settings; this is not Mainmind login |
| Business decision | The Process requires a person's judgment | Review the exact Mainmind decision; login never substitutes for approval |

Mainmind currently bounds renewable login to an absolute 30-day window;
access tokens and checkout leases are shorter-lived. This is not a guarantee
of no prompts for a month: revocation, changed scopes, lost client storage or
host policy can require attention earlier. Repeated routine sign-ins or a
second session breaking the first are product feedback, not reasons to copy
credentials around. Keep writes uncertain until verified; never disable all
approvals to make a test appear smooth.

## Feedback is part of the test

To learn about features you never requested, use `release_notes` and
[the product-update workflow](/docs/releases). `boot` includes a short summary;
read the full feed and save its completion token for your next check-in.

Use `feedback` for Mainmind product failures; use the space's knowledge
note or learning process for problems in the knowledge. Save the returned
product receipt even if GitHub delivery fails. Use `feedback_status` to see
the space's reports and what became of each; if this client does not
offer it, say status cannot yet be retrieved here. A product receipt does not by itself prove issue delivery or repair.

The intended closure is report, linked issue, tested fix, verified deployment,
then the same scenario rerun by the reporting harness. A saved report, handled
status or merged PR is not proof the issue is fixed. The builder loop is not a
Mainmind business-orchestration service.

## Verification boundary

Client instructions link to the official guides. They are setup instructions,
not a claim that this documentation
change ran every product against a live space. Always discover the
current tools and verify identity in the actual task. The deployed
[surface](/api/surface) describes available routes; an authenticated call and
its receipt establish whether your particular session can use them.

## Work as a team without a shared task lock

Knowledge reads and provider calls need no task lifecycle. Read the relevant
Process and constraints, then work. `list_runs` shows coordination tasks;
`include_operations: true` also reveals automatic operation receipt locators.
`run_receipt` reads the observed evidence without changing the outcome.

Use `run_start` only when coordination or a scoped knowledge change needs a
task. Each call creates independent work, even on a shared connection. It
returns `run_id` and a private `control_key`. Keep both with the bot doing the
work; pass the key for task updates, completion and explicit task attachments.
When the named Process declares Required scopes or Required capabilities,
`run_start` compares them to the Connection lease this member would hold and
refuses before opening a run if any are missing or unknown. That lease is
transport access, not business Authority. Seeing another task in `list_runs`
does not let a bot finish it. A new
`run_start` call does not close an older task; preserve its returned result.
A closing judgment cannot replace the gateway's evidence.

Independent operation permits expire automatically. For a provider artifact
or managed restricted-data continuation, pass the operation `run_id` returned
by the preceding call; that uses the original permit, which is not renewed.
An expired continuation must be recovered through the provider's workflow,
not by replaying an uncertain write.
`call_provider` delivers at most 256 KiB inline. For a larger Amazon
document, read it in Range pieces through the same continuation, or run the
read from the local CLI with a permit from `issue_tool_permit` and fetch the
Mainmind artifact link it returns over HTTP with that permit.

Use distinct stable profiles when standing agents need distinct attribution
through one person's connection. Each supported call carries the exact profile;
the shared connection still authenticates as that person and supplies only
their current permission. Use separate legacy machine identities only when a
static-bearer runner or deliberately independent grant requires one. A display
label is not an identity or permission. [Your agent team](/docs/agent-team)
owns the optional portable Role map and host-adapter boundary.