The Harvestr MCP server lets AI assistants like Claude and Cursor query your Harvestr workspace, your feedback, discoveries, customers, and 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.
Personal access 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

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

In Claude, open Customize, Connectors, Add custom connector.
Enter the server URL: https://mcp.harvestr.io/mcp.
Save. A browser window opens prompting you to authorize the connection.
Sign in to Harvestr if needed, choose Read or Write scope, and confirm.
The connection appears in Settings, Integrations, MCP Server, Connected apps 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, move feedback between discoveries, validate or reject AI suggestions, and archive messages, all orchestrated through plans (see Write tools below).

You can view every connected app, see which scope was granted, and revoke any connection at any time from Settings, Integrations, MCP Server.

Connect with a personal access token

Use a personal access 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.

Step 1: Generate a token

Go to Settings, Integrations, MCP Server.
Click New MCP Token.
Add a label to identify the client.
Click Create, then copy and store the token securely. You won't be able to see it again after this screen.

Each token is scoped to your organization and can be revoked at any time from the same page.

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 full source messages (support tickets, Slack threads, notes). Use when you need the complete context behind a feedback extract.
`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_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_UPDATE`	Move a single piece of feedback between discoveries.
`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 a message between inbox boxes, archive it, restore it, or send it to the bin.

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.

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.

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 or OAuth connections anytime from Settings, Integrations, MCP Server.
For Write connections, audit the connected app's activity in your MCP Server settings regularly.

Troubleshooting

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 a personal access 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 two things: that you granted the Write scope when authorizing, and that your workspace is on the Scale plan or higher. Read tools are available from Core, write tools from Scale.

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

Connect your AI tools to Harvestr with MCP