> ## Documentation Index
> Fetch the complete documentation index at: https://docs.heffl.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect Heffl to AI (MCP)

> Let Claude, ChatGPT, or Cursor work with your Heffl data — no coding, no API keys

# Connect Heffl to your AI assistant

You can connect Heffl to AI assistants like **Claude**, **ChatGPT**, and **Cursor** so they can look up and update your Heffl data for you — right inside a normal chat.

Once connected, you can simply ask things like:

> "Show me my open deals over AED 50,000."
>
> "Create a contact for Sarah at Acme, email [sarah@acme.com](mailto:sarah@acme.com)."
>
> "List tasks due this week and mark the Acme follow-up as done."

The assistant does the work in Heffl for you. No spreadsheets, no API keys, no setup files.

<Note>
  This uses a standard called **MCP** (Model Context Protocol). You don't need
  to know what that means — just follow the steps for your app below.
</Note>

## Supported apps

<CardGroup cols={3}>
  <Card title="Claude" icon="https://cdn.jsdelivr.net/npm/simple-icons@16.23.0/icons/claude.svg" href="#connect-your-app">
    Free or paid
  </Card>

  <Card title="ChatGPT" icon="https://api.iconify.design/logos/openai-icon.svg" href="#connect-your-app">
    Paid plan required
  </Card>

  <Card title="Cursor" icon="https://cdn.jsdelivr.net/npm/simple-icons@16.23.0/icons/cursor.svg" href="#connect-your-app">
    Free or paid
  </Card>
</CardGroup>

## Before you start

You'll need:

* A **Heffl account** you can sign in to (the same email and password you normally use).
* One of the supported apps shown above.
* This one address, which you'll paste into your app:

```
https://api.heffl.com/api/mcp
```

<Tip>
  Copy that address now — every app below asks you to paste it in one box.
</Tip>

## Connect your app

<Tabs>
  <Tab title="Claude" icon="https://cdn.jsdelivr.net/npm/simple-icons@16.23.0/icons/claude.svg">
    <Steps>
      <Step title="Open Claude settings">
        Go to [claude.ai](https://claude.ai), click your **profile icon** in the
        corner, and choose **Settings**.
      </Step>

      <Step title="Open Connectors">
        In the sidebar, click **Connectors**. Scroll to the bottom and click
        **Add custom connector**.
      </Step>

      <Step title="Paste the Heffl address">
        In the box that appears, paste:

        ```
        https://api.heffl.com/api/mcp
        ```

        You can name it **Heffl**. Click **Add**.
      </Step>

      <Step title="Sign in to Heffl">
        A Heffl sign-in window opens. Log in with your usual email and password.
      </Step>

      <Step title="Choose your team and approve">
        If you belong to more than one team, pick the team the assistant should
        use. Then click **Authorize** to allow access.
      </Step>

      <Step title="Done">
        Heffl now appears in your connectors. Start a new chat and ask Claude
        about your Heffl data.
      </Step>
    </Steps>
  </Tab>

  <Tab title="ChatGPT" icon="https://api.iconify.design/logos/openai-icon.svg">
    <Warning>
      Custom connectors in ChatGPT require a **paid plan** (Plus, Pro, Team,
      Business, or Enterprise) and **Developer Mode** turned on. The free plan
      can't add custom connectors.
    </Warning>

    <Steps>
      <Step title="Turn on Developer Mode">
        In ChatGPT, go to **Settings → Apps** (or **Connectors**) →
        **Advanced settings**, and turn on **Developer mode**.

        On a Business/Enterprise workspace, an admin may need to enable this
        under **Workspace Settings → Connectors**.
      </Step>

      <Step title="Create a connector">
        Go to **Settings → Connectors** and click **Create** (or
        **New connector**).
      </Step>

      <Step title="Paste the Heffl address">
        For the server URL, paste:

        ```
        https://api.heffl.com/api/mcp
        ```

        Name it **Heffl** and save.
      </Step>

      <Step title="Sign in to Heffl">
        A Heffl sign-in window opens. Log in with your usual email and password.
      </Step>

      <Step title="Choose your team and approve">
        If you belong to more than one team, pick the team the assistant should
        use, then click **Authorize**.
      </Step>

      <Step title="Done">
        In a chat, open the **apps / connectors** menu and turn on **Heffl** to
        let ChatGPT use it.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Cursor" icon="https://cdn.jsdelivr.net/npm/simple-icons@16.23.0/icons/cursor.svg">
    <Steps>
      <Step title="Open MCP settings">
        In Cursor, open **Settings** and find the **MCP** (or **Tools**)
        section. Click **Add new MCP server**.
      </Step>

      <Step title="Add the Heffl server">
        Choose a remote / URL server and paste:

        ```
        https://api.heffl.com/api/mcp
        ```

        Or, if Cursor asks for a config file, use:

        ```json theme={null}
        {
          "mcpServers": {
            "heffl": {
              "url": "https://api.heffl.com/api/mcp"
            }
          }
        }
        ```
      </Step>

      <Step title="Sign in and approve">
        The first time you use it, a Heffl sign-in window opens. Log in, pick a
        team if asked, and click **Authorize**.
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Choosing a team

If your Heffl login has access to **more than one team**, the sign-in step asks
you to **pick one team**. The assistant will only see and change data in that
team.

To switch the assistant to a different team later, **remove the Heffl connector
and add it again**, then pick the other team when you sign in.

## What the assistant can do

Once connected, the assistant can help with the same things you can do in Heffl,
for example:

| You can ask…                               | It will…                    |
| ------------------------------------------ | --------------------------- |
| "List my contacts at Acme."                | Find contacts and show them |
| "Create a deal for Acme worth AED 80,000." | Add a new deal              |
| "What invoices are unpaid this month?"     | Look up invoices            |
| "Add a task to call Sarah tomorrow."       | Create a task               |
| "Update Acme's stage to Won."              | Change the record           |

<Warning>
  The assistant makes **real changes** in your Heffl account — creating a
  contact or deal actually creates it. There's no practice mode. Read what it's
  about to do before approving an action.
</Warning>

## Is it safe?

* The assistant signs in **as you** and can only do what your Heffl role allows.
* It only ever touches the **one team** you picked during sign-in.
* You never share your password with the AI app — you log in on Heffl's own
  secure page, just like signing in to the website.
* You can disconnect anytime by removing the Heffl connector in your app's
  settings.

## Troubleshooting

<AccordionGroup>
  <Accordion title="My app says it can't connect">
    Double-check the address is exactly `https://api.heffl.com/api/mcp` with no
    extra spaces. Then remove the connector and add it again.
  </Accordion>

  <Accordion title="The sign-in window didn't appear">
    Your browser may have blocked a pop-up. Allow pop-ups for the app, remove
    the Heffl connector, and add it again so the sign-in window can open.
  </Accordion>

  <Accordion title="I picked the wrong team">
    Remove the Heffl connector in your app's settings and add it again. When the
    Heffl sign-in appears, choose the correct team.
  </Accordion>

  <Accordion title="ChatGPT won't let me add a connector">
    Custom connectors need a **paid ChatGPT plan** and **Developer Mode** turned
    on. On a company workspace, ask your admin to enable custom connectors.
  </Accordion>

  <Accordion title="It says I don't have permission to do something">
    The assistant can only do what your Heffl user is allowed to do. If you
    can't perform the action in Heffl yourself, the assistant can't either — ask
    your Heffl admin to adjust your permissions.
  </Accordion>
</AccordionGroup>

## For developers

<Accordion title="Technical details" icon="code">
  The MCP server is exposed at `https://api.heffl.com/api/mcp` using the
  **Streamable HTTP** transport and authenticates with **OAuth 2.1** (dynamic
  client registration — clients register themselves, no manual API key).

  Every [API v2](https://docs.heffl.com/api-v2/introduction) operation is offered as a tool, named
  `<object>_<action>` (e.g. `contacts_list`, `deals_create`, `tags_list`).
  Tools run with the signed-in user's role and are scoped to the team chosen
  during the OAuth flow (the team is carried in the access token). Calls are
  rate-limited to 200 requests per minute per token.

  Prefer writing your own code instead? Use the
  [REST API](https://docs.heffl.com/api-v2/introduction) with an `x-api-key` header — see
  [Authentication](https://docs.heffl.com/api-v2/authentication).
</Accordion>