# Connecting to Keeping's MCP server

### Prerequisites

* A Keeping account with an active subscription
* MCP access enabled for your organization (contact <support@keeping.com> if needed)

### Connecting from Claude Desktop

1. Open Claude Desktop and go to **Settings** (gear icon)
2. Select **Integrations** or **MCP Servers**
3. Click **Add MCP Server**
4. Enter the following server URL:

   ```
   https://mcp.keeping.com/
   ```
5. Claude will open a browser window asking you to sign in with your Google account (the same one you use for Keeping)
6. Review the requested permissions and click **Allow**
7. You're connected! Try asking Claude something like *"Show me my open tickets"*

### Connecting from Claude Code (CLI)

Add the Keeping MCP server to your Claude Code configuration:

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

Claude Code will handle 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

ChatGPT supports MCP connections through its **Actions** or **Connectors** feature (availability may vary by plan):

1. In a ChatGPT conversation, look for the **MCP** or **Connect tools** option
2. Enter the Keeping MCP server URL:

   ```
   https://mcp.keeping.com/
   ```
3. Authenticate via the browser popup using your Google account
4. Once connected, ChatGPT can use your Keeping tools

### 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`

### Permissions & Scopes

When you connect an AI tool, you'll be asked to authorize one or both of these permission scopes:

* **`mcp:read`** — Access to all read and analytics tools
* **`mcp:write`** — Access to all write tools

You can grant read-only access if you only want your AI assistant to retrieve information without making changes.

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 not be enabled for your organization. Contact <support@keeping.com> to enable it.
* 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 `mcp:write` scope. Re-authorize with both read and write permissions.

#### 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>.