---
name: mindset-connect
description: Use when connecting an outside system to Mindset (mindset.ai) so an agent can use it, through the mindset-admin MCP server. Covers choosing the connection type (HTTP API, MCP server, Postgres, Google Sheet, knowledge base), getting the credential in with request_capture or authorize_connection, enabling and governing operations, which writes wait for a person to enable them, and proving each read with real data.
metadata:
  title: Connect a system for an agent
  blurb: Connects an outside system, such as an API, database or MCP server, so an agent can use it.
  group: Mindset MCP
  order: 4
  docs: connections-and-operations, connection-types, connect-a-system, approve-what-an-agent-can-do, change-something-thats-already-live
  checked: 70d2d364d
  updated: 2026-11-11
---

# Connect a system so an agent can use it

When you finish, the outside system is an enabled **connection** in the person's environment, the operations the agent needs are enabled and offered to agents, each read has returned real data the person checked, and every write is either enabled or visibly waiting for a person to enable it.

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

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

## Before you start

This skill works through the `mindset-admin` MCP server. Check that its tools (for example `get_information`) are available to you. If they aren't, set the server up first, following the `mindset-mcp` skill or https://docs.mindset.ai/docs/work-from-claude-code.md, then come back here.

Call `get_information` with no arguments for the platform's own topic index. Its guidance is current for the platform you're connected to. Where it and this skill disagree, follow `get_information`.

## Connections and operations

A **connection** links Mindset to one outside system and holds its address and credential. Mindset looks up the credential for each call. The agent never holds it, and it never reaches the model.

An **operation** is a single action an agent can take on a connection, with a fixed input and output. Each one is a **read** (fetches something) or a **write** (changes something). An agent is given operations, never "the finance system": for example `get_invoice`, `get_purchase_order_for_invoice` and `get_supplier` (reads) and `register_supplier_query` (a write) for the invoice exceptions agent.

An agent can call an operation only when all five hold:

| | Question | Who settles it |
|---|---|---|
| 0 | Is the connection enabled (it passed its test when a person enabled it)? | A person, with **Enable** on its **Overview** tab |
| 1 | Is the operation enabled? | Creating it, or `govern_tool` |
| 2 | Is it offered to agents (`exposures` includes `agents`)? | `edit_resource` |
| 3 | For a write the org holds for a person: has a person enabled it? | The org setting, or a person in the Studio. Never you |
| 4 | Is it on the agent's active version? | `agent_config_admin`, or the agent's **Resources** tab |

Questions 0 to 3 are checked on every call. Question 4 takes effect only when a person activates a version.

## Ask the person for

- The host, org slug and environment slug, if your MCP address doesn't already settle them.
- What the agent must do with the system, in the person's own words. You turn that into the smallest set of named operations.
- The system's address, and what kind of system it is (an HTTP API, a remote MCP server, a Postgres database, a Google Sheet, or a search server holding documents).
- Who holds the credential, and that it's scoped to only what the operations need and pointed at the right account.
- One record they can check on their own screen (an invoice number, a supplier ID), so you can prove the reads.
- A safe target for any write you test: a test record, a test channel, their own address.

## Step 1: choose the connection type

`type` is required on every connection, and the platform can't infer it. It decides the protocol. Get it wrong for an MCP server (declaring `rest_api`) and the connection is created with zero operations and no error.

| `type` | Use it for | Credential | Operations come from |
|---|---|---|---|
| `rest_api` | Anything with an HTTP API. Most connections | Bearer token, up to three headers, HTTP Basic, or none | Authored, one per method and path |
| `mcp_server` | A **remote** MCP server. A local (stdio) one can't be connected | Token, headers, or an OAuth browser sign-in | Discovered from the server |
| `postgres_database` | Lookups and joins over more data than a sheet holds | A connection string (`dsn`) | Fixed parameterized queries you enable one at a time |
| `google_sheet` | A small table a person also edits | A Google Cloud service account key | Fixed: `get_range` (read), `append_row` (write) |
| `knowledge_base` | A search server holding the person's documents | As for an MCP server | Exactly one tool, `rag_search` |
| `model` | Letting functions and scripts call one AI model, under limits an admin sets | None | None. Functions and scripts name the connection |
| `stackone` | HR, recruiting and CRM systems, per end user through StackOne | None from you. Each end user signs in through StackOne | See the connection types page |

If the system fits none: does it have an HTTP API? Use `rest_api`. Is there a remote MCP server for it? Use `mcp_server`. Is it reachable only by clicking through a website? Mindset can't reach it. Say so.

An HTTP API that needs OAuth (browser sign-in or client credentials) can't be connected yet. Ask for an API key, or a vendor MCP server.

## Step 2: read the platform's recipe

Call `get_information` with `topic='authoring:connection'`. It's the generic flow, the adapter and config fields, and it names its other parts. Then read the guide for the type: `authoring:connection:api`, `authoring:connection:mcp`, `authoring:connection:database`, `authoring:connection:sheets` or `authoring:connection:llm`. For Slack, read `authoring:connection:provider:slack`. These are current for the platform. Follow them for field names and argument shapes.

## Step 3: probe the address

Call `probe_endpoint` with the URL before you create anything. It reports whether the far side speaks MCP, is plain HTTP, or is undetermined, and what authentication it declared.

- A `401` isn't a failure. For an MCP server it usually means it wants authorizing.
- `undetermined` is a real answer. Ask the person what the system is. Never guess the type from the URL.
- The probe decides nothing. You still state `type` and the adapter yourself.

## Step 4: get the credential in

You never see, hold or type a credential. There are exactly two routes:

- **A token, key, password, DSN or service account key:** call `request_capture` with the config `field` the adapter declares (for example `token`, `password`, `dsn`, `serviceAccountJson`), the `adapter`, and a `label` saying what it's for in the person's words ("the finance system's API key"). Give the person the `captureUrl`. Put the returned `secretRef` at `config.<field>` as `{ "secretRef": "<the ref>" }`. A secret captured under a field the adapter doesn't declare is never read, and the probe fails as if nothing were supplied.
- **An MCP server that signs in with OAuth:** create the connection with `adapter: "none"` and no credential, and have a person enable it. The `401` that comes back is expected, and the connection then reports `oauthRequired`. Call `authorize_connection` with the connection and hand on the link as its result's `instructions` say. The person signs in on the provider's own screen. Afterwards, read the connection back with `get_resource` and check `oauthConnected`. Don't assume it worked. Then the person enables it again. `authoring:connection:mcp` has the steps.

To replace a credential that already exists (rotated, leaked, wrong value), read its existing `secretRef` from the connection's config and pass it to `request_capture`. The reference stays the same, so don't edit the connection afterwards. Capturing a fresh one instead leaves the old secret working and orphaned.

## Step 5: create the connection, then a person enables it

1. Propose a short name and a one-line description to the person. The description is what later lets someone pick the right connection.
2. Call `create_resource` with `type: "connection"`, an `input` carrying the name, description, address, `type`, adapter and `config`, and an `idempotencyKey`. If the call errors, retry with the **same** key: a create that reported an error may already have committed, and a fresh key makes a second connection holding its own credential.
3. You can't enable a connection. Ask the person to press **Enable** on the connection's **Overview** tab in the Studio. Enabling tests it on its own host and enables it only on a pass. Read the result with `get_resource`: `testVerification` says which grade the pass reached (`credential_verified` or `reachability_only`). Report which, never a bare "it passed".

For an MCP server or knowledge base, enabling discovers the tools. Every discovered tool arrives disabled. A knowledge base with anything other than exactly one `rag_search` tool is refused. Connect a multi-tool search server as `mcp_server` instead.

## Step 6: set up the operations

**HTTP API.** Call `introspect_api` on the connection. It tries standard OpenAPI and Swagger paths and GraphQL on the API's own host. Finding nothing is a normal answer. Then ask the person to paste the relevant documentation into the conversation, or name the parameters. No tool here fetches a link, so don't ask for one. Register each operation with `create_resource` and `type: "connection_operation"`, including `sampleArgs` that name a real record. A read (`GET`) makes one real call and enables only if it worked, and its output shape comes from the real response, not the documentation. A required path parameter without a real value is refused.

**Postgres.** Each operation is one parameterized SQL statement. Enabling first checks the login's privileges (a refusal gives the `GRANT` statement for the database owner), then runs the query inside a rolled-back transaction. Read versus write follows the login's privileges, not the SQL, so a connection that must never write needs a login that can't write. An agent's call returns at most 100 rows, and a function's or script's 1,000. Every result stops at 5 MB of whole rows, and `truncatedBy` says which limit cut it.

**Google Sheet.** Ask the person to share the spreadsheet with the service account's email address. Register `get_range` and `append_row` as operations.

**MCP server.** A discovered tool becomes callable through four acts, in this order, each read back before the next: validate it (`test_resource` on the connection, `mode: "validate"`), enable it (`govern_tool` with its `operationId`), offer it (`exposures`), and grant it (`agent_config_admin`). Follow the numbered checklist in `authoring:connection:mcp`, which gives each call and the read-back that confirms it, and report a tool callable only when all four read true. Leave the tools the workflow doesn't need disabled.

Then, for every operation:

- **Descriptions.** The operation and every parameter need a description written for tool choice. The model picks the tool and fills its parameters from them. Fix wording with `edit_resource`, not `govern_tool`.
- **Labels.** Each operation also carries `labels`, `{ doing, done }`: the line a person sees in the chat while it runs and once it has. They're generated for you. To change them, `edit_resource` with a `path_set` on `labels` (one line each, at most 60 characters), or `null` to go back to the generated pair.
- **Offer it to agents.** Read the operation with `get_resource`, then `edit_resource` with a `path_set` on `exposures` to the full set you want (for example `["functions", "agents"]`). This is refused while any description is missing. Enabling never offers it to agents: an operation you register starts offered to functions only, and a discovered MCP tool to nobody. Until it's offered to agents, its record carries a `reachNotice` saying so.
- **Check read or write.** On an MCP tool, the marking comes from an admin's choice, then the server's hints, then a model's reading, and anything unknown counts as a write. Correct a wrong marking with `govern_tool` and `access`. If in doubt, mark it a write.
- **Other governance** through `govern_tool`: `disable` (kept, not callable), `adminOnly`, and `eraseOutputSamples`.

## Step 7: prove each read with real data

A probe proves the credential, not the data. Before any agent uses a read:

1. Call `test_resource` with `type: "connection"`, the connection, and the operation plus its arguments. It refuses a write operation, so it can't change the system.
2. Show the person one value from the response, and have them check it against what they see in the system itself. A credential pointed at the wrong account returns valid data and no error.
3. Report each operation you registered as **Tested** or **Untested**, by name. A person activating an agent version whose script calls an untested operation can be refused.

## Step 8: writes wait for a person

Read the result when you create or enable a write:

- **"Enable actions that change other systems automatically" on (Settings, Systems; the default):** a new write is enabled at once, recorded as enabled by the org setting. It's callable but untested. Say plainly what it would really do.
- **That setting off:** the write is registered, not rejected, and waits for a person to enable it. Its record carries `enableUrl`, and `govern_tool` leaves it disabled with the reason. Give the person the link: they enable it on the connection's **Operations** tab (or **Tools** for an MCP server). Report it verbatim. Never tell anyone the agent can use it yet.

No tool argument enables a write that waits for a person, and you can't enable one. To test a write, call `test_resource` with `input.mode: "invoke"` against the safe target. It's first refused with `write_go_ahead_required` and what it would write. Tell the person what it would write, and call again with `goAhead` only once they say go, quoting their instruction.

## Step 9: give it to the agent

Give the operations to the agent with `agent_config_admin` verb `set_assignments` and `assignments: { connection_operations: [<every operation id the agent should hold>] }`. It saves an agent version that isn't active. Tell the person the version number, and that they activate it: the reply's `next` carries the link. A knowledge base is assigned whole, under `connections`. If a connection you assign gives the agent no tool, the reply's `assignmentWarnings` says why. A write still waiting for a person can be assigned; it runs nothing until a person enables it. Nothing reaches the agent until a person activates a version holding it. If you aren't building the agent, tell the person to add the operations on the agent's **Resources** tab.

## Rules

- Never ask for a credential in the conversation, a tool argument or anywhere else, even if the person offers. If a capture can't be completed, say so and stop.
- Never write the literal `{ "secretRef": "captured" }`. That placeholder belongs to the in-app builder and resolves to nothing here.
- Give an agent the fewest operations it needs. Assign named operations rather than the whole connection, except for a knowledge base.
- Never call a test write without the person's go-ahead for that exact write.
- No tool deletes a connection. A person archives one in the Studio. To stop a connection for now, disable it with `edit_resource` and `disabled: true`. Only a person enables it again.
- Rotating a credential or changing the address makes the operations untested again.
- Don't put a probe path such as `/ping` on the base URL to make a probe pass. Operation paths are appended to it, so every operation breaks.

## Check it works

- `get_resource` on the connection shows it enabled, and which grade its test reached.
- `list_resources` with `type: "connection_operation"` and the connection as filter shows each operation you need, enabled, with `agents` in `exposures` where an agent calls it.
- One `test_resource` read per operation returned a value the person confirmed.
- Every write is reported as enabled (by the org setting or a named person) or waiting, with its `enableUrl`.

## When it fails

| What you see | Cause and fix |
|---|---|
| An MCP server connection has no operations and no error | It was created as `rest_api`. `edit_resource` the `type` to `mcp_server`, then the person enables it again |
| `probe_endpoint` or enabling returns `401` on an MCP server | It wants OAuth. Use `authorize_connection` |
| Enabling fails after a capture | The secret went under a field the adapter doesn't read, or the value is wrong. Replace it through `request_capture` with the existing `secretRef` |
| A capture or authorization link no longer works | It expired. Request a new one |
| Enabling a read fails with an authorization error | The credential is scoped narrower than the operation needs. The person widens it at the provider |
| `edit_resource` refuses `agents` in `exposures` | The operation or a parameter has no description. Add them |
| An operation comes back with a `blockedReason` | It's offered but not callable yet, usually a write waiting for a person to enable it. Report it verbatim |
| A write's record carries `enableUrl`, or `govern_tool` leaves a write disabled | A person must enable it in the Studio. Pass on the `enableUrl` |
| `credential_binding_required` | A connection the platform operator provides needs this org's own credential. Capture one, then call `bind_connection_credential` |
| Knowledge base discovery refused | The server doesn't expose exactly one `rag_search` tool. Connect it as `mcp_server` |
| The sheet reads as empty or refuses access | The spreadsheet isn't shared with the service account's email |
| The data is right but from the wrong place | Check the account the credential reaches, not the connection |
| `name_taken` | Another operation on that connection already has that name. Pick another, or rename that one first |
| Registering an HTTP operation refuses a header parameter | The connection's credential already sets that header, such as `Authorization`. Remove the parameter: Mindset sends the credential |

## 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/connections-and-operations.md: read for the five questions and how to check you reached the right account.
- https://docs.mindset.ai/docs/connection-types.md: read when a system doesn't obviously fit a type, or for the model and StackOne types.
- https://docs.mindset.ai/docs/connect-a-system.md: read for choosing a connection type, auth options, OAuth sign-in and how tools are marked read or write.
- https://docs.mindset.ai/docs/troubleshooting.md: read when enabling a database operation fails on a privilege, or a Google Sheet reads as empty.
- https://docs.mindset.ai/docs/approve-what-an-agent-can-do.md: read for writes that wait for a person, disabling one again, and per-action approval in Slack.
- https://docs.mindset.ai/docs/change-something-thats-already-live.md: read when a connection must be disabled or archived, or a system stops returning a field.
