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

# Heron MCP

> Connect Claude, ChatGPT, or Cursor to Heron with MCP.

Connect your AI assistant to Heron and ask questions about your data in plain language. Heron MCP currently supports finding submissions, checking processing status, and listing attached documents.

Heron uses [Model Context Protocol](https://modelcontextprotocol.io), so any client that supports remote MCP servers can connect.

<Note>
  Heron MCP is in **beta** and supports read-only access. Tools and setup steps may change.
</Note>

## What the assistant can do

The server currently exposes four tools. To write to Heron, use the [API](/api-reference/authentication).

| Tool                    | What it does                                                                                  |
| ----------------------- | --------------------------------------------------------------------------------------------- |
| `list_submissions`      | Lists recent submissions, most recently updated first. Supports search, filtering and paging. |
| `get_submission`        | Fetches one submission by your `end_user_id` or Heron's `heron_id`.                           |
| `get_submission_status` | Returns whether a submission is `processing` or `processed`, and why.                         |
| `list_documents`        | Lists a submission's documents - bank statements, ISO applications, and other files.          |

## Prerequisites

* A **Heron account** with access to the dashboard and to the submissions you want to read.
* A **client that supports remote MCP servers**, such as Claude, ChatGPT, or Cursor.

You do not need an API key.

## 1. Create an endpoint

Create an endpoint in [Settings > MCP Endpoints](https://dashboard.herondata.io/settings#mcp_endpoints), give it a label, then copy its URL:

```
https://app.herondata.io/api/mcp/<heron_id>
```

Endpoints are environment-specific, and each one reads only its own environment's submissions. Create one per client so you can revoke access individually.

<Note>
  The endpoint URL alone does not grant access. Each user signs in with their own Heron account and can access only the submissions available to them.
</Note>

## 2. Connect your client

We recommend **Claude**, which is where Heron MCP is best tested. Each client's own guide has the current screens and menu paths.

### Claude

Follow [Get started with custom connectors using remote MCP](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp).

Go to **Settings > Connectors**, select **Add custom connector**, and paste your endpoint URL. Sign in with your Heron account and approve access. No API key or OAuth client ID is needed.

<Note>
  On Team and Enterprise plans, an organization owner adds the connector once under **Organization settings > Connectors**. Each member then connects individually with their own Heron account.
</Note>

### ChatGPT

Follow [Connect and test your plugin](https://developers.openai.com/plugins/deploy/connect-chatgpt).

Add Heron as a remote MCP server using your endpoint URL. Choose OAuth, sign in with your Heron account, and approve access.

### Cursor

Follow [Model Context Protocol (MCP)](https://cursor.com/docs/mcp).

Add Heron to your `mcp.json` as a remote server pointing at your endpoint URL, then complete the OAuth sign-in Cursor prompts you for.

## 3. Test the connection

Ask your assistant:

> List my five most recently updated submissions. For the first result, show its details, processing status, and attached document list.

This exercises all four tools. If it returns submissions from your account, the connection works.

If the assistant has no Heron tools available, the connector is not authorized - reconnect and complete the sign-in. If it returns nothing, check that your account can see those submissions in the dashboard.

## Revoking access

Delete the endpoint in [Settings > MCP Endpoints](https://dashboard.herondata.io/settings#mcp_endpoints). Its URL stops working immediately and any client using it loses access. This cannot be undone - to reconnect, create a new endpoint. Other endpoints are unaffected.

## A note on data

Submissions contain customer PII - business names, owner details, financials, and document filenames. Your assistant reads that data to answer your questions, under the same access your Heron account already has. Treat the answers as confidential, the same way you would the dashboard.