> ## Documentation Index
> Fetch the complete documentation index at: https://www.plain.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Set up Plain for a person

> Instructions for an AI agent: get the person signed up, connect the Plain MCP server, and set up their workspace.

You are an agent setting up Plain, a customer support platform, for the person you're working with. You do the setup through Plain's Model Context Protocol (MCP) server at `https://mcp.plain.com/mcp`, which signs in as that person with OAuth. Don't ask the person for an API key: the MCP server needs none, and an API key belongs to a machine user, not to them.

Follow the steps in order. Steps 1 to 4 only read. In step 5, nothing in the workspace changes until the person agrees to it.

When the person has to choose, such as which labels to create or which Slack channels to connect, use your host's question tool if it has one, such as `AskUserQuestion` in Claude Code. Otherwise ask in chat.

When you've handed the person something to do, such as signing up or approving Slack, and they say they're done, check it with a tool if you can, then move straight on to the next step.

Related resources:

* **MCP server reference**: [MCP server](https://www.plain.com/docs/integrations/mcp-server.md) lists every tool and host-specific troubleshooting
* **Docs index**: `https://www.plain.com/docs/llms.txt`
* **OAuth metadata**: `https://mcp.plain.com/.well-known/oauth-protected-resource/mcp`

## 1. Check for an existing connection

If Plain tools are already loaded in your session, call `getMyWorkspace`. When it returns a workspace, tell the person its name and ID and ask whether it's the workspace they want to set up. A connection is bound to one workspace, so it might be the wrong one. If it is the right one, go to step 4.

If no Plain tools are loaded, ask whether the person already has a Plain workspace. If they do, or they gave you a workspace ID (it starts with `w_`), go to step 3 and check after connecting that `getMyWorkspace` returns that workspace. Otherwise, or if `getMyWorkspace` fails with `No workspace ID provided`, start at step 2.

## 2. Have the person sign up and create a workspace

The person signs up themselves. You can't create an account or a workspace for them. Send them this link and wait for them to say they're done:

```plaintext theme={null}
https://app.plain.com/get-started
```

Tell them to:

1. Sign up with Google or their work email
2. Name their workspace when Plain asks
3. Come back to you once the workspace exists

Don't connect the MCP server before the workspace exists. The connection gets bound to an account with no workspace, every tool fails with `No workspace ID provided`, and the person has to reconnect.

## 3. Connect the Plain MCP server

Add the server for the host you're running in. Every host opens a browser window for the person to sign in to Plain and pick the workspace. The person must finish that sign-in themselves.

### Claude Code

Run this command, then ask the person to run `/mcp`, select `plain`, and choose **Authenticate**:

```bash theme={null}
claude mcp add --transport http --scope user plain https://mcp.plain.com/mcp
```

Claude Code loads the Plain tools once authentication finishes. If they don't appear, ask the person to restart Claude Code.

### Codex

Run this command. Codex detects that the server uses OAuth and opens the browser sign-in:

```bash theme={null}
codex mcp add plain --url https://mcp.plain.com/mcp
```

### Cursor

Add the server to `~/.cursor/mcp.json`, or to `.cursor/mcp.json` in the project:

```json theme={null}
{
  "mcpServers": {
    "plain": {
      "url": "https://mcp.plain.com/mcp"
    }
  }
}
```

Cursor shows a **Needs login** prompt next to Plain. Ask the person to click it.

### Claude and Claude desktop

You can't add a connector from inside a chat. Ask the person to:

1. Go to **Customize** → **Connectors**
2. Click **+**, then **Add custom connector**
3. Name it `Plain` and set the URL to `https://mcp.plain.com/mcp`
4. Click **Connect** next to the new connector and sign in

On a Team or Enterprise plan, only an admin can add custom connectors. If the person isn't an admin, they need to ask theirs.

### ChatGPT

Ask the person to:

1. Turn on Developer Mode in **Settings** → **Apps** → **Advanced settings**
2. Click **Create app**, name it `Plain`, and set the URL to `https://mcp.plain.com/mcp`
3. Set authentication to **OAuth**, click **Create**, and sign in

If **Advanced settings** is missing, the person's ChatGPT admin has to allow custom apps.

### Other hosts

Any host that supports remote MCP servers over HTTP with OAuth works. Point it at `https://mcp.plain.com/mcp`. If your host can't connect to remote MCP servers, tell the person you can't set up Plain from here and send them to [Claude](https://claude.ai) or ChatGPT with the steps above.

When the connection is up, call `getMyWorkspace` and confirm the workspace name with the person.

### Find Plain's apps

Some Plain tools open an app: an interactive Plain view inside the chat where the person reviews and edits what you set up. Hosts that render MCP Apps show the view. Other hosts get the same result as text.

* **Find them**: search your Plain tools for ones whose description says they show the person a view, such as `suggestLabels` and `showWorkflow`
* **Always use one when it exists**: after you make a change, or to propose one, open the app for it so the person can check and change your work
* **Don't repeat the view**: when an app shows the result, don't list the same details again in chat

## 4. Read the setup checklist

Call `workspaceSetup`. It returns the same onboarding checklist the person sees in the Plain app, with a `steps` list of `key` and `isComplete`. Also call `getLabels`, `workflows` and `workspaceSlackChannelIntegrations` so you know what already exists. Tell the person in a sentence what's done and what's left.

If `workspaceSetup` returns a not-yet-implemented error, the checklist isn't available for this workspace. Work through step 5 from what the other reads returned, and treat each step's status as unknown. Any other error goes to [If something fails](#if-something-fails).

## 5. Walk the person through each step

Go through the steps that aren't complete one at a time, in the order of the table below, which follows the onboarding in the Plain app. Two steps don't go by the checklist: include `CONNECT_CHANNELS` while `connectedSlackChannels` is empty, and always include `SET_UP_WORKFLOWS`. Leave out email and `SET_UP_TIERS` for now, even if the checklist lists them. Finish each step before you start the next, and don't save steps for a list at the end:

* **A step you can do with tools**: tell the person exactly what you'll create, wait for a yes, do it, then show the result
* **A step the person does in the app**: give them that step's link, wait for them to say they're done, check it with a tool if you can, then move on
* **A step the person wants to skip**: move on

| Step key | What to do |
| - | - |
| `CONNECT_CHANNELS` | The checklist marks this complete once Slack is installed, even with no channels connected, so judge it by `connectedSlackChannels` instead. If `workspaceSlackChannelIntegrations` returns none, give the person the Slack install link, which takes them straight to Slack to approve. When they say they're done, call `workspaceSlackChannelIntegrations` and `connectedSlackChannels` to confirm Slack is connected and which channels are. Installing Plain doesn't join any channels, so if `connectedSlackChannels` is empty, ask the person to add the Plain app to a channel in Slack, then check again when they say they're done. Move on once a channel is connected or the person skips it. Don't set up channel rules unless the person asks. |
| `INVITE_TEAM` | The person invites teammates in the app. Give them the invite link. |
| `CREATE_LABEL_TYPES` | Call `suggestLabels` with labels that fit the person's support, so they can review and create them in the app. If it isn't available, check `getLabels` so you don't duplicate any, then create the agreed labels with `createLabelType`. |
| `SET_UP_SIDEKICK` | The person picks the Sidekick Agent's tools in the app. Give them the Sidekick Agent integrations link. |
| `SET_UP_WORKFLOWS` | Do this step even when the checklist marks it complete. Plain creates workflows with every workspace. Show them with `showWorkflow`, or list them if it isn't available, as the premade workflows for auto-labeling, priority and investigation. Tell the person to ask if they have questions, or say done to move on. If they want more detail about a workflow or want to change one, read `workflowBuilderGuide` first: it explains the triggers and every step. Change a workflow only if the person asks. |

Once the checklist steps are done, offer test threads: `createAllTestThreads` fills the inbox with example conversations from test customers, so the person can practice replying.

If you change a workflow, watch for 2 traps:

* **Unpublished by default**: `createWorkflow` creates a draft, and the checklist only counts a published workflow. If the person doesn't approve publishing with `updateWorkflow`, report it as a draft.
* **Steps get replaced**: `bulkUpsertWorkflowSteps` deletes every step you don't pass it. Never run it on an existing workflow without the complete list of steps.

Some hosts, such as Claude, ask the person to approve each tool call, so batch your writes within a step where a tool allows it.

### Links

Replace `workspace_id_here` with the ID from `getMyWorkspace`, which starts with `w_`. Never send a link with a placeholder in it.

| Page | Link |
| - | - |
| Slack install | `https://app.plain.com/workspace/workspace_id_here/install/slack` |
| Invite teammates | `https://app.plain.com/workspace/workspace_id_here/settings/members/add` |
| Sidekick Agent integrations | `https://app.plain.com/workspace/workspace_id_here/sidekick/integrations` |

If the workspace syncs its members from a directory, the invite page redirects to the members list. The person adds teammates in their identity provider instead.

## 6. Finish in the Plain app

When every step is done or skipped, give the person:

* **What you set up**: a short list, grouped by checklist step
* **What they skipped**: each with its link, so they can come back to it
* **Their workspace**: `https://app.plain.com/workspace/workspace_id_here`

## If something fails

| Error | What to do |
| - | - |
| `No workspace ID provided` | The connection was made before a workspace existed. Have the person create one (step 2), then re-authenticate the MCP server. |
| `403` after OAuth completes | The token is missing the `openid offline_access` scopes. Have the person disconnect and reconnect the MCP server. If your host lets you set scopes, request both. |
| A tool is missing | The host cached an old tool list. Disconnect and reconnect the MCP server. |
| A permission error | The person's role in Plain doesn't allow that action. An admin can do it, or change their role. |
| Anything else | Tell the person to email [help@plain.com](mailto:help@plain.com) with their workspace ID, the error, and the host they're using. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.