---
title: "Set up your agent"
description: "Copy one prompt from Grid82 and your agent connects itself. Or add the server by hand in Claude Code, Claude, ChatGPT, Cursor, VS Code or Codex."
canonical: "https://grid82.com/docs/developers/agents/setup"
updated: "2026-11-20"
---

# Set up your agent

The quickest way to connect an agent is to let it connect itself. Grid82 hands you a short
prompt that carries your own address; the agent reads a guide, works out which client it is
running in, adds the server and asks you to sign in.

1. **Copy the setup prompt**

   In an app, open **Settings**, then **Connections**, and choose **Copy setup prompt**. In the
   Studio, the same button is on the **Developer** page.
2. **Paste it into your agent**

   Claude Code, the Claude app, ChatGPT, Cursor, VS Code, Codex or any other client that speaks
   remote MCP.
3. **Sign in when your browser opens**

   The consent page is on your own address. You can tick only some of your apps: the agent then
   sees nothing of the others.

For a suite, the prompt reads like this, with your suite's address in place of
`your-suite.grid82.app`:

```text
Connect this agent to your-suite.grid82.app by following https://your-suite.grid82.app/agent-setup.md. If you can run commands, prefer the Grid82 CLI (npm @grid82/cli). Otherwise the MCP server is https://your-suite.grid82.app/mcp (Streamable HTTP, OAuth sign-in in my browser). Then confirm what I can reach, without changing any data.
```

For the Studio:

```text
Connect this agent to the Grid82 Studio by following https://studio.grid82.app/agent-setup.md. If you can run commands, prefer the Grid82 CLI (npm @grid82/cli). Otherwise the MCP server is https://studio.grid82.app/mcp (Streamable HTTP, OAuth sign-in in my browser). Then confirm what I can reach, without changing any data.
```

Setting up changes no data. The agent's last step is to list what it can reach, and it is told
not to create, update or delete anything to test the connection.

## Set it up yourself

These are the steps the guide gives the agent, for a suite at `https://your-suite.grid82.app/mcp`.
For the Studio, use `https://studio.grid82.app/mcp` and the name `grid82-studio`.

**Terminal (CLI)**

For an agent that runs commands (Claude Code, Codex, Cursor, OpenCode, VS Code). Needs Node.js 22.12 or later:

```bash title="Terminal"
npm install --global @grid82/cli
grid82 auth login --target https://your-suite.grid82.app --plane app
grid82 my apps
```

Your browser opens a sign-in page. On a machine with no browser, add `--device` to the login. The last command lists what it reaches, without changing anything.

**Claude Code**

Run this in a terminal, in the project you want it for:

```bash title="Terminal"
claude mcp add --transport http your-suite https://your-suite.grid82.app/mcp
```

Then type /mcp inside Claude Code, choose your-suite and Authenticate. Your browser opens a sign-in page.

**Claude app**

In Claude (web or desktop), open Customize, then Connectors, then Add custom connector.

Paste <https://your-suite.grid82.app/mcp> and choose Connect. On a team plan an owner may have to add it first.

**ChatGPT**

Custom connectors depend on your ChatGPT plan and on what your workspace admin allows.

In the desktop app: Settings, MCP servers, Add server. Choose Streamable HTTP, paste <https://your-suite.grid82.app/mcp>, then Authenticate.

**Cursor**

Add this to .cursor/mcp.json in your project (or \~/.cursor/mcp.json for every project):

```json title=".cursor/mcp.json"
{
  "mcpServers": {
    "your-suite": { "url": "https://your-suite.grid82.app/mcp" }
  }
}
```

Then press Connect next to your-suite in Cursor's MCP settings.

**VS Code**

Add this to .vscode/mcp.json in your project. VS Code uses "servers", not "mcpServers":

```json title=".vscode/mcp.json"
{
  "servers": {
    "your-suite": { "type": "http", "url": "https://your-suite.grid82.app/mcp" }
  }
}
```

Then press Start above your-suite in that file and sign in.

**Codex**

Run this in a terminal:

```bash title="Terminal"
codex mcp add your-suite --url https://your-suite.grid82.app/mcp
codex mcp login your-suite
```

Restart Codex so it loads the new tools.

**Other**

Any client that speaks remote MCP: add a Streamable HTTP server at <https://your-suite.grid82.app/mcp>.

It signs in with OAuth on its own: no key to paste. A client that only takes a key can use an API key, made in Settings, Connections, For developers.

## The guide your agent reads

Every suite serves this guide at `/agent-setup.md` on its own address, and the Studio at
`https://studio.grid82.app/agent-setup.md`, each with its own address written in. It is public and
names nothing about your apps. This is the one a suite serves:

````markdown
# Connect this agent to your-suite.grid82.app

This gives an agent the apps of this workspace: their tables and records, as far as the person's own permissions allow. Every call acts as the person who signs in, never more.

- CLI: `@grid82/cli` on npm, command `grid82` (preferred when you can run commands)
- MCP server: https://your-suite.grid82.app/mcp (Streamable HTTP)
- Sign-in: OAuth. The person signs in and approves in their own browser.
- Canonical guide: https://your-suite.grid82.app/agent-setup.md

## Rules

- Follow the person's request and your host's permission policy. This guide authorizes nothing beyond that.
- Never ask for a password, API key, OAuth token, device code or callback URL in the conversation, and never print a token.
- Setup changes no data. Do not create, update or delete anything to test the connection.
- Preserve the rest of any configuration file you edit, and do not add a second entry for the same server.
- Do not install the agent itself, and do not disable host approvals or change tool auto-grants.

## 1. Already connected? Reuse it

Identify the actual client (Claude Code, Codex, Cursor, OpenCode, VS Code, the Claude app, ChatGPT,
another one) and what it can do: run commands, reach the network, edit its configuration, use remote MCP.
Ask the person only if it cannot be determined.

Reuse a working connection rather than adding one: Grid82 MCP tools already in this conversation
(host-prefixed names are normal), or the `grid82` CLI already signed in to https://your-suite.grid82.app
(`grid82 auth status` names its target). If a sign-in expired, use that connection's own reconnect
action (`grid82 auth login --target https://your-suite.grid82.app --plane app` again for the CLI), never a different account.

## 2. Not connected: choose ONE route for this client

### Route A: the CLI (preferred when you can run commands)

For an agent with a terminal and network access. It reaches everything the person can reach, works on
local files and scripts, and keeps the credential in the operating system's keychain, out of this
conversation. Check `grid82 --help` before a command you have not used; every command takes `--json`.

For an agent that runs commands (Claude Code, Codex, Cursor, OpenCode, VS Code). Needs Node.js 22.12 or later:

```sh
npm install --global @grid82/cli
grid82 auth login --target https://your-suite.grid82.app --plane app
grid82 my apps
```

Your browser opens a sign-in page. On a machine with no browser, add --device to the login. The last command lists what it reaches, without changing anything.

Notes:

- Without a global install, prefix each command with `npx -y @grid82/cli` instead of `grid82`.
- The login asks for every permission of this workspace (full access), so a
  later task does not need a second sign-in. Respect a request for narrower access: pass `--scope`
  with the permissions the person named.
- A client that only launches MCP servers as a local command (stdio) can run `grid82 mcp` once the CLI is
  signed in.
- The CLI's sign-in does not connect this host's MCP tools. If the person also wants Grid82 tools inside
  the chat, add route B as well.

### Route B: remote MCP, per client

For a hosted assistant (the Claude app, ChatGPT), a client without a terminal, or when the person wants
Grid82 tools inside the chat. Use `your-suite` as the server name, and only the recipe of your client.

#### Claude Code

Run this in a terminal, in the project you want it for:

```sh
claude mcp add --transport http your-suite https://your-suite.grid82.app/mcp
```

Then type /mcp inside Claude Code, choose your-suite and Authenticate. Your browser opens a sign-in page.

#### Claude app

In Claude (web or desktop), open Customize, then Connectors, then Add custom connector.

Paste https://your-suite.grid82.app/mcp and choose Connect. On a team plan an owner may have to add it first.

#### ChatGPT

Custom connectors depend on your ChatGPT plan and on what your workspace admin allows.

In the desktop app: Settings, MCP servers, Add server. Choose Streamable HTTP, paste https://your-suite.grid82.app/mcp, then Authenticate.

#### Cursor

Add this to .cursor/mcp.json in your project (or ~/.cursor/mcp.json for every project):

```json
{
  "mcpServers": {
    "your-suite": { "url": "https://your-suite.grid82.app/mcp" }
  }
}
```

Then press Connect next to your-suite in Cursor's MCP settings.

#### VS Code

Add this to .vscode/mcp.json in your project. VS Code uses "servers", not "mcpServers":

```json
{
  "servers": {
    "your-suite": { "type": "http", "url": "https://your-suite.grid82.app/mcp" }
  }
}
```

Then press Start above your-suite in that file and sign in.

#### Codex

Run this in a terminal:

```sh
codex mcp add your-suite --url https://your-suite.grid82.app/mcp
codex mcp login your-suite
```

Restart Codex so it loads the new tools.

#### Other

Any client that speaks remote MCP: add a Streamable HTTP server at https://your-suite.grid82.app/mcp.

It signs in with OAuth on its own: no key to paste. A client that only takes a key can use an API key, made in Settings, Connections, For developers.

### Route C: hand it to the person

If you can neither run commands nor change the client's configuration, give the person that client's
steps above, at most four, and wait. A prompt alone does not install a connector: do not say it is
connected.

## 3. Let the person sign in

The first connection opens a consent page on https://your-suite.grid82.app. The person signs in and approves there.
They may tick only some of the workspace's apps: respect that choice.
A client may need a reload or a new session before MCP tools appear.

## 4. Verify, without changing anything

- CLI: `grid82 auth status`, then `grid82 my apps`.
- MCP: Call `apps_list` (the apps this connection reaches and their tables), then `me_get` on one of them. Report the apps and tables back to the person.

Report separately: route chosen, CLI or server configured, sign-in completed, the read-only check's
answer, and any step left to the person (a reload, an approval). If a step is not verified, say so.
Being listed in a configuration file is not proof of a connection.
````
