---
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 published ones.
metadata:
  title: Install and use the Mindset MCP
  blurb: Connects your coding agent to Mindset, so it can build agents and call published ones.
  group: Start here
  order: 1
  docs: work-from-claude-code, use-your-agents-from-claude-and-other-ai-clients, environments
  checked: 23edea589
  updated: 2026-10-29
---

# Install and use the Mindset MCP

When you finish, your client is connected to the right Mindset server for the right environment, the person has signed in, the project carries a note that tells future sessions what Mindset is, 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 address under **Settings → Systems → Connect an AI client** |
| **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 `original`.** 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 can't be deleted, and they're for stages such as Test and Production, not for projects. 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 published to 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>/api/v1/orgs/<org-slug>/envs/<environment-slug>/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: it prints the exact address for the environment the person has selected. Ask the person for that address and nothing else. It already holds the host, the org slug and the environment slug, so read all three out of it and say them back. Build it from the host and the two slugs only if the person can't reach the screen. The org-only form, without `/envs/<environment-slug>`, is refused.

## 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-admin-<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` shows an entry for a different address, in any scope, 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. 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. Ask the person to run `/mcp`, pick the server and sign in. (`claude mcp login mindset-admin` does the same from the command line.) A session that was already running when you added the server may not list it. Then the person restarts Claude Code, or reloads the editor window when Claude Code runs in an editor, runs `/mcp`, and picks the conversation up again (`claude --continue` in 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`:

```markdown
## Using Mindset

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

- 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.
- Author with `find_examples` first, then `create_resource` / `edit_resource` / `publish_resource`.
- 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 published to 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.
- Read the list back, with each role, and send nothing until they say yes. Every invite emails a real person.
- Look each person up first: `member_admin` with verb `list` and `search` set to their address.
- To change the role of anyone already in the list, call `member_admin` with verb `set_type`, their `userId` and the `type`.
- Someone shown as `disabled` was removed. Bring them back with verb `enable` and their `userId`.
- Someone shown as `locked` was invited but never accepted. Invite them again to send a fresh link.
- Invite everyone not in the list: `member_admin` with verb `invite`, `email`, and `grantedType` set to `admin` or `user`. Report what each call returns, not what you asked for.
- 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. **Start from an example.** Call `find_examples` before you write a script, function or widget, then `create_resource` and `edit_resource`. Functions and widgets go live with `publish_resource`. A script doesn't: it belongs to one agent, and goes live when that agent's configuration names it and the version is activated (see the `mindset-script` skill).
3. **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.
4. **Leave approvals to people.** You can enable a read operation. A write operation waiting for approval stays waiting until a person approves it in the Studio. No tool argument gets round that.
5. **Deleting can't be undone.** Archive an agent to take it out of use instead. Confirm with the person before you delete anything.
6. **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. Pass `envSlug` on a call to point it at another environment, for example to compare an agent in Test and Production. Only a person's signed-in admin connection can do that.
- **`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:** `envSlug` can't reach it, because the org is in the address. Add a separate entry named for that org, such as `mindset-admin-<org-slug>`, and say in the note which name reaches which org.

## 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 the address | A wrong slug, or the org-only address without `/envs/<slug>` | Copy the address from the screen named above |
| 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 un-enabled | It's waiting for a person to approve it | A person approves 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 address or an `envSlug` named another one | Check the address in the MCP config and any `envSlug` you passed |

## 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.