# Connect a system

> Lets an agent read from or write to one of your systems, through operations you choose.

**Skill for your coding agent:** [`mindset-connect/SKILL.md`](https://docs.mindset.ai/skills/mindset-connect/SKILL.md)

**Skill for your coding agent:** [`mindset-slack-connection/SKILL.md`](https://docs.mindset.ai/skills/mindset-slack-connection/SKILL.md)

**Skill for your coding agent:** [`mindset-postmark-email-connection/SKILL.md`](https://docs.mindset.ai/skills/mindset-postmark-email-connection/SKILL.md)

Building an agent goes in order: build the agent, connect your systems, add functions, scripts, Skills and widgets, test it, take it live, then put it in your product. Highlighted: Connect.

## Ask your coding agent

```
Connect our finance system's HTTP API so the invoice exceptions agent can read invoices and purchase orders. Read only for now.
```

Skill: [mindset-connect](https://docs.mindset.ai/skills/mindset-connect/SKILL.md)

## What gets built

A [connection](https://docs.mindset.ai/docs/connections-and-operations) holds the system's address and credential, with one operation for each action an agent may take. The agent reaches the system only through those operations, and the credential never reaches the model.

| Type                                | Use it for                                                                                                                          | What it needs                                                                                                        |
| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| **HTTP API**                        | A system with an HTTP API. Operations come from its OpenAPI description, a documentation page, or your description of each endpoint | A token, up to three headers, or a key in the address. An API that needs OAuth can't be connected yet, except Google |
| **MCP server**                      | A vendor's remote MCP server. Each tool becomes an operation                                                                        | A token, headers, or an OAuth sign-in. Only remote servers: a local (stdio) server can't be connected                |
| **Postgres database**               | Lookups and joins over more data than a sheet holds. Each query is a fixed, parameterized SQL statement                             | A connection string                                                                                                  |
| **Google Sheet**                    | A small table a person also keeps by hand. Two operations: `get_range` reads and `append_row` writes                                | A service-account key, with the sheet shared to the service account's email                                          |
| **Knowledge base**                  | Searching your documents. Mindset doesn't store or index them: they stay on your search server                                      | A remote MCP search server with exactly one tool, `rag_search`                                                       |
| **Google (Calendar, Drive, Gmail)** | A person's or a team's calendar, files and email                                                                                    | Your own Google OAuth client                                                                                         |

[Connection types](https://docs.mindset.ai/docs/connection-types) lists every type and its fields.

> **Info:** Whoever builds the connection, your org's [compliance rules](https://docs.mindset.ai/docs/compliance) apply to it: its writes follow the org's approval setting, and every call is recorded.

## What you decide

- **Shared or Individual.** One account for everyone, or each person connects their own. See [Shared or individual](https://docs.mindset.ai/docs/connections-and-operations#shared-or-individual).
- **Which operations exist.** Only the ones the agent needs. New MCP tools arrive switched off and offered to nobody: your coding agent validates, enables, offers and grants each one the agent needs, and checks each step.
- **Which are writes.** A `GET` is a read and every other method a write. An MCP tool's marking comes from an admin, then the server's own hints, then a model, and anything still unanswered is a write. A database query's boundary is the login's own privileges, so give a read-only job a login that can't write. Correct any marking that's wrong.
- **Whether a new write needs a person.** A read needs no approval. A write is approved once per operation, and with your org's auto-enable setting on (the default) it's enabled with no person involved. See [Approve what agents can do](https://docs.mindset.ai/docs/approve-what-an-agent-can-do).
- **Who can use each operation.** An operation is offered to agents only when it and each of its parameters have a description, because the model picks tools from them. A database query starts out available to functions only.

> **Warning:** A Shared sign-in is used by every run and every user of the connection. If each person should act as themselves, make it Individual.

Google runs on your own OAuth client. Before you connect Calendar, Drive or Gmail, create an OAuth client in your own Google Cloud project and set up its consent screen. Your coding agent gives you the redirect URI to add to the client. Google reviews your project, not Mindset:

- An **Internal** consent screen (accounts in your own Google Workspace only) needs no verification.
- An **External** one needs Google's verification before Calendar or Gmail go to production.

Google's guides: [Configure the OAuth consent screen](https://developers.google.com/workspace/guides/configure-oauth-consent) and [Create access credentials](https://developers.google.com/workspace/guides/create-credentials).

## Done when

- One real read came back, and you checked a value in it against what the system's owner sees. Enabling an HTTP API read makes that call, and the operation's output shape is taken from the real response. A database query runs inside a transaction that is rolled back. A knowledge base answers a **Sample query**.
- You entered the credential on the capture page yourself.
- Every enabled write is one you meant, and you know whether a person approved it or the org setting enabled it.

## See it working

**Live demo:** [Help widget](https://docs.mindset.ai/demos/widget). A billing help agent reads charges over MCP and stops at a refund nobody has approved.

**Live demo:** [Trip planner](https://docs.mindset.ai/demos/trip-planner). Plan a Lisbon trip that uses every feature, each one lit on the Features tab as it fires.

## In your repo

Keep each connection and its operations as one file in `agents/connections/`, beside your agents. The file never holds the credential: a person enters it on a capture page, once per environment. See [Keep your agents in your code](https://docs.mindset.ai/docs/keep-your-agents-in-your-code).

## In the Studio

Connections are created in your AI tool, not in the Studio. **Connections → Copy prompt to create** opens **Build this in your AI tool**, with a prompt that asks for a connection in the right environment: paste it into your coding agent and say what to connect. Each connection's page shows whether it's **Shared** or **Individual**, and its operations under **Operations** or **Tools** on its **Overview**. When a connected system changes, see [Change something that's live](https://docs.mindset.ai/docs/change-something-thats-already-live).
