# Connect an MCP server

> Connect a remote MCP server, sign in to it, choose which of its tools agents can use, and check how each tool is marked as a read or a write.

After this page an MCP server is connected, you've chosen which of its tools agents can use, and you know whether each one reads or writes.

## What this is

An **MCP server** connection reaches the tools a server exposes over the Model Context Protocol. Use it for things Mindset doesn't do itself, such as reading text from a scanned invoice, or for a product whose vendor ships an MCP server. Each tool becomes an [operation](https://docs4.mindset.ai/docs/ams/connect-a-system), and from then on it behaves like any other operation: enabled, made available, approved if it writes, and assigned to an agent.

**Only remote MCP servers can be connected.** Setup asks for an address. A local (stdio) server, the kind that runs as a program on your own laptop, can't be connected, because Mindset hosts your agents and has no machine of yours to run it on. Ask the vendor for their remote address.

## How to connect it

1. Open **Connections**, press **+ New connection**, choose **I will set it up**, then **MCP server**.
2. Under **Paste what your vendor gave you**, paste a `claude mcp add` line, an `.mcp.json` block, or just the address, and press **Read it**. Mindset fills in the address and any headers it carries. Or fill in the **Address** yourself.
3. Enter the credential, or sign in (see below).
4. Press **Check this address**. Once the server answers, its tools appear under **What it can do**. That list is how you tell it's the right server.
5. Give it a **Name** and an optional **Description**, then press **Add it**.
6. On the **Tools** tab, enable the tools agents need. New tools arrive switched off.

You can also choose **Describe it to the builder** and let the Connection Builder set it up with you.

## Auth options

| The server wants | What to do |
|---|---|
| A bearer token | Enter it as **Token**. It's sent as `Authorization: Bearer <token>` |
| Its own header, a different value format, or a gateway header | Leave **Token** empty and use **Add a header**. Up to three headers |
| An OAuth sign-in | Setup shows **This server signs you in through your browser**. Press **Sign in**, approve access in the provider's window, and come back |
| A key in the query string | It can't be sent. The MCP specification forbids a token in the query string |

**OAuth sign-in is shared.** One person signs in once, and the grant is used for every agent run and every user of the connection. There's no per-user sign-in. Mindset stores the tokens and refreshes them itself.

Some providers don't hand out clients automatically. Setup tells you so, and you supply a client ID (and a client secret, if the provider issued one) on the connection's **Overview** tab, created in the provider's own console with the redirect URI shown there. To renew the grant, press **Sign in again**.

## How tools are classified

Mindset decides whether each tool reads or writes when it discovers the tools, in this order:

1. **An admin's choice** is final. Discovery never changes it.
2. **The server's own hints.** `destructiveHint: true` makes it a write. Otherwise `readOnlyHint: true` makes it a read, and `readOnlyHint: false` makes it a write.
3. **A model's reading.** Tools still unanswered are sent to a model in one batch, which reads each tool's name and description. Only answers it's highly confident in are kept.
4. **Not recorded.** Anything still unanswered is treated as a write at every check, so it needs consent before an agent can call it.

Each tool has an **Access** select (**Read** or **Write**) with a note saying where its marking came from, such as "Inferred from this operation's name and description" or "Not recorded for this operation". Change it to correct the marking. Your choice then survives every later discovery.

A read needs no approval. A write needs consent, given once per operation. See [Approve what an agent can do](https://docs4.mindset.ai/docs/ams/approve-what-an-agent-can-do).

## Try a tool, and tested status

Enabling a tool makes no call to the server. To see one work, open it on the **Tools** tab and use **Run this tool**, or **Run all enabled** to try every enabled tool. Each tool shows **Tested** or **Untested**: it's tested once a call to it has succeeded. See [Test before it goes live](https://docs4.mindset.ai/docs/ams/test-before-it-goes-live).

The **Tools** tab also shows tool-quality suggestions, such as vague names or short descriptions. They don't block anything. Take them seriously anyway: a bad description means the model picks the wrong tool on every run.

## Make it available to agents

A tool can be offered to agents only when it has a description and every one of its parameters has a description, because the model picks the tool and fills in its parameters from them. The **Tools** tab shows a missing description next to the tick.

Then add the tool on the agent's **Resources** tab, save a version and activate it. See [What saving actually does](https://docs4.mindset.ai/docs/ams/what-saving-actually-does).

## When the server changes

Whoever runs the server can add, remove, rename or change its tools without telling you.

- **A tool you never enabled can't be used.** New tools arrive switched off.
- **A tool you enabled can change underneath you.** The name stays the same and the behavior doesn't.
- **Press Discover tools** on the **Overview** tab when you know the server changed. Your settings survive.
- **A tool the server stops offering** is marked **Withdrawn by the server** and switched off. If a later discovery brings it back, it keeps its settings but stays off until you enable it again.

For more on changes at the other end, see [When a connected system changes](https://docs4.mindset.ai/docs/ams/when-a-connected-system-changes).

## Change it later

The address and the credential are locked on the **Settings** tab. To change either, use **Set this up again**, which checks the new one works before it goes live. You can change the name and description directly.

**Settings** also has **Send attribution labels to this server**. Turn it on only for a server you control: every tool call to it then carries the labels your backend set on the session or run.

## What can go wrong

**"That runs a program on your own machine".** You pasted a local (stdio) server's command. Ask the vendor for a remote address.

**The sign-in window never finishes.** Setup gives up waiting after a while and says nothing was lost. Press **Sign in** again.

**The provider won't register a client.** Create one in the provider's console with the redirect URI from the **Overview** tab, and paste its client ID there.

**A tool can't be ticked for agents.** It or one of its parameters has no description. Ask the server's owner to add one.

**A tool call takes too long.** A call to a tool on an MCP server stops after 120 seconds. See [Limits and run behavior](https://docs4.mindset.ai/docs/ams/limits-and-run-behavior).

## You're done when

- The server's tools appeared under **What it can do**, and they're the ones you expected.
- Only the tools the workflow needs are enabled.
- You've checked the **Access** marking of every enabled tool, and corrected any that are wrong.
- One tool returned data you checked against what you see in that product.