MCP Server (Beta)

Connect your AI tools to EmailShepherd using the Model Context Protocol (MCP). This enables external AI tools to be able to interact with EmailShepherd, including creating and updating emails.

EmailShepherd hosts the server at https://mcp.emailshepherd.com/mcp. Your client connects over Streamable HTTP with OAuth. It is a remote server, so there is nothing to install.

Authentication

The MCP server uses OAuth 2.1 with the Authorization Code flow and PKCE. There are two separate identities involved, and it’s worth being clear on what each one does:

The MCP App identifies the client software (Claude Desktop, ChatGPT, Cursor, etc.) connecting to your EmailShepherd workspace. An admin registers the app once for your organization and gets a client_id and client_secret. These credentials authenticate the app during the OAuth token exchange. They do not grant access to any data on their own, and they do not define what the app is allowed to do inside EmailShepherd.

The user is the person actually using the MCP client. The first time anyone connects, the client opens a browser to EmailShepherd, the user signs in with their own account, and approves a consent screen. The access token that comes back is bound to that specific user.

Because each user authenticates individually:

Every MCP request runs as the signed-in user, using their EmailShepherd role and permissions, optionally narrowed by the app’s permission scopes. The MCP server never uses a shared or admin-level identity.
Two teammates connecting the same MCP App get two different tokens and see only what their own accounts allow.
Actions taken through MCP are attributed to the user in the audit log, the same as actions taken in the web app.
The client_secret alone does not grant access to anything. Anyone who obtains a copy of it still has to complete the interactive OAuth login as a real EmailShepherd user before they can make a request.

Permission scopes

By default, the MCP App inherits each user’s own EmailShepherd permissions — it can’t do anything a user couldn’t already do in the web app.

If you’d like to restrict what users can do through the MCP server, you can narrow this further by selecting only certain permission scopes. Scopes only ever restrict access; they never grant a user abilities they don’t already have.

For example, you might want to set up an MCP App so that users can only:

Read data, not edit it
Read and edit data, but not delete anything

You choose the scopes when you create or edit an MCP App. The available actions are grouped by resource (Emails, Projects, Image library, and so on), and most offer Read, Write, and Delete. Leave an action unselected and no one can perform it through the app, even if their role normally allows it.

Setup

Before anyone in your organization can connect a client to the MCP server, an app must be pre-registered in EmailShepherd. Each client that connects identifies itself using credentials issued ahead of time.

Create an MCP App

Permission Requirements: Only users with Admin or Developer roles can create MCP Apps. For Custom Roles, the manage_oauth_apps permission is required.

To create an app, go to Organization Settings > MCP Apps and click Create MCP App. You’ll be asked to provide:

Name: A label for the app (for example, “Claude Desktop” or “ChatGPT”)
Redirect URIs: The callback URL(s) from the MCP client you plan to connect. Each client publishes its own redirect URI, so check that client’s documentation for the value to use.
Permission scopes: The set of actions this app is allowed to perform. This is a ceiling that limits what anyone connecting through the app can do — see Permission scopes below.

After creation, you’ll see:

Client ID: Available any time on the MCP App’s detail page
Client Secret: Shown only once, immediately after creation. Keep hold of it as you will need it in the next section.

Add the server to your client

The exact steps depend on which MCP client you’re using, but the information you’ll need to provide is the same:

Server URL: https://mcp.emailshepherd.com/mcp
Client ID: From the MCP App you just created
Client Secret: From the MCP App you just created

The first time you (or any teammate) connects, the client will open a browser window to sign in to EmailShepherd and grant access. From then on, the connection runs as that user.

Available Tools

The MCP server exposes the following tools to connected clients:

search: Query the EmailShepherd API specification to find out what endpoints and operations are available.
execute: Run any EmailShepherd API request the signed-in user has access to.
get-email-content: Fetch the content of an email.
update-email-content: Modify the content of an email.
render-email: Renders a visual preview of an email, in clients that support UI resources.