Folderly MCP

Connect Folderly to ChatGPT, Claude, Claude Code, Codex, or another compatible
Model Context Protocol (MCP) client. Once connected, the assistant can work
with the Folderly account you approve without receiving your Folderly password.

Before you connect

You need:

a Folderly account;
the Admin role for the Folderly account you want to connect;
an MCP client that supports remote Streamable HTTP servers;
permission to add custom connectors or MCP servers in that client.

Use this MCP server URL:

https://api.folderly.com/mcp

The /mcp path is required.

What the connection can access

During authorization, Folderly asks you to select one account. Every tool call
is restricted to that account.

The current integration can:

list and inspect mailboxes without exposing mailbox credentials;
update safe mailbox metadata;
create Gmail and Outlook connect or reconnect links;
list, inspect, create, and update email templates;
view Folderly state and statistics;
update Folderly settings, attach or detach templates, and stop Folderly for
a mailbox;
view Inbox Insights tests and recurring-test reports;
disable recurring Inbox Insights tests.

Folderly does not expose API-key management, mailbox passwords or tokens,
destructive deletes, inbox-test execution, or actions that send email through
this MCP connection.

Connect from ChatGPT

ChatGPT uses OAuth for the Folderly connection. An API key is not required.

Open ChatGPT Plugins in ChatGPT on the web.
Select + and then Add custom MCP server.
Enter Folderly as the name.
Under Connection, paste the Folderly MCP server URL shown above.
Select OAuth as the authentication method. If ChatGPT asks for the
client-registration method, select Client ID Metadata Document (CIMD).
Do not enter a client ID or client secret.
Review the warning and select I understand and want to continue.
Select Create as a plugin.
Complete the Folderly sign-in and consent screen. Select the Folderly
account you want to connect and approve access.
Install the new plugin from your personal or workspace plugins.
Start a new Work conversation, type @, and select Folderly.

Custom MCP availability can be controlled by ChatGPT workspace policy. If the
option to add a server is missing, ask your workspace administrator to enable
it.

Connect from Claude

Claude Pro or Max

Open Customize → Connectors.
Select + Add → Add custom connector.
Enter Folderly as the connector name and paste the MCP server URL.
Review the authentication settings detected by Claude.
Under Authentication, select Sign in now or Sign in when needed.
Under OAuth client, select Use Claude's published identity
(Recommended).
Select Add, then complete the Folderly sign-in and consent screen.

Claude Team or Enterprise

A workspace owner first adds the connector from Organization settings →
Connectors → Add → Custom → Web. Use the same server URL and choose Use
Claude's published identity (Recommended).

After the connector is available, each Folderly administrator who needs access
opens Customize → Connectors, finds Folderly, and selects Connect.

Enable Folderly for a conversation through + → Connectors in the chat
composer.

Connect from Claude Code

Add Folderly as a remote HTTP server:

claude mcp add --transport http --scope user folderly \
  https://api.folderly.com/mcp

Then:

Start Claude Code.
Run /mcp.
Select Folderly and authenticate in the browser.
Confirm the connection with claude mcp list or /mcp.

Omit --scope user if the connection should only be available in the current
project.

Connect from Codex

Codex CLI

Add the server and start OAuth authorization:

codex mcp add folderly \
  --url https://api.folderly.com/mcp

codex mcp login folderly

Complete the Folderly sign-in and consent flow in the browser, then verify the
connection:

codex mcp list

Inside the Codex terminal UI, use /mcp to inspect active servers.

Codex IDE extension

Open the gear menu and select MCP servers.
Select Add server.
Enter folderly, choose Streamable HTTP, and paste the MCP server URL.
Save the server and restart the extension.
Select Authenticate next to Folderly and complete authorization in the
browser.

Codex CLI and the Codex IDE extension share the same MCP configuration.

Connect with an API key

OAuth is recommended because access is account-scoped, renewable, and can be
revoked as a connected app. Use an API key only with clients that support a
custom Authorization header.

Send the key as a Bearer token:

Authorization: Bearer YOUR_FOLDERLY_API_KEY

For Codex, keep the key in an environment variable and reference it from
~/.codex/config.toml:

export FOLDERLY_API_KEY="YOUR_FOLDERLY_API_KEY"

[mcp_servers.folderly]
url = "https://api.folderly.com/mcp"
bearer_token_env_var = "FOLDERLY_API_KEY"

For a Claude custom connector, choose No sign in and add this request
header:

Authorization: Bearer YOUR_FOLDERLY_API_KEY

On shared Claude Team or Enterprise connectors, a fixed request header may be
used by every member who can use that connector. Do not configure a personal
or broadly privileged API key there unless shared access is intentional.

ChatGPT's custom MCP connection flow does not accept a manually entered Bearer
API key. Use OAuth for ChatGPT.

Try the connection

Start with a read-only request:

Use Folderly to show which account is connected and list its mailboxes.

Other examples:

Use Folderly to show today's statistics for [email protected].

List the recurring Inbox Insights tests and show the latest run for the first
active test.

Show the current Folderly settings for [email protected]. Do not change
anything.

For a write request, review the tool call and its arguments before approving
it:

Update the alias of [email protected] to "Outbound US" using Folderly.

Disconnect or revoke access

To revoke an OAuth connection from Folderly:

Open Folderly → Settings → API access.
Select the Connected apps tab.
Find the ChatGPT, Claude, or Codex connection.
Select Revoke and confirm.

Folderly rejects subsequent requests from that connection immediately. To use
it again, complete the OAuth connection flow again.

Also disconnect or remove Folderly in the AI client to clear its locally stored
connection and tokens. Revoking only in the client and revoking in Folderly are
complementary actions:

Folderly revoke blocks server-side access to the selected Folderly
account;
client disconnect removes the connection and locally stored credentials
from ChatGPT, Claude, or Codex.

API keys are managed separately in Settings → API access → API Keys.
Revoking a connected app does not revoke an API key, and revoking an API key
does not revoke OAuth connections.

Troubleshooting

The authorization page says access is not allowed

Only Folderly account administrators can authorize MCP access. Confirm that
your user has the Admin role for the selected account.

The client cannot discover Folderly authentication

Confirm that the server URL is HTTPS and ends with /mcp. Remove the existing
connection and add it again if it was created before OAuth was enabled.

The connection stopped after it was working

The connection may have been revoked, the Folderly user's role may have
changed, or the account may no longer be available. Reconnect the app and
select an account you can administer.

Tools or descriptions look outdated

Refresh the MCP server in the client, or remove and reconnect it. In ChatGPT,
open the plugin details and select Refresh. Start a new conversation after
refreshing.

A write action asks for confirmation

This is expected. Clients may require confirmation for tools that update
Folderly data or settings. Read the proposed tool name and arguments before
approving the action.