# Connect your AI tools to Harvestr with MCP

The Harvestr MCP server lets AI assistants like Claude and Cursor query your Harvestr workspace (feedback, discoveries, customers, components) directly in natural language.

There are two ways to connect a client:

- **OAuth (recommended for most users)**: a one-click browser flow inside your AI client. No tokens to copy or paste.

- **MCP token**: for headless setups, agentic workflows, or clients that don't support OAuth yet.

# Plans

| **Scope** | **Minimum plan** |
| --------- | ---------------- |
| **Read**  | Core             |
| **Write** | Scale            |

# Server URL

```
https://mcp.harvestr.io/mcp
```

You can also copy it from the **Server URL** card on **[Settings > Integrations > MCP server](https://app.harvestr.io/settings/integrations/mcp-server)**.

# Connect via OAuth

OAuth is the default flow for most modern MCP clients. The process is the same regardless of the client: add the Harvestr MCP server in your client's settings, the client opens a browser, you authorize from inside Harvestr, and the client is connected.

## Claude

1. In Claude, open **Customize > Connectors > Add custom connector**.

2. Enter a name (for example Harvestr) and the server URL: `https://mcp.harvestr.io/mcp`. Leave the client ID and secret empty: Claude registers itself automatically.

3. Save. A browser window opens prompting you to authorize the connection.

4. Sign in to Harvestr if needed, choose **Read** or **Write** scope, and confirm.

5. The connection appears in the **Connected apps** card of **Settings > Integrations > MCP server** inside Harvestr. Harvestr tools become available in the client.

## Cursor, Windsurf, and other OAuth-capable clients

The flow is the same. Open your client's MCP settings, add a new server with URL `https://mcp.harvestr.io/mcp`, then complete the OAuth prompt in your browser.

## Scopes

When you authorize, you pick the level of access the client gets:

- **Read**: browse and analyze your workspace data (feedback, discoveries, components, customers, roadmap projects, activities).

- **Write**: create, update, and delete discoveries, components, and roadmap projects, organize feedback, validate or reject AI suggestions, add labels and comments, all orchestrated through plans (see [Write tools](#h_writetools) below).

Every connected app is listed in the **Connected apps** card of **[Settings > Integrations > MCP server](https://app.harvestr.io/settings/integrations/mcp-server)**. To disconnect one, open its **⋯** menu and click **Revoke access**: it is disconnected right away. Only Editors and Owners see and manage the connected apps and tokens.

# Connect with an MCP token

Use an MCP token when:

- Your AI client doesn't support OAuth yet.

- You're running an agent or script in a headless environment with no browser to complete the OAuth flow (CI, server-side automations, n8n flows, custom orchestrators).

A token grants the client the same access as the user who created it. There is no scope to pick when you create one: read tools are available from Core, write tools from Scale.

## Step 1: Generate a token

1. Go to **[Settings > Integrations > MCP server](https://app.harvestr.io/settings/integrations/mcp-server)**.

2. In the **MCP tokens** card, click **Create token**.

3. Enter a **Name** that identifies the client, for example Dust, n8n or Claude Desktop. Never include a secret.

4. Click **Create token**.

5. In **Copy your MCP token now**, click **Copy**, store the token securely, then click **Done**. You won't be able to see it again.

Each token is scoped to your organization. To revoke one, open its **⋯** menu in the **MCP tokens** card and click **Delete token**.

## Step 2: Connect your AI client

In your MCP client, add a new server with:

- **URL**: `https://mcp.harvestr.io/mcp`

- **Authentication**: Bearer token, paste your MCP token

Save and reconnect.

# What you can do

The Harvestr MCP server gives connected AI tools access to the following data and actions.

## Read tools (available with both scopes)

| **Tool**                                  | **What it does**                                                                                                                                                              |
| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `list_harvestr_discoveries`               | Search and filter discoveries by title, component, state, or date. Primary tool for browsing your backlog.                                                                    |
| `list_harvestr_discoverystates`           | List all workflow states (Backlog, In Progress, Done, and so on) for filtering discoveries.                                                                                   |
| `list_harvestr_discovery_fields`          | List custom and default discovery fields available in your workspace.                                                                                                         |
| `list_harvestr_discovery_tags`            | List the tags available on discoveries.                                                                                                                                       |
| `list_harvestr_discovery_templates`       | List the discovery templates configured in your workspace.                                                                                                                    |
| `list_harvestr_feedback`                  | Semantic search across feedback by topic, customer, or discovery. Returns both validated and AI-suggested feedback.                                                           |
| `list_harvestr_messages`                  | Access the full source feedback (support tickets, Slack threads, notes), with its labels and team comments. Use when you need the complete context behind a feedback extract. |
| `list_harvestr_message_labels`            | List the feedback labels available in your workspace.                                                                                                                         |
| `list_harvestr_components`                | Browse your product component hierarchy. Useful for scoping queries to a specific product area.                                                                               |
| `list_harvestr_custom_inboxes`            | List the Custom Inboxes set up in your workspace.                                                                                                                             |
| `list_harvestr_customers`                 | Look up users, companies, and teammates by name. Useful for finding customer IDs before filtering feedback by requester.                                                      |
| `search_harvestr_customers_by_attributes` | Find customers by CRM attributes, such as plan tier, industry or geography. Supports semantic search on text attributes and numeric filters.                                  |
| `list_harvestr_customer_attributes`       | List the customer attributes available in your workspace.                                                                                                                     |
| `list_harvestr_roadmap_projects`          | Browse the projects on your product roadmap.                                                                                                                                  |
| `list_harvestr_roadmap_fields`            | List the custom fields configured on roadmap projects, with their options.                                                                                                    |
| `analyze_harvestr_feedback`               | Analyze feedback volume over time. Returns a time series with period-over-period changes, globally or broken down by discovery.                                               |
| `aggregate_harvestr_data`                 | Get counts broken down by state, component, or type, for example how many discoveries sit in each state.                                                                      |
| `read_harvestr_activities`                | Read the activity log on a discovery or component for change history.                                                                                                         |
| `read_harvestr_deleted_archive`           | Browse archived and deleted items for recovery or audit.                                                                                                                      |
| `read_harvestr_plan`                      | Read the contents of a plan that's already been created.                                                                                                                      |

## Write tools (Write scope only)

Write operations go through Harvestr plans. Three tools handle plan orchestration:

| **Tool**                 | **What it does**                                                                   |
| ------------------------ | ---------------------------------------------------------------------------------- |
| `create_harvestr_plan`   | Start a new plan that will package one or more actions to apply to your workspace. |
| `add_harvestr_plan_step` | Append one or more actions to an existing plan.                                    |
| `execute_harvestr_plan`  | Run the actions in a saved plan against your workspace.                            |

The actions a plan can perform:

| **Action**               | **What it does**                                                                                                                |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| `DISCOVERY_CREATE`       | Create a new discovery.                                                                                                         |
| `DISCOVERY_UPDATE`       | Update a discovery's title, description, state, tags, assignees, field values, or parent. Also merges a discovery into another. |
| `DISCOVERY_DELETE`       | Delete a discovery.                                                                                                             |
| `CHUNK_CREATE`           | Link a whole piece of feedback to a discovery.                                                                                  |
| `CHUNK_UPDATE`           | Move feedback between discoveries, or change how much it counts.                                                                |
| `CHUNK_DELETE`           | Remove feedback from a discovery. The original feedback stays in your inbox.                                                    |
| `SUGGESTION_VALIDATE`    | Accept an AI-suggested feedback categorization into a discovery.                                                                |
| `SUGGESTION_REJECT`      | Dismiss an AI suggestion so it isn't proposed again.                                                                            |
| `COMPONENT_CREATE`       | Create a new component.                                                                                                         |
| `COMPONENT_UPDATE`       | Update an existing component.                                                                                                   |
| `COMPONENT_DELETE`       | Delete a component.                                                                                                             |
| `ROADMAP_PROJECT_CREATE` | Create a roadmap project.                                                                                                       |
| `ROADMAP_PROJECT_UPDATE` | Edit a roadmap project's title, descriptions, Timeline dates, owners, linked discoveries, or custom field values.               |
| `MESSAGE_UPDATE`         | Move feedback between inbox folders, archive it, restore it, send it to the bin, or add and remove its labels.                  |
| `MESSAGE_COMMENT_CREATE` | Post an internal team comment on a piece of feedback, or reply in a thread.                                                     |

**Plans are reviewable before they run.** When a plan touches several resources or includes a deletion or a merge, your client is asked to confirm with you before executing. Nothing is applied to your workspace until the plan is executed.

## Run plans without confirmation

Using an agent that works on its own? When you authorize an app with the **Write** scope, tick **Run plans without asking me**. The app can then apply its plans, including deletions and merges, without asking you first, so only do this for an agent you trust.

The app then shows **Runs without confirmation** in the **Connected apps** card. To stop it, click **Revoke access** in its **⋯** menu. This option is only available with OAuth, not with an MCP token.

## A few things worth knowing when building workflows

- Two tools do **semantic search**, finding conceptually related records even when the wording differs: `list_harvestr_feedback` over feedback content, and `search_harvestr_customers_by_attributes` over text attributes when you pass a free-text query. The other list tools use keyword or title matching.

- Tools chain naturally: use `list_harvestr_discoveries` to get a discovery ID, then `list_harvestr_feedback` with `discovery_ids` to get its feedback, then `list_harvestr_customers` to profile who's behind it.

- All tools support **pagination** via a cursor parameter for workflows that need to process large result sets.

- The MCP server cannot create feedback or customers. To push new feedback into Harvestr programmatically, use the [Public API](https://developers.harvestr.io/).

# Security

- Treat MCP tokens like passwords: never commit them to version control.

- Each token and each OAuth connection is scoped to your organization only.

- Use one token per client so you can revoke individual access without disrupting other tools.

- Revoke tokens (**Delete token**) or OAuth connections (**Revoke access**) anytime from **[Settings > Integrations > MCP server](https://app.harvestr.io/settings/integrations/mcp-server)**.

- For Write connections, review the **Connected apps** card regularly and revoke the apps you no longer use.

# Troubleshooting

## The connection points to Harvest, not Harvestr

Harvest (time tracking) is a different product. If your AI tool suggests a URL such as `api.harvestapp.com`, replace it with `https://mcp.harvestr.io/mcp`.

## OAuth browser window doesn't open

Make sure your AI client is up to date. Older versions of some clients don't yet implement the MCP OAuth flow; try an MCP token instead.

## "No tools available" after connecting

For token-based connections, check that your token is correctly formatted with the `Bearer` prefix in the Authorization header. For OAuth, try disconnecting from your client and re-authorizing.

## Write tools don't appear

Check that your workspace is on the **Scale** plan or higher: read tools are available from Core, write tools from Scale. With OAuth, also check that you granted the **Write** scope when authorizing.

## Authentication errors

Your token or OAuth connection may have been revoked. Generate a new token, or re-authorize from your client. Check your active connections in the **Connected apps** and **MCP tokens** cards of **[Settings > Integrations > MCP server](https://app.harvestr.io/settings/integrations/mcp-server)**.

## Slow responses on large queries

Queries that span your full workspace (no date range or filter) may take longer. Scope your question to a time period or specific component for faster results.