> For the complete documentation index, see [llms.txt](https://docs.keeping.com/help/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.keeping.com/help/mcp-server/connecting-to-keepings-mcp-server.md).

# Connecting to Keeping's MCP server

How to connect to Keeping's MCP server.

### Prerequisites

* A Keeping account with an active subscription
* MCP access turned on for your organization. It's on by default. Billing Admins can turn it off, and back on, in Organization Settings.

<figure><img src="https://1058495162-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCHa8WIsJ5Z5NqmPmq5VS%2Fuploads%2Fgit-blob-1ac819331dd16bf9262874483bb03aaec8367f44%2Fadmin-mcp-access.png?alt=media" alt=""><figcaption><p>Billing Admins Can Turn MCP Access On or Off</p></figcaption></figure>

### Connecting from Claude

Keeping is listed in Claude's connectors directory, so you can connect it in a couple of clicks without entering a server URL. One connection works everywhere you use Claude: the web app, the desktop app, the mobile apps, and Claude Code.

1. In Claude, go to **Customize → Connectors**. In the desktop app, click **Customize** in the sidebar, then **Connectors**.
2. Click **Discover** and search for **Keeping**.
3. Click **Connect** on the Keeping connector (listed as "by Keeping").
4. Sign in with the Google account you use for Keeping, choose how much access to give Claude (see [Permissions & Scopes](#permissions-and-scopes)), and click **Allow**.
5. Keeping now shows as **Connected** under **Yours**. Start a chat and try asking Claude something like *"Show me my open tickets"*.

Claude asks for approval before it uses a Keeping tool. To change that, open the Keeping connector under **Customize → Connectors** and adjust **Tool permissions**: read-only tools and write tools are listed separately, so you can allow one group and keep approval on the other.

{% hint style="info" %}
On Claude Team and Enterprise plans, an Owner adds Keeping for the organization first (**Organization settings → Connectors**), and then each person connects with their own Keeping login. If you see a **Request** button instead of **Connect**, click it to ask your Owner.
{% endhint %}

If you can't use the directory listing, you can still add Keeping manually: go to **Customize → Connectors**, click **Add custom connector**, and enter `https://mcp.keeping.com/` as the server URL. The sign-in flow is the same.

#### Claude Code

If you've connected Keeping in Claude as described above, it's already available in Claude Code when you sign in with the same Claude account. No extra setup is needed.

To add it to Claude Code directly instead, run:

```bash
claude mcp add keeping-mcp --transport http https://mcp.keeping.com/
```

Claude Code handles OAuth authentication automatically — you'll be prompted to sign in via your browser on first use.

### Connecting from Cursor

1. Open Cursor and go to **Settings → MCP**
2. Click **Add new MCP server**
3. Set the transport type to **HTTP**
4. Enter the server URL:

   ```
   https://mcp.keeping.com/
   ```
5. Cursor will prompt you to authenticate via your browser
6. Sign in with your Google account and authorize access

### Connecting from ChatGPT

Keeping works in ChatGPT on every plan, including Free. ChatGPT calls these connections **plugins**. You set Keeping up on the ChatGPT website, at [chatgpt.com](https://chatgpt.com), because ChatGPT doesn't let you add one from its mobile apps.

1. In ChatGPT on the web, click **Plugins** in the sidebar.
2. Click the **+** button, then **Add custom MCP server**.
3. Enter a name, such as **Keeping**, and an optional description.
4. Under **Connection**, enter the Keeping server URL:

   ```
   https://mcp.keeping.com/
   ```
5. Under authentication, choose **OAuth**. You don't need to enter a client ID or secret, because Keeping's server registers ChatGPT automatically.
6. Read the risk warning, select **I understand and want to continue**, and click **Create as a plugin**.
7. Sign in with the Google account you use for Keeping, choose how much access to give ChatGPT (see [Permissions & Scopes](#permissions-and-scopes)), and click **Allow**.

To use Keeping in a conversation, type `@` and choose Keeping, then ask something like *"Show me my open tickets"*. ChatGPT may ask you to approve an action before it makes a change. To change when it asks, open **Settings → Plugins**, select Keeping, and adjust its permissions.

{% hint style="info" %}
On ChatGPT Business, only workspace admins and owners can add a custom MCP server. On ChatGPT Enterprise and Edu, an admin has to give your role the **Create plugins with MCPs** permission first. If you don't see **Add custom MCP server**, ask your ChatGPT admin.
{% endhint %}

### Connecting from Gemini

You can connect Keeping to the Gemini web app, and developers can also connect it to Google's command-line coding agents.

#### Gemini web app

Gemini lets you add Keeping as a **custom app**. You set it up on the web, and it then also works in the Gemini mobile app.

Before you start, Google requires that you:

* use a **personal Google Account** to sign in to Gemini. Work and school accounts aren't supported for custom apps yet
* are 18 or older and in the United States
* have **Keep Activity** turned on in Gemini
* use Gemini in English

To connect Keeping:

1. Go to [gemini.google.com](https://gemini.google.com) in a browser on your computer.
2. At the bottom, click **Settings**, then **Connected Apps**. If you don't see **Connected Apps**, click **Personal Intelligence** first.
3. Under **Custom apps**, enter the Keeping server URL in the **Add a custom app link to get started** field. If you already have a custom app, click **Add a custom app** instead.

   ```
   https://mcp.keeping.com/
   ```
4. Click **Next** and follow the on-screen instructions. Sign in with the Google account you use for Keeping, review the permissions, and click **Allow**.

You don't need to enter any credentials under **Advanced features**. Keeping's server supports automatic client registration.

To use Keeping in a conversation, type `@` and choose Keeping, then ask something like *"Show me my open tickets"*. Gemini asks you to confirm any action that makes a change.

To disconnect, go to **Connected Apps**, open the Keeping app's **More details**, and click **Disconnect**, or click **Remove app** to remove it entirely.

#### For developers

Keeping also works in Google's command-line coding agents, Antigravity CLI and Gemini CLI. Add `https://mcp.keeping.com/` as a remote MCP server and sign in with your Google account when prompted. For the exact configuration, see Google's documentation for [Antigravity](https://antigravity.google/docs/mcp) and [Gemini CLI](https://geminicli.com/docs/tools/mcp-server/).

### Connecting from Other MCP Clients

Any MCP-compatible client can connect to Keeping using:

* **Server URL:** `https://mcp.keeping.com/`
* **Transport:** Streamable HTTP
* **Authentication:** OAuth 2.1 with PKCE (handled automatically by most clients)

The server supports OAuth Discovery via these standard endpoints:

* `https://mcp.keeping.com/.well-known/oauth-authorization-server`
* `https://mcp.keeping.com/.well-known/oauth-protected-resource`

### Connecting with a Personal Access Token

If your MCP client can't complete the OAuth 2.1 browser sign-in — for example a script, a server-side automation, or a custom-built client — you can authenticate with a **Personal Access Token (PAT)** instead. A PAT is tied to your own agent account and carries the same read and write permissions you have in Keeping.

<figure><img src="https://1058495162-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCHa8WIsJ5Z5NqmPmq5VS%2Fuploads%2Fgit-blob-2bda66066c4aaefb1a7217790c0909849eef6c7d%2Fpat-generate.png?alt=media" alt=""><figcaption></figcaption></figure>

**Prerequisites**

* MCP access must be turned on for your company. It's on by default. If you don't see the option below, ask a Keeping admin to check that MCP access hasn't been turned off in your company settings.
* A PAT carries the `mcp:read` and `mcp:write` permissions only. To use the admin tools that manage company settings, connect with OAuth instead. See [Permissions & Scopes](#permissions-and-scopes).

**Generate your token**

1. In Keeping, open **Settings** and select the **Preferences** tab.
2. Under **MCP Personal Access Token**, click **Generate Token**.
3. Copy the token immediately - it starts with `kp_at_` and is shown **only once**. Treat it like a password and store it somewhere secure. If you lose it, generate a new one.

**Use your token**

Send the token as a Bearer token in the `Authorization` header on every request to `https://mcp.keeping.com/`:

```
Authorization: Bearer kp_at_your_token_here
```

Most MCP clients have a field for a bearer token or a custom header. For a hand-built client, set the header on each request - for example:

```bash
curl https://mcp.keeping.com/ \
  -H "Authorization: Bearer kp_at_your_token_here" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"my-client","version":"1.0"}}}'
```

**Revoke or replace a token**

* Generating a new token from the **Preferences** tab automatically revokes your previous one.
* To turn off access entirely, click **Revoke Token** on the same screen. Revoking takes effect immediately.

**"Authentication failed" or 401 errors**

* Confirm the `Authorization` header is exactly `Bearer` followed by your token, with no extra spaces or quotes.
* The token may have been revoked or replaced by a newer one — generate a fresh token and try again.
* If all tokens are rejected, MCP access may have been turned off for your company; contact a Keeping admin or <support@keeping.com>.

### Permissions & Scopes

When you connect an AI tool, you choose how much access to give it:

| Choice                               | Permissions granted                                                | What your AI assistant can do                                                                                                                  |
| ------------------------------------ | ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| **Read only**                        | `mcp:read`                                                         | Read tickets and run reports. Write tools are hidden.                                                                                          |
| **Read and Write**                   | `mcp:read`, `mcp:write`                                            | Everything above, plus draft replies, tag, assign, add notes, and the other write tools.                                                       |
| **Read, Write, and Manage Settings** | `mcp:read`, `mcp:write`, `mcp:settings:read`, `mcp:settings:write` | Everything above, plus the admin tools that create and change mailboxes, agents, tags, templates, workflows, SLAs, and other company settings. |

Some details:

* **Manage Settings is for company admins on plans with Advanced MCP.** The option appears only if you're an admin. On a plan without Advanced MCP it shows as unavailable, with a note to contact Keeping to add it to your subscription. Admins on a plan with Advanced MCP who choose **Read only** or **Read and Write** also get read-only access to company settings, such as company settings, workflows, and SLAs.
* **Tools you can't use are hidden.** A read-only connection doesn't show write tools at all, so your AI assistant won't try to use them.
* **Deletes and many changes ask first.** Deleting a tag, template, workflow, or SLA, removing an agent, and many changes to existing settings require an explicit confirmation. Your AI assistant should ask you before confirming. See the [MCP tool reference](https://docs.keeping.com/help/mcp-server/mcp-tool-reference.md) for which tools do.
* **To change access later,** disconnect and reconnect the Keeping server in your AI tool, then choose a different option.

Your AI assistant will only be able to access the mailboxes and data that your Keeping account has permission to view. Existing team permissions are fully respected.

### Troubleshooting

#### "Authentication failed" or 401 errors

* Your access token may have expired. Most MCP clients refresh tokens automatically — try disconnecting and reconnecting.
* Make sure you're signing in with the same Google account you use for Keeping.

#### "Access denied" or 403 errors

* MCP access may have been turned off for your organization. A Billing Admin can turn it back on in Organization Settings, or contact <support@keeping.com>.
* Your Keeping subscription may have lapsed. Check your subscription status in Keeping settings.

#### "Tool not found" or missing tools

* Analytics tools require a Premium Reporting subscription. Upgrade at [keeping.com/pricing](https://keeping.com/pricing).
* Write tools require the **Read and Write** permission. Admin tools for company settings require **Read, Write, and Manage Settings**, and only company admins on a plan with Advanced MCP can choose it. Disconnect and reconnect with the access you need.
* PATs don't include the settings permissions. Use OAuth to reach the admin tools.
* Tools added after you connected appear once you reconnect. In ChatGPT, also open **Plugins**, select Keeping, and click **Refresh**.

#### Connection drops or timeouts

* The MCP server enforces rate limits to ensure stability. If you're making many requests in quick succession, wait a moment and try again.
* Check that your network allows outbound HTTPS connections to `mcp.keeping.com`.

#### "Mailbox not found" or empty results

* Your AI assistant can only access mailboxes your Keeping account has permission to view. Check your mailbox permissions in Keeping settings.

### Still need help?

Contact us at <support@keeping.com>.

### Authentication & Security

The Keeping MCP server uses **OAuth 2.1 with PKCE** for authentication — the same standard used by major platforms like Google and GitHub. Here's what that means for you:

* **You sign in with Google** — the same account you use for Keeping. No separate passwords or API keys to manage.
* **Access tokens expire after 1 hour** and are automatically refreshed, so your connection stays active without re-authenticating.
* **Refresh tokens are valid for 90 days.** After that, you'll need to re-authorize.
* **Tokens are encrypted** — Keeping never stores your raw tokens. Only a secure hash is kept.
* **Replay protection** — if a token is ever intercepted and reused, Keeping automatically revokes the entire token family.
* **You can revoke access at any time** by contacting <support@keeping.com>.
