---
name: mindset-mcp
description: Use first for any work with Mindset (mindset.ai), the AI agent platform. Explains orgs and environments, then installs and uses Mindset's MCP servers in Claude Code, Cursor, VS Code, Claude Desktop or Claude.ai, mindset-admin to build and govern agents or mindset to call the agents enabled for the person.
metadata:
  title: Install and use the Mindset MCP
  blurb: Connects your coding agent to Mindset, so it can build agents and call the ones enabled for you.
  group: Start here
  order: 1
  docs: work-from-claude-code, use-your-agents-from-claude-and-other-ai-clients, environments
  checked: 70d2d364d
  updated: 2026-11-11
---

# Install and use the Mindset MCP

When you finish, your client is connected to the right Mindset server, the person has signed in, the project carries a note that tells future sessions what Mindset is and which environment it uses, and you've made a first call.

## Mindset in brief

Mindset is a hosted platform for building, running and governing AI agents. An **agent** is configuration, not code: a prompt, a model, and the resources it may use. Those resources are **scripts** (steps that must wait or happen in order), **functions** (fixed steps with one right answer), **widgets** and **connections** (the only way data enters or leaves). People manage all of it in the Studio, a web app, or through Mindset's MCP servers.

## Where you are building: host, org, environment

Every Mindset call names three things. Get all three from the person before you write code or call a tool. Never guess or invent them.

| Value | What it is | Where the person finds it |
|---|---|---|
| **Host** | The Mindset deployment their org lives on, for example `https://eu.mindset.ai` | The address bar when they're signed in to the Studio, or an agent's **Embed** tab |
| **Org slug** | Their company's account. The org is the isolation boundary: members, model keys, settings and audit sit here, and one org can never see into another | An agent's **Embed** tab, or the users' server address under **Settings → Systems → Connect an AI client → For users** |
| **Environment slug** | A named partition inside the org, such as Sandbox, Test or Production | An agent's **Embed** tab, or the same address. The **Environment** switcher in the Studio shows which one is current |

How environments behave:

- **Agents, scripts, functions, connections, triggers, schedules, conversations, runs and API keys each belong to exactly one environment** and can't see anything in another.
- **Every org starts with one environment, Sandbox, whose slug is `sandbox`.** A slug never changes, even when the environment is renamed. Use the slug, never the display name.
- **Nothing copies between environments.** To promote a change from Test to Production, make the same change again in Production.
- **Don't create an environment to hold your work.** Environments are for stages such as Test and Production, not for projects, and only a person can delete one, with everything in it. Work in the environment the person names. Create one only if the person asks you to.
- **Members, model keys and org settings are shared by every environment.** Changing an org setting changes it everywhere.

## Pick the server

Mindset runs two MCP servers. Both are remote HTTP servers, and both sign the person in through the browser.

| | `mindset-admin` | `mindset` |
|---|---|---|
| Use it to | Build, test, run and govern: agents, scripts, functions, widgets, connections, runs, costs, audit, members | List the agents enabled for the person and call one |
| Who can use it | Org admins only. Anyone else is stopped at sign-in and sent to the hub | Every member of the org |
| Address | `<host>/mcp` | `<host>/api/v1/orgs/<org-slug>/envs/<environment-slug>/mcp/hub` |
| Where the person copies it | **Settings → Systems → Connect an AI client → For administrators** | The Hub, under **Use your agents from your own AI client** |

Writing code that changes agents or connections needs `mindset-admin`. Only asking existing agents to do work needs `mindset`. If you're unsure, ask the person whether they're an org admin.

Copy the address from the screen above when you can, and ask the person for that address and nothing else. The `mindset-admin` address is the host followed by `/mcp`, the same for every org: the sign-in chooses the org, and every call that works inside an environment names it with `envSlug`. A `mindset` address holds the host, the org slug and the environment slug, so read all three out of it and say them back. Build an address yourself only if the person can't reach the screen. A `mindset` address without `/envs/<environment-slug>` is refused. A `mindset-admin` entry added earlier at `<host>/api/v1/orgs/<org-slug>/envs/<environment-slug>/mcp` still works: leave it as it is.

## Install it

Use the server name exactly as shown (`mindset-admin` or `mindset`), so the person can say "use the mindset-admin MCP". A second org gets a name of its own (see "More than one environment or org"). Replace `<url>` with the address. If a step is already done, say so and skip it.

**Claude Code.** Scope it to the project, so the server lands in `.mcp.json` next to the note you write below. The transport flag goes before the name.

```sh
claude mcp add --transport http --scope project mindset-admin <url>
```

`.mcp.json` and `CLAUDE.md` are usually committed, so project scope gives the server and the note to everyone who works in this repository. That's right when they all use this org. When they don't, for example because the person reaches several orgs from this repository or it's shared beyond the org, use `--scope local` instead: the server then stays on this machine, and the note goes in `CLAUDE.local.md`, which Claude Code loads beside `CLAUDE.md` and you add to `.gitignore`. In a repository that reaches several orgs, name every entry for its org from the first one, such as `mindset-<org-slug>`, and add a line to the note saying which name reaches which org. If you can't tell which applies, ask. If `claude mcp get mindset-admin` already shows an entry, in any scope, make one call through it and read which org its reply names before you change anything. Don't replace it or add a second one under the same name: a local entry silently wins over a project entry of the same name. If it reaches another org, ask, then name the new one for its org, as "More than one environment or org" below says. An entry already in `.mcp.json` belongs to everyone in the repository: ask before you remove it (`claude mcp remove <name> --scope project`).

Adding the server doesn't open a browser, and a server added during a session doesn't appear in `/mcp` until Claude Code restarts. Ask the person to restart Claude Code in this folder (`claude --continue` keeps the conversation; when Claude Code runs in an editor, they reload the window), approve `mindset-admin` when asked (a project-scoped server waits for approval), then run `/mcp`, pick `mindset-admin` and sign in. Or they run `claude mcp login mindset-admin` in a terminal. Don't run it yourself: it needs a real terminal, and run by you it fails with "stdin isn't a terminal".

**Cursor.** Add it to `.cursor/mcp.json` in the project, or `~/.cursor/mcp.json` for every project. Cursor takes a bare `url`, with no `type` field.

```json
{
  "mcpServers": {
    "mindset-admin": {
      "url": "<url>"
    }
  }
}
```

The person reloads Cursor and completes the browser sign-in when prompted.

**VS Code (Copilot agent mode).** Add it to `.vscode/mcp.json`. VS Code requires `"type": "http"`.

```json
{
  "servers": {
    "mindset-admin": {
      "type": "http",
      "url": "<url>"
    }
  }
}
```

The person reloads VS Code, runs **MCP: List Servers**, picks the server, chooses **Start**, and signs in in the browser.

**Claude.ai.** The person adds it themselves: **Customize → Connectors → + → Add custom connector**, then pastes the address. On a Claude Team or Enterprise plan, an Owner adds it once in **Organization settings → Connectors**, and everyone else finds it under **Customize → Connectors** and clicks **Connect**.

**Claude Desktop.** The person adds a custom connector in the app's connector settings and pastes the address.

Swapping the Cursor and VS Code shapes fails without an error. Use the one for the client you're in.

## Write the durable note

Registering the server tells a future session that tools exist, but not what Mindset is. Add the matching note to the client's always-loaded instructions file: `CLAUDE.md` for Claude Code (`CLAUDE.local.md` when you added the server with local scope), `.cursor/rules/mindset.mdc` (with `alwaysApply: true`) for Cursor, `.github/copilot-instructions.md` for VS Code, and a Project's instructions in Claude.ai or Claude Desktop. If a "Using Mindset" section is already there, leave it alone.

For `mindset-admin`, as it stands before the person has chosen an environment. Fill the environment in once they have:

```markdown
## Using Mindset

This project's agents live in Mindset. The `mindset-admin` MCP server administers them: the agents, the connections that are the only way data enters or leaves, and the resources around them.

- Environment: not chosen yet. Before the first Environment-scoped call, ask the person which Environment this project uses (`org_admin({ verb: 'list_envs' })` lists them), then record it here and in `mindset/mindset.json`. Pass it as `envSlug` on every Environment-scoped call.
- The same organization, Environment(s) and server address are recorded in `mindset/mindset.json`; create it if it is missing, and keep the two in step. Its shape (`topic='working-with-mindset'` has the folder layout around it): `{"orgs":{"<org>":{"server":"https://<region>/mcp","connection":"mindset-admin","environments":{"<env>":"<what it is for>"},"default":"<env>"}}}`
- Call `get_information` with no arguments for the topic index, and read `topic='what-is-this-platform'` before authoring anything. It is the topic that explains what the pieces ARE; the others assume you already know.
- Before authoring, use `find_examples` if this deployment has examples; if it answers that none are available, read `topic='choosing-what-to-build'` instead. Then `create_resource` / `edit_resource`. Your saves are not active: a person activates them, and enables what is new, in the web UI.
- Errors come back structured. Read `code` and `context` and recover, rather than retrying blind.
```

For `mindset`:

```markdown
## Using Mindset

The `mindset` MCP server reaches the agents this organization has enabled for me, plus my own.

- `list_callable_agents` to see what I can use (each row carries its description), then `call_agent` to hand it work.
- Each agent runs under its OWN permissions, never mine.
- A call is usually synchronous and can take minutes. Size the timeout accordingly; it cannot be cancelled.
- Sometimes it is not synchronous: a call that outlives the platform's conversion window returns state `working` with no text. That means the waiting stopped, not the agent, and this surface cannot fetch the reply afterwards. Don't re-send it; that starts a second run.
- There is no administrative capability here, by design. Don't go looking for it.
```

## Check it works

Confirm the tools are listed, then make one read call:

- `mindset-admin`: call `get_information` with no arguments, then ask for the agents in the environment.
- `mindset`: call `list_callable_agents`.

Every reply ends with the org it answered for, and the environment too when the call works inside one, as listing agents does: `Answered for Org … · Environment …`. Tell the person, from that line, which org and environment you're connected to, so a wrong address shows on the first call. Don't rely on the server's opening instructions for this, because some clients cut long instructions short before the line that says it.

## Bring the team in

On `mindset-admin`, once the first call works, ask once: "Does anyone else at your company need Mindset? For each person, do they build and govern (admin), or only use agents (member)?" If they say no, move on.

- Use only the addresses the person gives you. Never guess or complete one.
- Look each person up: `member_admin` with verb `list` and `search` set to their address.
- You can't invite anyone, change a member's role or enable a disabled member. The person does those in the Studio, under **Settings → Members**: **Invite member** for someone not in the list, and the member's menu for a role or for someone shown as `disabled`. Read the list back to them, with who is already a member, each role, and who needs an invite.
- Someone shown as `locked` was invited but hasn't signed in. `member_admin` with verb `send_sign_in_link` and their `userId` emails them a fresh link. It emails a real person, so send it only when the person says yes.
- Tell the person what happens next. Each invitee gets an email from Mindset with a link that works once and lasts 7 days. The email doesn't say how to connect an AI client, so give each invited admin the address of this skill, https://docs.mindset.ai/skills, to connect their own; a member uses agents from the Hub or from their own AI client. Everyone signs in as themselves, and nobody shares a connection.
- If many colleagues share the company's email domain, one setting can replace a long list of invites: `org_domain_admin` can let anyone who signs in with that domain join as a member. Mention it, and leave the choice to the admin.

## Use `mindset-admin`

## Credentials for building in Mindset: sign in, never a key

You build inside Mindset through the **`mindset-admin` MCP server**. The person signs in with their own Mindset account in a browser, and they must be an org admin. There is no key or token, so never ask the person for one.

- **The server address names one environment**: `<host>/api/v1/orgs/<org-slug>/envs/<environment-slug>/mcp`. Every call goes to that environment unless the tool call passes `envSlug` to point that one call at another environment. Org-level tools refuse an `envSlug`.
- **No tool takes a secret value.** When a connection needs a credential, call `request_capture`. It returns a reference and a capture URL. Give the person the URL to open and paste the value into themselves, then use the reference. Capture links expire after 15 minutes. For a system that signs in with OAuth, `authorize_connection` returns a sign-in link the person opens the same way, and it expires after 10 minutes. If a link has expired, request a new one. Never ask the person to paste a credential into the conversation, even if they offer.
- **Errors come back structured.** Read `code` and `context` and act on them. Don't retry blind.

How to work through it:

1. **Orient.** Call `get_information` with no arguments for the topic index, then read `topic='what-is-this-platform'` before you author anything.
2. **Name the environment.** Pass `envSlug` on every call that works inside an environment. A call without it is refused with `env_required`, which lists the org's environments. Ask the person which one when the note doesn't say.
3. **Start from an example.** Call `find_examples` before you write a script, function or widget, then `create_resource` and `edit_resource`.
4. **Save, then hand over.** Every save makes a version that isn't active. You can't activate a version or enable anything: a person does that in the Studio. Before your first save, tell the person so. After each save, give them the link in the reply's `next` block. A script becomes active with the agent version that names it (see the `mindset-script` skill).
5. **Ask before writes.** A test run that would write to a connected system is refused the first time with `write_go_ahead_required`, carrying everything it would read and write. Tell the person what it reads and writes, without jargon. Call again only when they say go, passing `goAhead: { listHash, instruction }` with their instruction quoted.
6. **Leave writes to people where the org says so.** You can enable a read operation with `govern_tool`. Enabling a write may wait for a person: it comes back still disabled, with the reason, and a person enables it on the connection's **Operations** tab in the Studio. No tool argument gets round that.
7. **Nothing here deletes.** Archive an agent with `archive_agent` to take it out of use. A person disables a function or widget, or archives a connection, in the Studio.
8. **Some work is done only in the Studio, by a signed-in person**, such as creating an API key. When no tool does what's asked, say so.

Everything you do is checked against the person's real admin permissions and recorded in the org's audit trail under their name.

## Use `mindset`

1. Call `list_callable_agents`. Each row has the agent's description. Only agents available in the Hub appear, plus the person's own agents. Before you send people to an agent, check `availability.hub` with `get_agent` on `mindset-admin`. That server's own `list_callable_agents` also lists agents the Hub doesn't offer, so it can't tell you what members see.
2. Call `call_agent` with the agent and the task. The agent runs under its own permissions, never the caller's.
3. A call can take minutes and can't be canceled. If it comes back with state `working` and no text, the agent is still running in Mindset. Don't call again: that starts a second run, and any writes in it happen twice. Tell the person to check back later.
4. To continue a conversation, pass back the `contextId` and replay the earlier turns in `history`. On `mindset`, only the person's own `user` turns are accepted there.

## More than one environment or org

- **`mindset-admin`:** keep one server entry per org. Every call that works inside an environment names it with `envSlug`, so one entry reaches all of them, for example to compare an agent in Test and Production.
- **`mindset`:** each address sees one environment's agents. For a second environment, add a second entry with a distinct name, such as `mindset-production`.
- **Another org:** each entry signs in to one org, so `envSlug` can't reach another. Add the same `mindset-admin` address again under a name of its own, such as `mindset-<org-slug>`, and choose that org when you sign in. Say in the note and in `mindset/mindset.json` which name reaches which org. Claude Code has been checked to hold two orgs side by side; other clients haven't been checked yet.

## When it doesn't work

| What you see | Cause | What to do |
|---|---|---|
| Sign-in for `mindset-admin` says "Admin tools are for admins" | The person isn't an org admin in that org | Use `mindset` instead, or ask an org admin |
| "Not found" or a refusal on a `mindset` address | A wrong slug, or no `/envs/<slug>` in it | Copy the address from the screen named above |
| A call is refused with `env_required` | It didn't name an environment | Pass `envSlug`. The refusal lists the environments; ask the person which one if the note doesn't say |
| Tools don't appear in Claude Code | Sign-in hasn't happened | Ask the person to run `/mcp` and sign in |
| `/mcp` doesn't list a server you just added | The session started before it was added | Restart Claude Code, or reload the editor window, then run `/mcp` |
| `list_callable_agents` is empty | No agent in that environment is available in the Hub | Ask the agent's owner to tick **The Hub** for it, or check the environment in the address |
| `call_agent` returns `working` | The run outlived the wait. It's still going | Don't re-send. On `mindset-admin`, read the reply later with `conversation_fetch`, noun `message`, filtered by the answer's `conversationId`. On `mindset`, check later |
| Enabling a write operation comes back still disabled | The org has a person enable each write | A person enables it on the connection's **Operations** tab in the Studio |
| A capture link says it's no longer valid | It expired after 15 minutes | Call `request_capture` again |
| A change landed in the wrong environment | The `envSlug` you passed, or a `mindset` address, named another one | Check the `envSlug` you passed and the address in the MCP config |

## Read more

Fetch these as Markdown when you need more than this skill gives you. If one disagrees with this skill, the page is newer: follow it.

- https://docs.mindset.ai/docs/work-with-the-mcp-server.md: read for which topics to read first, and what stays with a person.
- https://docs.mindset.ai/docs/use-your-agents-from-claude-and-other-ai-clients.md: read when the person only calls agents.
- https://docs.mindset.ai/docs/environments.md: read when the person asks about setting up or promoting between environments.
- https://docs.mindset.ai/docs/glossary.md: read when the person uses a Mindset term you don't know.
- https://docs.mindset.ai/llms.txt: every page, with a one-line summary.
