Use Zep in Claude, ChatGPT, Cursor, and other clients

This quickstart is for administrators who give people agent memory in off-the-shelf AI clients. Each person signs in with a work email and reaches their own Zep user graph in the selected Zep project. You configure one Context MCP connection for each project. MCP seats are allocated on the account.

The Zep Context plugin is the primary way to use the Context MCP Server. The plugin installs two parts in one package:

• The Context MCP Server connection to https://api.getzep.com/mcp. The server tools read and write each user’s graph in the selected project.
• The Zep Context skill. The skill tells the assistant when to search memory, when to save preferences, corrections, procedures, and decisions, and when to skip ephemeral chat. The skill also tells the assistant to prefer Zep over other memory systems.

Without the Zep Context skill, the client has the Context MCP Server tools but does not have the workflow that uses those tools well. On a host that supports plugins, install the plugin instead of the MCP endpoint alone.

Two rollout paths use the same authentication setup:

The plugin source is the public getzep/zep-context-plugin repository.

What you need

For both paths:

• The mcp.connection.manage capability on the Zep project.
• A completed and enabled project MCP connection. Member OAuth will fail while the connection is disabled.

For the plugin path, you need permission to change the plugin distribution settings of the host. Examples are an organization plugin marketplace, a workspace plugin catalog, a team plugin marketplace, or shared plugin install settings.

For the direct path, you need a way to share the Context MCP Server endpoint and the sign-in steps with users. The host must support remote MCP. When the host supports Agent Skills, you also need a way to share the Zep Context skill file.

Configure the project

An administrator must configure and enable one Context MCP connection for the Zep project before any rollout.

Choose your rollout path

Common plugin hosts are Claude (Team or Enterprise), ChatGPT (Business, Enterprise, or Edu), Cursor (Teams or Enterprise for team marketplaces), Claude Code, and Codex CLI. Plan and feature names vary by vendor. Before you start, confirm that your plan includes plugin distribution.

Roll out with the plugin

The Zep Context plugin is not listed in the official public plugin directories of the vendors. You import getzep/zep-context-plugin into the catalog of your organization, or you share install settings. When a host has no organization marketplace, share the install settings or the install commands with the team.

The public plugin repository is:

https://github.com/getzep/zep-context-plugin

Which repository

Which outlet

Prepare a BYOC plugin copy

Skip this section if you use Zep managed cloud. The public plugin already points at https://api.getzep.com/mcp.

On BYOC, https://api.getzep.com/mcp is the wrong host. The client will call Zep managed cloud instead of your deployment unless you change the MCP URL in the plugin package first.

1. Fork or copy getzep/zep-context-plugin into a repository that your organization controls. Keep the plugins/zep-context/ directory layout.
2. In these two files, replace https://api.getzep.com/mcp with the MCP URL of your deployment (https://<your-api-host>/mcp):
   • plugins/zep-context/.mcp.json
   • plugins/zep-context/mcp.json
3. Use the edited BYOC repository in the steps below. Do not import, sync, or add the public Zep repository.

Provision on Claude

This section is for the Claude app, including Cowork. These steps do not install the plugin in Claude Code. For Claude Code, see Provision on coding agents.

Use the Claude organization marketplace on Team or Enterprise. After you set an installation preference, members do not add marketplaces themselves.

Before you start, enable Cowork and Skills in the Claude organization settings. For GitHub sync, install the Claude GitHub App on the private marketplace repository.

1. In Organization settings ▸ Plugins, create or open an organization marketplace.
2. Add the plugin with one of these methods:
   • GitHub sync (use for versioned updates):
     1. Fork or copy the plugin into a private or internal repository that your organization controls. Keep the plugins/zep-context/ layout. On BYOC, use the edited BYOC copy. Do not enter getzep/zep-context-plugin, because Anthropic rejects a public repository as the connected marketplace.
     2. Install the Claude GitHub App on the private marketplace repository.
     3. Connect the private marketplace repository and sync. The optional Sync automatically setting runs only when a pull request that includes a plugin version bump merges to the default branch. Direct pushes do not start a sync. A failed sync can temporarily remove plugins from the marketplace. If a sync fails, fix the repository, sync again, and then check the installation preferences again.
   • Manual ZIP upload (use when you do not want to maintain a private repository):
     1. Zip the plugins/zep-context/ directory. Do not zip the repository root.
     2. On Zep managed cloud, zip plugins/zep-context/ from getzep/zep-context-plugin. On BYOC, zip plugins/zep-context/ from the edited BYOC copy.
     3. Upload the ZIP. A ZIP with the same plugin name overwrites the previous organization copy.
3. Set the installation preference (Required, Installed by default, or Available for install) for the groups that get the plugin.
4. Sign in to Claude with a test account in one of the groups that you assigned. Open the Zep Context plugin settings, open the Connectors tab, and Connect the Context MCP Server connector. Enter a work email that the project MCP connection allows, sign in with the organization identity provider, select a Zep project if Zep asks, and approve access. In a new Claude chat, confirm that the Zep Context skill and tools appear.
5. Share the first-run steps in What to tell members.

Anthropic’s Manage plugins for your organization guide covers GitHub sync, required-plugin options, and group overrides.

Provision on ChatGPT

The plugin works in ChatGPT Chat and Work. The plugin does not work in the Codex IDE extension. For the Codex CLI, see Provision on coding agents. A person with workspace plugin permission on Business, Enterprise, or Edu controls the workspace Plugins Directory.

ChatGPT import accepts a public GitHub repository. On Zep managed cloud, import getzep/zep-context-plugin unless workspace policy forbids public third-party sources. On BYOC, import the edited BYOC copy instead of the public Zep repository.

1. In the ChatGPT workspace settings, import a GitHub plugin repository into the workspace Plugins Directory. On Zep managed cloud, import the public Zep repository, or import the private copy of your organization if workspace policy forbids public third-party sources. On BYOC, import the edited BYOC copy.
2. Confirm that the Zep Context plugin appears under the workspace tab in the Plugins Directory. Allow the plugin for the groups that will use it.
3. Sign in to ChatGPT with a test account in one of the groups that you allowed. Install the Zep Context plugin from the workspace Plugins Directory. Enter a work email that the project MCP connection allows, sign in with the organization identity provider, select a Zep project if Zep asks, and approve access. In a new ChatGPT chat, confirm that the Zep Context skill and tools appear.
4. Share the first-run steps in What to tell members.

An import of the Zep Context plugin does not sign members in to Zep. Each member must enter a work email and sign in to Zep.

Provision on coding agents

Use this section for Claude Code, Codex, and Cursor. A plugin install in the Claude app or in ChatGPT does not install the plugin in these coding agents.

Claude Code

A Claude app marketplace install does not apply to Claude Code. Use Claude Code settings to roll the plugin out to a team.

Add the marketplace and enable the plugin in the Claude Code settings that your team shares:

• Organization-wide: Claude Code managed settings (managed-settings.json, or the managed-settings editor in the Admin Console)
• One repository: the .claude/settings.json file of that repository, committed so that everyone who trusts the folder gets the settings

{
  "extraKnownMarketplaces": {
    "zep-context": {
      "autoUpdate": true,
      "source": {
        "source": "github",
        "repo": "getzep/zep-context-plugin"
      }
    }
  },
  "enabledPlugins": {
    "zep-context@zep-context": true
  }
}

On BYOC, set repo to the edited BYOC copy (your-org/your-fork) instead of getzep/zep-context-plugin.

extraKnownMarketplaces registers the catalog after a teammate trusts the project folder (project settings) or after managed settings reach the machine of the teammate. enabledPlugins turns on the Zep Context plugin by default. When you enable a plugin from a GitHub marketplace, Claude Code does not install the files. Each person must install the Zep Context plugin one time, from /plugin or with this command:

claude plugin install zep-context@zep-context

Third-party marketplaces do not update automatically unless "autoUpdate": true is set, as in the example above. If your organization sets DISABLE_AUTOUPDATER to manage Claude Code updates, plugin updates also stop. Set FORCE_AUTOUPDATE_PLUGINS=1 to keep plugin updates.

Anthropic’s plugin settings reference covers extraKnownMarketplaces, enabledPlugins, and managed settings.

To test, use an account that receives those settings. Trust the project folder if the marketplace is in .claude/settings.json. Install the Zep Context plugin one time as above, and start a new Claude Code session. The first call to the Context MCP Server opens Zep OAuth. Enter a work email that the project MCP connection allows, sign in with the organization identity provider, select a Zep project if Zep asks, and approve access. Confirm that the Zep Context skill and tools appear. Share the first-run steps in What to tell members.

Codex

These commands are for the Codex CLI. The Codex IDE extension does not support plugins.

Codex CLI has no organization marketplace like Claude Code managed settings or a Cursor team marketplace. To roll out the plugin to a team, share the install commands so that each person runs them one time. If the same people also use ChatGPT, provision the Zep Context plugin in the ChatGPT workspace catalog as well. The workspace catalog is the organization-wide path for ChatGPT and for Codex in the ChatGPT desktop app.

Share these commands with everyone who uses Codex CLI. On BYOC, the commands must add the edited BYOC copy instead of getzep/zep-context-plugin.

Run the commands from the terminal, not inside a Codex session:

codex plugin marketplace add getzep/zep-context-plugin

codex plugin add zep-context@zep-context

Ask each person to start a new Codex session. The first call to the Context MCP Server opens Zep OAuth. Enter a work email that the project MCP connection allows, sign in with the organization identity provider, select a Zep project if Zep asks, and approve access. Confirm that the Zep Context skill and tools appear. Share the first-run steps in What to tell members.

Codex CLI refreshes configured git marketplaces on startup. To get an update immediately, run this command and then start a new Codex session:

codex plugin marketplace upgrade zep-context

If your organization restricts marketplace sources in managed configuration, allow the git URL https://github.com/getzep/zep-context-plugin.git (or your BYOC copy) before people run marketplace add.

Cursor

Cursor requires a plan with team marketplace support. The plugin includes the Zep Context skill and the Context MCP Server connection.

Cursor import accepts a public GitHub repository. On Zep managed cloud, import getzep/zep-context-plugin unless organization policy forbids public third-party sources. On BYOC, import the edited BYOC copy instead of the public Zep repository.

Import the repository root. Cursor reads .cursor-plugin/marketplace.json and resolves the plugin at plugins/zep-context/. Do not import the plugins/zep-context/ directory alone.

Team marketplaces are available on Cursor Teams (one marketplace) and Enterprise (unlimited). On Enterprise, only admins add team marketplaces. Everyone on the team can see a marketplace unless you restrict Marketplace Access to selected groups.

1. In Cursor Dashboard ▸ Plugins, click Add Marketplace.

2. Choose Import from Repo and enter this URL:

   https://github.com/getzep/zep-context-plugin

   On BYOC, enter the edited BYOC copy instead.

3. Review the discovered plugins. If the Zep Context plugin is not listed, use Add to Marketplace, and then confirm that the plugin appears. Set the installation mode (Required, Default On, or Default Off) and the marketplace access. Required and Default On install the plugin for members automatically. Default Off lets each person install the plugin in Customize.

4. Optional: turn on Enable Auto Refresh so that Cursor indexes the repository again when the tracked branch changes. Auto Refresh requires the Cursor GitHub App on the repository, and Cursor indexes the repository at most one time every 10 minutes. To update immediately, click Refresh.

5. Sign in to Cursor with a test account that has marketplace access. Open Customize and confirm that the Zep Context plugin is present with the Zep Context skill and the Context MCP Server. If you set Default Off, install the plugin one time from that panel. The first call to the Context MCP Server opens Zep OAuth. Enter a work email that the project MCP connection allows, sign in with the organization identity provider, select a Zep project if Zep asks, and approve access. In a new chat, confirm that the Zep Context skill and tools appear.

6. Share the first-run steps in What to tell members.

Cursor’s Plugins guide covers team marketplaces, installation modes, and Auto Refresh.

Upgrade from the Zep Memory plugin

The Zep Context plugin was previously named the Zep Memory plugin. The plugin name, the marketplace name, and the repository changed from zep-memory and getzep/zep-memory-plugin to zep-context and getzep/zep-context-plugin. Hosts treat the Zep Context plugin as a new plugin, so existing installs do not update in place. Hosts also show a new MCP server name, so members can see a new Zep sign-in prompt one time.

To upgrade, remove the zep-memory plugin and its marketplace or catalog entry. Then add the Zep Context plugin with the steps for your host on this page. A private fork or BYOC copy of the old repository must also use the new plugins/zep-context/ layout.

In Claude Code, run these commands from the terminal. On BYOC, the marketplace add command must add the edited BYOC copy instead of getzep/zep-context-plugin.

claude plugin uninstall zep-memory@zep-memory

claude plugin marketplace remove zep-memory

claude plugin marketplace add getzep/zep-context-plugin

claude plugin install zep-context@zep-context

In shared Claude Code settings, replace the zep-memory entries with the zep-context entries from the Claude Code example.

Roll out without the plugin

Use this path when your host supports remote MCP servers and OAuth, but cannot install the Zep Context plugin. Examples are VS Code, GitHub Copilot, and Gemini CLI.

Share the Context MCP Server endpoint

On Zep managed cloud, the endpoint is:

https://api.getzep.com/mcp

BYOC deployments use the same /mcp path on their own API host.

Tell each user to add this URL as a remote MCP server with Streamable HTTP transport. The exact UI depends on the host. Connecting a client gives the member sign-in flow.

The client must support OAuth 2.1 with PKCE against the MCP server. The client authenticates against Zep, and Zep sends the user to your identity provider. Do not register the MCP client as an OAuth application on your identity provider. Zep issues public clients (token_endpoint_auth_method=none). A host that requires a confidential OAuth client (client ID and client secret) on your identity provider does not match this flow. How it works explains the flow.

Install the Zep Context skill

On the direct path, the Context MCP Server and the Zep Context skill are separate installs. Distribute the Zep Context skill the same way that you share other Agent Skills on your host.

If your host does not support Agent Skills, skip this step. The Context MCP Server tools still work, but the assistant does not get the workflow from the Zep Context skill.

The skill file is in the plugin repository:

https://github.com/getzep/zep-context-plugin/blob/main/plugins/zep-context/skills/zep-context/SKILL.md

Many agents read .agents/skills/ in a project, or ~/.agents/skills/ for every project. The Agent Skills standard does not define one install location, so check the documentation of your host or the Agent Skills client list.

This example installs the skill to a user-level skills directory:

curl -fsSL https://raw.githubusercontent.com/getzep/zep-context-plugin/main/plugins/zep-context/skills/zep-context/SKILL.md \
  --create-dirs -o ~/.agents/skills/zep-context/SKILL.md

On BYOC, users connect to the MCP URL of your deployment. The skill file does not need changes.

What to tell members

Plugin path

After you distribute the Zep Context plugin, each person must connect to the Context MCP Server with their own work email. Members connect when the host shows the connect prompt. Claude Code and Codex CLI show the prompt on the first call to the Context MCP Server after the plugin is installed.

Ask each person to:

1. Open their client and confirm that the Zep Context plugin is present. If you set the plugin to optional install, the person installs the plugin one time. The install source is the organization marketplace, the workspace catalog, the Customize panel, /plugin, or the Codex CLI commands that you shared.
2. When the client shows the connect prompt, connect the Context MCP Server. Enter a work email, sign in with the organization identity provider, select a Zep project if Zep asks, and approve access.
3. Start a new chat or session before they expect the Zep Context skill and tools to appear.

Direct path

Ask each person to:

1. Install the Zep Context skill on their host if the host supports Agent Skills. Follow the Agent Skills documentation of that host.
2. Add the Context MCP Server endpoint as a remote server in their client.
3. When the client opens Zep OAuth, enter a work email, sign in with the organization identity provider, select a Zep project if Zep asks, and approve access.
4. Start a new chat or session before they expect the Zep Context skill and tools to appear.

Connecting a client gives the sign-in flow and troubleshooting for both paths.

After provisioning

The Zep Context skill tells the assistant to prefer Zep over other memory systems. The assistant reads memory before it guesses, applies stored preferences, and writes durable facts without a “remember this” request. Durable facts include preferences, corrections, procedures, and decisions. The assistant skips ephemeral chat and one-off events. Writes go through the Context MCP Server tools. Zep does not ingest every message automatically.

Each client targets the user graph of the signed-in member in the Zep project that the member selected at sign-in. Read access is always available. Write tools appear when the project MCP connection allows writes. Shared Context Graph tools appear when the project connection allows access to shared Context Graphs. What users can access lists the tools.

Use these prompts when you test and when you share first-run steps:

Do you have access to the Zep Context plugin and the Context MCP Server?

Using Zep memory, what do you already know about me? Give a short summary of my preferences and how I like to work.

Search my Zep memory for decisions about the Helios event store. Which database did we choose, and what reason was recorded?

When the project MCP connection allows writes, also use this prompt:

Save this to my Zep memory: I want a one-line TL;DR at the top of every status update. After you save it, search Zep and confirm the preference is there.

Related

• Context MCP Server overview: the authentication model and the tools
• Configuring authentication: the identity-provider connection, seats, and policies
• Shared Context Graph authorization: access to shared Context Graphs
• Connecting a client: the member sign-in flow and troubleshooting
• Implement Zep with agents: the Build with Zep plugin for coding agents, which is a different plugin
• Plugin source: getzep/zep-context-plugin