> For the complete documentation index, see [llms.txt](https://guide.hardfin.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://guide.hardfin.com/advanced-options/ai-assistants.md).

# Connect AI assistants

Connect an AI assistant to Hardfin to look up and work with your Hardfin records in plain language. You can ask it questions like "Which assets are deployed at Acme's warehouse?" or hand it routine updates, without exporting data or writing code.

{% hint style="success" %}
An AI assistant always acts with **your own permissions** in Hardfin. It can never see or do more than you can.
{% endhint %}

## Choose how to connect

How you connect depends on the assistant you use.

| You use                                                                           | Connect with                  | Steps                                                     |
| --------------------------------------------------------------------------------- | ----------------------------- | --------------------------------------------------------- |
| Claude (claude.ai or the Claude app) or ChatGPT                                   | The Hardfin connector         | [Add the Hardfin connector](#add-the-hardfin-connector)   |
| A coding assistant, such as Claude Code, Codex, Cursor, GitHub Copilot or VS Code | The Hardfin plugin            | [Install the Hardfin plugin](#install-the-hardfin-plugin) |
| An assistant that runs commands in a terminal                                     | The Hardfin command line tool | [Use the Hardfin CLI](#use-the-hardfin-cli)               |

The plugin and the command line tool also install the **Hardfin skills**: instructions that teach an assistant how Hardfin's records fit together and how to work with them, such as how to import your spreadsheets. An assistant with the skills makes fewer mistakes, so install them wherever your assistant supports them.

## Add the Hardfin connector

1. In your AI assistant, add a custom connector (some assistants call it an "MCP server" or an "integration") with this URL:

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

   In ChatGPT, custom connectors are available only on some plans and may need your workspace administrator to turn them on.
2. When your assistant asks you to sign in, log in to Hardfin with your usual password, Google, or Microsoft sign-in.
3. Review the **Connect to Hardfin** screen. It shows:
   * The name of the assistant asking to connect
   * The email address you are signed in with
   * **Organization it will act in**: choose one if you belong to more than one organization
   * The access level, **Read and write** or **Read only**: see [Access levels](#access-levels)
4. Select **Allow** to finish connecting, or **Cancel** to stop without connecting.

{% hint style="warning" %}
If the **Connect to Hardfin** screen shows a caution that the application described itself to Hardfin, only continue if you started the connection from that assistant yourself.
{% endhint %}

## Install the Hardfin plugin

The Hardfin plugin connects a coding assistant to Hardfin and installs the Hardfin skills. Install it in the assistant you use:

| Assistant                             | Install                                                                                                          |
| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| Claude Code                           | Run `/plugin marketplace add hardfinhq/skills`, then `/plugin install hardfin@hardfin`                           |
| Codex                                 | Run `codex plugin marketplace add hardfinhq/skills`, then `codex plugin add hardfin@hardfin`                     |
| Cursor                                | In Customize, choose **From GitHub Repository** and enter `https://github.com/hardfinhq/skills`                  |
| GitHub Copilot CLI                    | Run `copilot plugin install hardfinhq/skills`                                                                    |
| VS Code                               | In the Command Palette, run **Chat: Install Plugin From Source** and enter `https://github.com/hardfinhq/skills` |
| Any other assistant that reads skills | Run `npx skills add hardfinhq/skills`                                                                            |

The first time the assistant uses Hardfin, it asks you to sign in and shows the **Connect to Hardfin** screen described in [Add the Hardfin connector](#add-the-hardfin-connector).

{% hint style="info" %}
Plugins do not update on their own. The [Hardfin skills page](https://github.com/hardfinhq/skills) lists the update command for each assistant.
{% endhint %}

## Use the Hardfin CLI

The Hardfin CLI lets an assistant that runs terminal commands read and change your Hardfin records.

1. Install it with [Node.js](https://nodejs.org/) 20.12 or later:

   ```
   npm install -g @hardfin/cli
   ```
2. In the folder your assistant works in, run `hardfin init`. It installs the Hardfin skills and connects the assistant to Hardfin.
3. Run `hardfin login` to sign in. Your browser opens the **Connect to Hardfin** screen described in [Add the Hardfin connector](#add-the-hardfin-connector).

On a computer without a browser, such as a server, use an [API key](https://guide.hardfin.com/advanced-options/api-access.md#api-keys) instead of signing in.

## Access levels

When you connect an assistant, you choose its access level on the **Connect to Hardfin** screen:

* **Read and write**: the assistant can read, create and change records in the organization you choose
* **Read only**: the assistant can only read records in the organization you choose

{% hint style="info" %}
Choose **Read only** for an assistant that only needs to look up or report on your data. Choose **Read and write** only for an assistant you trust to make changes in Hardfin.
{% endhint %}

## Manage connected assistants

Your connected assistants are listed in the **Connected applications** section of your [account page](https://assets.hardfin.com/account), with each one's access level and the date it was connected.

* Select an assistant to see its sessions, and select **Sign out** to end one session
* Select **Disconnect** to remove the assistant's access right away. To use it again, connect it again

## When access ends

An assistant's access to Hardfin ends when:

* You disconnect it
* You are removed from the organization
* The organization's Hardfin access ends

For help connecting an AI assistant, contact your Customer Success representative.
