# Giov MCP server

> Connect Claude, ChatGPT, Cursor, Codex, VS Code and more to Giov over MCP. Search the docs, or sign in to work in your workspace with the access you choose.

The Giov MCP server lets AI tools that speak the [Model Context Protocol](https://modelcontextprotocol.io) work with Giov. Ask your assistant how to install the widget, and it reads the current Giov docs. Sign in, and it can work in your workspace: read conversations and customers, update the CRM, set up GiovBot and more, with the Read and Write permissions you choose for each area.

It never sees secrets.

## Two addresses

| Address | Sign-in | Plans | What it offers |
|---|---|---|---|
| `https://mcp.giovchat.app/docs` | None | Anyone, no account needed | The public Giov docs |
| `https://mcp.giovchat.app/mcp` | Your Giov account, through OAuth | Pro, Business, Advanced | The docs, plus one workspace, with the permissions you choose |

Use the `/docs` address if you only want the docs, for example in a shared or public setup. Use `/mcp` to work with your own workspace. Both addresses, with the set-up snippets below, are also in **Settings → MCP & API**.

## Permissions

Like fine-grained access tokens, a connection gets **Read** and/or **Write** for each area of the workspace. Read lets the app look things up; Write lets it change them. Docs and workspace basics are always included.

| Area | Read | Write | Who can grant it |
|---|---|---|---|
| Conversations (messages, notes, quick replies) | ✓ | ✓ | Admins and agents |
| Customers & CRM (contacts, companies, tasks, visitors) | ✓ | ✓ | Admins and agents |
| Your profile (profile, notifications) | ✓ | ✓ | Everyone |
| GiovBot (agents, knowledge, tools, publishing) | ✓ | ✓ | Admins and developers |
| Copilot (setup, catalog, activity) | ✓ | | Admins and developers (not activity) |
| Channels & widget (channels, mailboxes, widget identity, push) | ✓ | ✓ | Admins and developers |
| Team (members, invitations) | ✓ | ✓ (resend or cancel invitations) | Admins |
| Analytics (reports, audit log) | ✓ | | Admins and developers (not the audit log) |
| Workspace settings (company, integrations, onboarding, billing details) | ✓ | ✓ | Admins and developers (plan summary only) |

Some tasks are never available to apps, so a person does them in the dashboard:

- Account and workspace deletion, security (two-factor, single sign-on, SCIM), connected apps and API keys themselves, billing changes, data exports and sign-in.
- **Even with Write**, apps can't invite people, change roles or remove members; connect or disconnect channels and mailboxes, or set push keys; change the widget's identity verification; add or change GiovBot tools (they call outside addresses); or connect Google Analytics. In workspace settings they can change the company name, defaults, widget, business hours and auto-reply, but not the AI provider, data retention or GiovBot's on/off switch.

Permissions belong to each connection: every app you connect has its own, chosen when you approve it and changed later from **Permissions** next to it. An app also acts as the person who connected it, so it can't do what that person's role doesn't allow. Each call must pass both.

## Tools

| Tool | What it does |
|---|---|
| `list_docs`, `search_docs`, `get_doc_page` | List, search and read the docs (also on `/docs`, without signing in) |
| `get_workspace`, `get_install_snippet` | Your workspace name, plan and role, and the widget code with your workspace ID for HTML, React, Next.js, Svelte, Vue, WordPress, React Native or Expo |
| `search_operations` | Finds the workspace tasks the connection may run, with their inputs. Tasks outside its permissions aren't listed; the result names the permissions that would unlock more |
| `call_operation` | Runs one of those tasks as the person who connected the app. Reads need Read on the task's area, changes need Write |
| `get_copilot_setup` | Copilot setup and the remaining steps (needs Read on Copilot) |
| `get_identity_setup`, `get_install_status` | Identity verification setup, and where the widget has been seen running (need Read on Channels & widget). Never secrets or keys |

> [!NOTE]
> Copilot is part of the Advanced plan. On other plans, `get_copilot_setup` says Copilot isn't included, and the other tools work as usual.

## Set up your client

Pick your client. Each one opens a Giov sign-in page the first time it connects.

```text title="Claude" tab="Claude"
1. Open Customize → Connectors (claude.ai/customize/connectors).
2. Choose Add custom connector.
3. Name it Giov and paste the URL: https://mcp.giovchat.app/mcp
4. Choose Add, then Connect, and approve the request in Giov.
```

```bash title="Terminal" tab="Claude Code"
claude mcp add --scope user --transport http giov https://mcp.giovchat.app/mcp
```

```bash title="Terminal" tab="Codex"
codex mcp add giov --url https://mcp.giovchat.app/mcp
codex mcp login giov
```

```text title="ChatGPT" tab="ChatGPT"
Add a custom connector in ChatGPT settings, paste https://mcp.giovchat.app/mcp and choose OAuth. Needs Business, Enterprise or Pro, on the web only; menu names change often.
```

```json title="~/.gemini/config/mcp_config.json" tab="Antigravity"
{
  "mcpServers": {
    "giov": {
      "serverUrl": "https://mcp.giovchat.app/mcp"
    }
  }
}
```

```bash title="Terminal" tab="Gemini CLI"
gemini mcp add --transport http giov https://mcp.giovchat.app/mcp
```

Gemini CLI is for Code Assist and API-key users. Everyone else uses Antigravity.

```json title="~/.cursor/mcp.json" tab="Cursor"
{
  "mcpServers": {
    "giov": {
      "url": "https://mcp.giovchat.app/mcp"
    }
  }
}
```

```json title=".vscode/mcp.json" tab="VS Code"
{
  "servers": {
    "giov": {
      "type": "http",
      "url": "https://mcp.giovchat.app/mcp"
    }
  }
}
```

```json title="~/.config/devin/mcp_config.json" tab="Windsurf (Devin Desktop)"
{
  "mcpServers": {
    "giov": {
      "url": "https://mcp.giovchat.app/mcp",
      "transport": "http"
    }
  }
}
```

Older Windsurf builds: `~/.codeium/windsurf/mcp_config.json`.

```json title="settings.json" tab="Zed"
{
  "context_servers": {
    "giov": {
      "url": "https://mcp.giovchat.app/mcp"
    }
  }
}
```

```json title="~/.kiro/settings/mcp.json" tab="Kiro"
{
  "mcpServers": {
    "giov": {
      "url": "https://mcp.giovchat.app/mcp"
    }
  }
}
```

```json title="~/.junie/mcp/mcp.json" tab="Junie"
{
  "mcpServers": {
    "giov": {
      "url": "https://mcp.giovchat.app/mcp"
    }
  }
}
```

```bash title="Terminal" tab="Amp"
amp mcp add giov https://mcp.giovchat.app/mcp
```

```bash title="Terminal" tab="Devin CLI"
devin mcp add giov https://mcp.giovchat.app/mcp
devin mcp login giov
```

```bash title="Terminal" tab="OpenCode"
opencode mcp add
# name: giov, type: remote, url: https://mcp.giovchat.app/mcp
opencode mcp auth giov
```

In Claude Code, run `/mcp` after adding the server and choose **giov** to sign in. In Codex, `codex mcp login giov` opens the sign-in. In Gemini CLI, run `/mcp auth giov` inside the CLI. In OpenCode, answer `opencode mcp add` with the name `giov`, type remote and the address. In Cursor and VS Code, start the server from the MCP list and follow the sign-in prompt. In the other editors, restart the app and sign in when asked.

Cursor, VS Code, Goose and Replit also have one-click install: choose **Install** under **Connect your coding agent** on the dashboard home, and the app opens with Giov ready to add. Replit asks you to authorize in the Project Editor. Devin (OAuth), Lovable, Bolt (MCP OAuth) and Copilot Studio (OAuth 2.0, Dynamic discovery) add a custom MCP server from their connector settings: paste the address and choose that OAuth option.

**Not supported yet.** These work with remote MCP servers but not with Giov's OAuth sign-in, or their sign-in is reported unreliable: GitHub Copilot cloud agent (no OAuth for remote servers), Roo Code, Continue, Cline in the IDE and JetBrains AI Assistant (OAuth not documented), and Augment (sign-in reported broken).

To use only the public docs, use `https://mcp.giovchat.app/docs` instead. No sign-in is needed.

## Approve the connection

When an app connects to `/mcp`, your browser opens a Giov approval page of its own, outside the dashboard. If you're already signed in to Giov in that browser, you go straight to approving. If you're signed out, you sign in on that page first, with a two-factor code if your account uses one. It then shows:

- **The app.** Its name comes from the app itself. When the app publishes its details on its own website, Giov also shows that verified domain. Otherwise the page says Giov can't verify the name, so only connect apps you trust.
- **Where you'll return.** The website the app sends you back to, or a note that it's an app on your computer or device.
- **The account** you're signed in with.
- **The workspace to connect.** An app connects to one workspace. Workspaces you can't use right now are greyed out with the reason, such as the Starter plan, an inactive seat, or a workspace that requires single sign-on or two-factor authentication.
- **Access.** Read only to start. Choose **Modify permissions** to pick Read and Write per area, or use **Select all**, **Read only**, **Write only** or **Clear**. You decide, whatever the app asked for; only areas your role doesn't allow are locked, with the reason.

Choose **Approve** to connect, or **Cancel** to send the app away without access. Each request works once and only for a few minutes; if it expires, start again from the app.

To connect another workspace, add the server again in your client and choose that workspace.

## Change an app's permissions

You can change what a connected app can read and change without reconnecting it:

1. Open **Settings → Profile → Connected apps**, or **Settings → MCP & API** if you're an admin.
2. Choose **Permissions** next to the app.
3. Tick Read and Write per area, or use the quick choices and the column headers, and choose **Save**.

The change applies to the app's next request. If the app then calls something it no longer has permission for, Giov tells it which permission is missing and where to turn it back on.

- **Docs** and **workspace basics** stay on while an app is connected. To remove them, revoke the connection.
- **Admins** can take a permission away from anyone's connection in the workspace, but can't add one to someone else's. Only the person who approved a connection can give it more, so they can also turn it back on. To stop an app for good, revoke the connection.
- **Turning a permission on** works like approving the app again: the workspace's rules (seat, single sign-on, two-factor, plan) apply, and you can give any permission your role allows, whatever the app asked for when it connected.

Every change is recorded in the audit log as `oauth.grant_scopes_changed`, with the permissions before and after. Every change an app makes in the workspace is recorded as `oauth.app_action`, with the app's name and the task it ran.

## Disconnect an app

- **Your own apps:** open **Settings → Profile → Connected apps** and choose **Revoke**. The app loses access right away.
- **Everyone's apps in a workspace:** admins can see every connection, with the account that approved it, in **Settings → MCP & API**, and revoke any of them.

A connection lasts up to 90 days. Resetting your password or turning off two-factor authentication also disconnects your apps. To keep using an app, connect it again.

If a workspace moves to the Starter plan, its connections pause. They work again after an upgrade.

## Security

- **Read and Write are separate.** An app can only change what it has Write for, area by area; without it, it can only look things up.
- **No secrets.** Identity secrets, provider keys, SCIM tokens and connection credentials are never returned.
- **Your role applies.** The app acts as you: it can't see or do more than your account can, and admin-only areas stay admin-only.
- **Checked on every call.** Giov checks the connection's permissions, your role, your seat and the workspace's plan and sign-in policy each time the app uses a tool. Each connection can make up to 120 calls a minute.
- **One workspace per connection,** chosen by you on the consent page.
- **Workspace policy applies.** If a workspace requires single sign-on or two-factor authentication, you need to meet that policy before you can connect it.