Connect an external AI client, such as Claude Code or ChatGPT, to Hoppflow over MCP so it can work from what your company knows. The client acts as you, in one workspace, and can never do more than your role allows. Anything it proposes to change goes through approvals.
Before you begin
- You need a member seat. Guest seats cannot connect a client.
- To let a client read, your role needs View knowledge and brain.
- To let it propose actions, your role needs View approvals and at least one of View integrations or edit rights on meetings, tasks or knowledge.
Choose how the client signs in
There are two ways, and the first is the one to use:
- Sign in from the client. You add Hoppflow in the client, the client opens Hoppflow's consent screen in your browser, and you approve. Hoppflow creates the grant for you. The client renews its own access.
- Paste a short-lived token. Only for a machine where a browser sign-in is not possible. You create a grant in Hoppflow and copy a token into the client's configuration. The token lasts minutes, so you copy a new one each time it expires.
Get the server URL
-
Open External AI clients
Open Settings and, under Your account, choose External AI clients.
-
Copy the Server URL
Under Set up a client, copy the value shown after Server URL:. Use it wherever the steps below say
<SERVER_URL>.
Create a grant ahead of time
Signing in from the client creates a grant automatically. Skip this section unless you need the token fallback or want to set the grant up ahead of time.
-
Name the client
On External AI clients, in New grant, enter a Client name, for example "Claude Code on my laptop".
-
Set how long it lasts
Set Valid for (days, at most 30). It starts at 7.
-
Choose scopes
Under Scopes, tick Read, Propose actions, or both. Read is ticked by default. Connect and List tools are always included, and you can only delegate what your own role allows.
-
Create the grant
Choose Create grant. Hoppflow confirms with "Created <name>. It expires <date>." The grant appears under Grants.
The grant is for the workspace you have open. To create one for another workspace, switch to it first.
| Scope | What the client may do |
|---|---|
| Connect | Open a session with this workspace's brain. Always included. |
| List tools | See which tools the client may call. Always included. |
| Read | Read knowledge you can already see yourself. Your role and each item's access still apply. |
| Propose actions | Propose actions in your name. Every one goes through approvals. Nothing is executed directly. |
Copy a short-lived token
For the token fallback only: on a live grant, choose Copy short-lived token. The token goes to your clipboard and is never shown on screen. Hoppflow says how many minutes it lasts. Copy a new one when it expires.
Set up your client
Each client has its own setup. Replace <SERVER_URL> with the URL you copied.
Claude (web)
-
Add a custom connector
In Claude, open Settings > Connectors and add a custom connector.
-
Enter the server URL
Give it a name and enter your server URL.
-
Approve in Hoppflow
Claude opens Hoppflow's consent screen. Pick one workspace, review the scopes and choose Approve.
-
Turn it on in a chat
In a chat, enable the connector. Claude lists the tools your grant allows.
Claude's custom connectors do not take a pasted token. This client always signs in through the consent screen.
Claude Code
-
Add the server
Run this command:
claude mcp add --transport http hoppflow <SERVER_URL> -
Sign in
Run
/mcpinside Claude Code and choose to authenticate. Your browser opens Hoppflow's consent screen. Pick the workspace and approve. -
Check the connection
Run
/mcpagain at any time to see the connection and the tools your grant allows.
Only if you cannot sign in from that machine, add the server with a short-lived token instead:
claude mcp add --transport http hoppflow <SERVER_URL> --header "Authorization: Bearer <TOKEN>"
Codex
The Codex CLI, the Codex IDE extension and Codex in the ChatGPT desktop app share one configuration file, ~/.codex/config.toml. One setup serves all three.
-
Add the server and sign in
Run these commands:
codex mcp add hoppflow --url <SERVER_URL> codex mcp login hoppflowThe login opens Hoppflow's consent screen. Pick the workspace and approve.
-
Reload
Reload the IDE window or restart the desktop app. Hoppflow then shows in the MCP list with the tools your grant allows.
Only if you cannot sign in from that machine, put a short-lived token in the server's headers in ~/.codex/config.toml.
ChatGPT desktop
-
Add the server
In the ChatGPT desktop app, open Settings > MCP servers > Add server, and enter your server URL.
-
Authenticate
Choose Authenticate. Your browser opens Hoppflow's consent screen. Pick the workspace and approve.
Codex inside the desktop app reads the same ~/.codex/config.toml as the Codex CLI. If you already added Hoppflow there, it is available without a second setup.
ChatGPT (web)
ChatGPT on the web does not let a member paste an MCP server URL. Its MCP tools come from plugins that a ChatGPT workspace admin installs.
-
Ask your ChatGPT admin
Ask your ChatGPT workspace admin to install Hoppflow as a plugin, and give them your server URL.
-
Sign in when you enable it
When you enable the plugin, ChatGPT sends you to Hoppflow's consent screen. Pick your workspace and approve. Each member grants their own access. The admin's install never speaks for anyone else.
Gemini CLI
-
Add the server
Add Hoppflow under
mcpServersin~/.gemini/settings.json:{ "mcpServers": { "hoppflow": { "httpUrl": "<SERVER_URL>" } } } -
Sign in
Run
/mcp auth hoppflow. Your browser opens Hoppflow's consent screen. Pick the workspace and approve. -
Check the connection
Run
/mcpto see the server's status and the tools your grant allows.
Only if you cannot sign in from that machine, send a short-lived token in the headers instead:
{
"mcpServers": {
"hoppflow": {
"httpUrl": "<SERVER_URL>",
"headers": { "Authorization": "Bearer <TOKEN>" }
}
}
}
Approve on the consent screen
When a client signs in, Hoppflow asks "Let <client> work in your workspace?" If you are not signed in to Hoppflow, you sign in first.
-
Review what you are granting
Read What approving grants. It lists the scopes the client asked for.
-
Choose a workspace
Under Workspace, choose one workspace. A workspace where your role cannot grant what the client asked for is marked "(your role cannot grant this here)".
-
Choose how long access lasts
Under Access lasts, choose 1 day, 7 days, 14 days or 30 days. You can revoke it any time from Settings.
-
Approve
Choose Approve, or Deny to refuse. Hoppflow returns you to the client.
What a connected client can do
A client sees only the tools its scopes allow. See the scope table under Create a grant ahead of time.
With Read, it can:
- Search and fetch what you could open yourself in Hoppflow.
- Build a context pack of up to 20 references you are allowed to see.
- Explain whether you may reach a source, without revealing anything you may not.
- List what you may do, so it does not guess.
With Propose actions, it can propose an action in your name, such as a Slack post. Each proposal waits in Approvals and runs only after a reviewer allows it. The client can check where its proposal stands, and withdraw a pending proposal it raised itself. There is no direct write.
Use Hoppflow to build a context pack for the work I am about to start. Include the current goal, the project documents that matter, the decisions that constrain the approach, and the open tasks with their owners and known risks.Give me a short brief with a source for each section, and pass on anything Hoppflow reports as restricted or missing rather than working around it.
Manage and revoke a grant
Each grant on External AI clients shows a status chip: Active, Expires soon (under 48 hours left), Expired or Revoked. A row also shows the workspace, when it was created, when it expires, when it was last used, and a link Audit trail for this grant.
-
Choose Revoke access
On the grant's row, choose Revoke access.
-
Confirm
The dialog says "Revoke <name>? Its tokens stop working immediately and any actions it proposed that are still pending are retired." Confirm to revoke.
After you revoke a grant:
- The client's access stops on its next request. It has to sign in again from scratch.
- Pending actions it proposed are retired. Actions a reviewer already approved are not undone.
Revoked grants are hidden. Choose Show <n> revoked to see them.
Access tokens last 15 minutes, and a grant lasts at most 30 days. If your role is narrowed, every grant narrows with it on the next request.