# Connecting an MCP server

Let a person decide whether an agent may use an MCP server: where it runs, who runs it and what it can do.

For: Admins and agent owners adding a tool source.

Web page: https://candor.themethodic.com/screens/connect-mcp-server

## Layouts

### Consent dialog

Pick it when: The default: a short, deliberate step before anything connects.

Layout: A dialog listing the server's host, its owner and its tools by name, with Connect and Cancel.

Items:

- **MCP connect** (`mcp-connect`, Pro; https://candor.themethodic.com/docs/mcp-connect.md): Consent to connect: where it runs, who runs it, what it says it can do (its tools, by name).
- **Copy field** (`copy-field`, free; https://candor.themethodic.com/docs/copy-field.md): A value to copy, such as a callback URL.
- **Locked** (`locked`, free; https://candor.themethodic.com/docs/locked.md): Connect stays locked, with the reason, until the person has seen the tools.

```bash
npx candor-ui add mcp-connect copy-field locked
```

### Connections page

Pick it when: Many servers to see, review and remove.

Layout: A list of connected servers with status, then the open server's tools, each with its permission.

Items:

- **Settings layout** (`settings-layout`, Pro; https://candor.themethodic.com/docs/settings-layout.md): Sections down the side.
- **Tool permissions** (`tool-permissions`, Pro; https://candor.themethodic.com/docs/tool-permissions.md): What each of the server's tools may do.
- **MCP input** (`mcp-input`, free; https://candor.themethodic.com/docs/mcp-input.md): The input a tool takes, shown as it is.

```bash
npx candor-ui add settings-layout tool-permissions mcp-input
```

### A server's own UI in the thread

Pick it when: The server ships an MCP App and the person uses it in the conversation.

Layout: A thread with an isolated frame holding the app between two messages.

Items:

- **MCP app frame** (`mcp-app-frame`, Pro; https://candor.themethodic.com/docs/mcp-app-frame.md): An MCP App isolated in a sandbox on another origin; without a sandbox it says why instead.
- **Thread** (`thread`, free; https://candor.themethodic.com/docs/thread.md): The conversation around it.
- **Composer sources** (`composer-sources`, Pro; https://candor.themethodic.com/docs/composer-sources.md): The connected servers in the composer's @ menu, each saying whether it is connected, needs signing in or can't be used, and why.

```bash
npx candor-ui add mcp-app-frame thread composer-sources
```

## Rules that matter most here

- **Unknown stays unknown** (https://candor.themethodic.com/principles#unknown-stays-unknown): A server's own description of its tools is shown as the server's claim, not as verified.
- **A control that can't be used says why** (https://candor.themethodic.com/principles#locked-says-why): Connect says why it's not yet available, for example that the tools haven't been shown.
- **Say what can and can't be undone** (https://candor.themethodic.com/principles#say-what-can-be-undone): Removing a server says which agents lose which tools.

## Brief for a coding agent

Paste this to the agent that builds the screen.

```text
Build the connect-an-MCP-server step with Candor UI: McpConnect asks for consent, naming where the server runs, who runs it and what it says it can do (its tools, by name).
Show the tool list as the server's own claim; Candor does not verify it.
Connect stays locked (Locked) until the tools have been shown, and says why.
After connecting, list the server's tools in ToolPermissions; new tools start as ask first.
A server's own UI (an MCP App) goes in McpAppFrame, isolated in a sandbox on another origin; without a sandbox, the frame says why it isn't shown.
Removing a server says which agents lose which tools.

Start from the "Consent dialog" layout: A dialog listing the server's host, its owner and its tools by name, with Connect and Cancel.
Candor items: mcp-connect (https://candor.themethodic.com/docs/mcp-connect.md), copy-field (https://candor.themethodic.com/docs/copy-field.md), locked (https://candor.themethodic.com/docs/locked.md).
Install: npx candor-ui add mcp-connect copy-field locked
Read each item's docs before using it and take its props from there; don't guess them. Pro and Premium items need the person's licence key, which they add with `npx candor-ui key <key>`; don't ask for it.
```