Enter to open, arrow keys to move, Escape to close

    Connecting tools

    Connect an AI client over MCP

    Let Claude, Codex, ChatGPT or Gemini CLI read your company brain and propose actions, under a grant you control.

    On this page

    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:

    1. 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.
    2. 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

    1. Open External AI clients

      Open Settings and, under Your account, choose External AI clients.

    2. 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.

    1. Name the client

      On External AI clients, in New grant, enter a Client name, for example "Claude Code on my laptop".

    2. Set how long it lasts

      Set Valid for (days, at most 30). It starts at 7.

    3. 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.

    4. 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.

    ScopeWhat the client may do
    ConnectOpen a session with this workspace's brain. Always included.
    List toolsSee which tools the client may call. Always included.
    ReadRead knowledge you can already see yourself. Your role and each item's access still apply.
    Propose actionsPropose 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)

    1. Add a custom connector

      In Claude, open Settings > Connectors and add a custom connector.

    2. Enter the server URL

      Give it a name and enter your server URL.

    3. Approve in Hoppflow

      Claude opens Hoppflow's consent screen. Pick one workspace, review the scopes and choose Approve.

    4. 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

    1. Add the server

      Run this command:

      claude mcp add --transport http hoppflow <SERVER_URL>
      
    2. Sign in

      Run /mcp inside Claude Code and choose to authenticate. Your browser opens Hoppflow's consent screen. Pick the workspace and approve.

    3. Check the connection

      Run /mcp again 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.

    1. Add the server and sign in

      Run these commands:

      codex mcp add hoppflow --url <SERVER_URL>
      codex mcp login hoppflow
      

      The login opens Hoppflow's consent screen. Pick the workspace and approve.

    2. 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

    1. Add the server

      In the ChatGPT desktop app, open Settings > MCP servers > Add server, and enter your server URL.

    2. 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.

    1. Ask your ChatGPT admin

      Ask your ChatGPT workspace admin to install Hoppflow as a plugin, and give them your server URL.

    2. 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

    1. Add the server

      Add Hoppflow under mcpServers in ~/.gemini/settings.json:

      {
        "mcpServers": {
          "hoppflow": {
            "httpUrl": "<SERVER_URL>"
          }
        }
      }
      
    2. Sign in

      Run /mcp auth hoppflow. Your browser opens Hoppflow's consent screen. Pick the workspace and approve.

    3. Check the connection

      Run /mcp to 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>" }
        }
      }
    }
    

    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.

    1. Review what you are granting

      Read What approving grants. It lists the scopes the client asked for.

    2. 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)".

    3. 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.

    4. 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.

    PromptPrepare context before coding
    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.

    1. Choose Revoke access

      On the grant's row, choose Revoke access.

    2. 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.

    Next steps