Connecting a client | Zep Documentation

This page is for end users connecting an MCP client to their own memory. If you administer the project, see Configuring authentication first.

What you need

An MCP client that supports remote servers over Streamable HTTP and OAuth 2.1 with PKCE. Claude, ChatGPT, Claude Code, Codex, and Cursor are common examples.
The universal Zep MCP endpoint:
```
https://api.getzep.com/mcp
```
The host above is for Zep’s managed cloud. BYOC deployments use the same /mcp path on their own API host.
An account with the identity provider your organization uses. You sign in with the same credentials you use elsewhere; Zep never sees your password.

Connect

The endpoint URL stays the same across Zep projects. Zep uses your work email to find your organization’s identity provider, then determines which projects your verified identity can access.

Add the server to your client

Add a remote MCP server and paste the endpoint URL. Consult the client documentation for the location of its remote-server settings.

The client authenticates against Zep. Zep sends you to your organization’s identity provider. Do not register the MCP client as an OAuth application on that identity provider.

The client must support OAuth 2.1 with PKCE against the MCP server. Zep issues public clients (token_endpoint_auth_method=none). A host that requires a confidential OAuth client on your identity provider does not match this flow.

Enter your work email

The client opens a Zep page. Enter your work email so Zep can find your organization’s identity provider. Your work email domain must already be set up for MCP, through Google Workspace or your organization’s Custom OIDC configuration.

Select a project when prompted

If your identity can access more than one project, choose the account and project to connect. Zep selects it automatically when only one project is available and refuses the connection when none are available.

Approve the connection

Zep shows a consent screen naming the client and the access it requests: reading your memory, and writing to it if your administrator allows writes. Approve to finish connecting.

After sign-in, the client lists Zep’s tools and can work with your memory. Sessions are short-lived and renew automatically while your access remains valid.

The selected project is fixed in the signed token. To use another project, reconnect and choose it during sign-in. A client cannot switch the project attached to an existing token.

What you can do

Your client always has access to your own memory in this project. The user-graph tools operate on your graph implicitly. You never pass a user or project identifier, and you cannot select anyone else’s user graph or another project.

Read access is always available:

Search your memory for context relevant to a query: a ready-to-use context block by default, or raw observations, thread summaries, episodes, entities, or facts.
Get a narrative summary of who you are, drawn from your memory.
Explore how your memory connects: get an entity’s direct neighbors with get_node_neighbors, or a bounded multi-hop neighborhood with get_subgraph. Search with scope=nodes first to find the entity UUIDs these tools need.
List your raw ingested episodes, most recent first, with list_episodes.

If your administrator has enabled access to shared Context Graphs, you can also:

Read zep://graphs/directory for a paginated overview of the other graphs you can access.
List the other graphs you can access with list_graphs.
Search one by passing its graph_id to search_graph_in.
Explore or list one with get_subgraph_in, get_node_neighbors_in, and list_episodes_in.
Add information to one with add_memory_to_graph when writes are enabled.

Graph directory describes how directory listing and metadata search relate to the SDKs and to content search.

Which shared Context Graphs appear depends on the connection’s authorization mode. Project-wide mode exposes every shared Context Graph in the selected project. UserGroup ABAC mode exposes only graphs granted to your effective UserGroups. An unauthorized graph is indistinguishable from one that does not exist.

Write access is available when your administrator has enabled writes for the connection (the default). When it is enabled, you can add new memory as text, JSON, or a message. If writes are disabled, the write tool does not appear, and a write attempt is refused.

Troubleshooting

Sign-in does not start or the client reports no authorization server. Confirm that the client uses the /mcp URL for your Zep deployment.
Zep cannot find your identity provider. Confirm that you entered your work email. Ask your administrator whether Google Workspace is connected for your domain, or whether your domain is assigned on the account’s Custom OIDC configuration.
No projects are available after sign-in. Your verified identity is not eligible for any enabled MCP connection. Ask your administrator to check the connection’s admission gates, user-mapping, and provisioning settings.
You are signed in but cannot connect. Your identity may not be admitted: your email domain or group may be outside the connection’s allowed list, or your user may not exist yet and just-in-time provisioning is off. Ask your administrator to admit you or provision your account.
Write tools are missing. The connection is read-only, or the account-level writes kill switch is engaged. In UserGroup ABAC mode, your UserGroups must also grant the selected graph’s write action.
Shared Context Graph tools are missing. Allow standalone graphs is off on the project connection.
The connection stops working after a while. Tokens are short-lived and renew automatically up to the connection’s grant maximum lifetime. If renewal fails, the grant has reached that ceiling or your administrator disabled the connection; reconnect to sign in again.