> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clustr-ai.com/llms.txt
> Use this file to discover all available pages before exploring further.
# MCP Server
> Connect AI assistants to Clustr via the Model Context Protocol
Clustr provides an [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server that lets AI assistants like Claude Desktop, Claude Code, and Cursor interact with your Clustr network directly through natural language.
Ask your AI assistant to search opportunities, manage target accounts, or import contacts without leaving your workflow.
## Setup
### Configure Claude Code
Clustr connects two ways. Both register a server named `clustr` — pick one.
Recommended. No API key, no Node.js. Run this in your terminal:
```bash theme={null}
claude mcp add --transport http clustr https://api.clustr-ai.com/mcp
```
Then run `/mcp` in Claude Code and choose **Authenticate** to sign in with Clustr in your browser. The tools appear once you approve access.
For headless or shared setups. Requires **Node.js 18+** ([download](https://nodejs.org)). Run this in your terminal:
```bash theme={null}
claude mcp add clustr -e CLUSTR_API_KEY=your-api-key -- npx -y @clustr-ai/mcp-server
```
Replace `your-api-key` with a key from your [API settings page](https://app.clustr-ai.com/api). The server is available immediately, no sign-in and no restart needed. `npx` downloads the server automatically on first run.
### Other clients (Claude Desktop, ChatGPT, Cursor)
Add Clustr as a custom connector using the HTTP endpoint, then sign in with Clustr:
```
https://api.clustr-ai.com/mcp
```
In Claude or ChatGPT, open **Settings → Connectors → Add custom connector**, paste the URL, continue, and approve access. The same endpoint accepts a static API key via an `Authorization: Bearer your-api-key` header for clients that support custom headers.
## Available Tools
Once connected, your AI assistant has access to the following tools:
The tool set updates automatically, for every install. OAuth and
custom-connector clients talk to `https://api.clustr-ai.com/mcp` directly. The
API-key install (`npx -y @clustr-ai/mcp-server`) is a stdio bridge to that same
endpoint: it declares no tools of its own and fetches the list from the server
every time a client asks for one, so new tools appear without an npm update.
| Tool | Description |
| --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `start_account_research` | **Renamed in v1.9.0** (was `start_abm_search`, which still executes but is no longer listed). Start account research on a target company and get a shareable magic link immediately |
| `get_account_research_link` | **Renamed in v1.9.0** (was `get_abm_search_link`, same). Retrieve the magic link for an existing account research report without re-running the pipeline |
| `import_connectors` | **Renamed in v1.2.0** (was `import_contacts`, which no longer resolves). Import LinkedIn connectors for referral opportunity discovery. Results delivered via webhook. |
| `search_opportunities` | **Changed in v1.8.0.** Search opportunities by connector, company, or across your entire network. Company filters now match any role a person currently holds, so a search for a fund finds the partner filed under one of its portfolio companies. Add `include_all_positions` to see every job each person holds or held |
| `search_companies` | Search or lookup companies by name, domain, or LinkedIn URL |
| `list_connectors` | List people in your network with opportunity counts |
| `set_connector_owner` | **New in v1.5.0.** Set who owns a connector, and therefore everything it produces, with no reimport. The same thing `owner_email` sets at import time |
| `unassign_connector_owner` | **New in v1.5.0.** Clear a connector's owner. Opportunities already assigned keep theirs |
| `delete_connector` | **New in v1.6.0.** Remove a connector and delete every opportunity that came through them, for people who have left. Irreversible, and flagged destructive so clients confirm first |
| `get_network_stats` | Get an overview of your network: connectors, opportunities, top companies |
| `get_job_status` | Get the status and progress of an import job |
| `list_jobs` | List import jobs with optional status filter |
| `update_opportunity` | **Changed in v1.5.0.** Update an opportunity's status or notes. Owners are no longer set here — an owner owns a connector, so use `set_connector_owner` |
| `list_opportunity_statuses` | List available opportunity statuses for your tenant |
| `list_owners` | List the owner directory, with each owner's opportunity count and whether they are a workspace member |
| `create_owner` | **New in v1.4.0.** Add someone to the owner directory. Sends no email and grants no access |
| `import_owners` | **New in v1.4.0.** Add up to 2000 owners at once, e.g. a rep list from your CRM. Idempotent, so re-running an import adds nothing |
| `update_owner` | **New in v1.4.0.** Update an owner's email or name |
| `delete_owner` | **New in v1.4.0.** Delete an owner. Every opportunity they hold becomes unowned, and the count is returned |
| `create_target_accounts` | Add target accounts for opportunity prioritization |
| `list_target_accounts` | List or search your target accounts |
| `delete_target_account` | Remove a target account by ID, name, or LinkedIn URL |
| `list_icps` | **New in v1.4.0.** List your Ideal Customer Profiles |
| `create_icp` | **New in v1.4.0.** Create an ICP |
| `update_icp` | **New in v1.4.0.** Update an ICP; only provided fields change |
| `delete_icp` | **New in v1.4.0.** Delete an ICP |
| `list_competitors` | List monitored competitors with slot usage |
| `register_competitor` | Register a competitor to monitor (subject to your slot limit). **Starts its first scan.** |
| `update_competitor` | Update a competitor's details or status (`active` / `paused`) |
| `pause_competitor` | Pause monitoring of a competitor |
| `delete_competitor` | Delete a competitor and stop monitoring it |
| `list_competitor_interactions` | **New in v1.4.0.** The Signals feed — every competitor-rep interaction with a person at one of your accounts, with the ICP, CRM and critical verdicts. Filter by competitor, window, engagement type, rep role and seniority, and by CRM scope — including `crm=customer` for the accounts you already own. |
| `list_competitor_interaction_prospects` | **New in v1.4.0.** The same feed folded to one row per engaged person |
| `export_competitor_interactions` | **New in v1.4.0.** Your entire interaction history in one call |
| `list_competitor_accounts` | **New in v1.4.0.** Every account competitors are touching, ranked, with your CRM ownership and open-deal detail |
| `list_competitor_account_interactions` | **New in v1.4.0.** One account's full competitor history |
| `list_competitor_summaries` | **New in v1.4.0.** Header tallies for every tracked competitor |
| `get_competitor_detail` | **New in v1.4.0.** One competitor's battlecard: ranked accounts, reps, activity over time |
| `list_competitor_runs` | **New in v1.4.0.** In-flight and recent scans, with status |
| `snooze_competitor_interaction` | **New in v1.4.0.** Hide one interaction until a deadline you set |
| `dismiss_competitor_target` | **New in v1.4.0.** Permanently silence one person |
| `undismiss_competitor_target` | **New in v1.4.0.** Reverse a dismissal |
| `list_dismissed_competitor_targets` | **New in v1.4.0.** The people you have dismissed |
| `log_competitor_interaction_to_crm` | **New in v1.4.0.** Write a critical signal onto the matched CRM company as a note |
| `get_competitor_monitoring_schedule` | **New in v1.4.0.** When the automatic scan runs |
| `update_competitor_monitoring_schedule` | **New in v1.4.0.** Set when it runs, and whether it runs at all |
| `get_competitor_delivery_config` | **New in v1.4.0.** Where finished reports are delivered |
| `update_competitor_delivery_config` | **New in v1.4.0.** Set delivery channels and the engagement policy |
| `list_competitor_reports` | List competitor-monitoring reports, newest first |
| `get_competitor_report` | Get one competitor report by ID, including full attack/defend data |
| `whats_new` | Show the MCP changelog and available tools for the installed version |
**Removed in v1.4.0: `start_competitor_monitoring`.** A competitor scan now fires on exactly two events — a competitor being added, and the weekly schedule — everywhere, not just in the web app. `register_competitor` starts the new competitor's first scan itself and tells you whether it started, so nothing replaces the removed tool. Use `list_competitor_runs` to see what is running.
## Owners are a directory, not a seat
An owner is the person accountable for a **connector**, and therefore for every opportunity that connector produces. In Clustr that is a directory entry scoped to your workspace, not a login, so it does not have to be one of your teammates. An investor, an advisor, a former colleague, or a friend can own an opportunity.
That has three consequences worth knowing when you ask an assistant to assign work:
* **No email is sent.** Creating an owner never notifies that person. If you want them to know, tell them yourself.
* **No access is granted.** An owner cannot sign in, see your network, or read the opportunity. The entry is a label on your data.
* **No seat is used.** Adding owners does not change your billing, so there is no reason to be sparing with them.
Owners who *are* workspace members come back with `is_member: true`, so an assistant can tell the two apart. Deleting an owner never deletes opportunities: every opportunity that person held is simply left with no owner, and `delete_owner` reports how many so you can reassign them.
## Example Prompts
Here are some things you can ask your AI assistant once Clustr is connected:
* *"Run account research on Salesforce and give me the report link"*
* *"Find referral opportunities at Stripe"*
* *"What opportunities do we have through john-doe on LinkedIn?"*
* *"Show me my top opportunities by confidence score"*
* *"Give me an overview of my network"*
* *"Who are my connectors?"*
* *"Check the status of my last import"*
* *"Mark opportunity X as Contacted"*
* *"Assign that Stripe opportunity to [sam@northstar.vc](mailto:sam@northstar.vc), he is our investor, create the owner if needed"*
* *"Who owns the most opportunities right now?"*
* *"Add Stripe as a target account"*
* *"List all our target accounts"*
* *"Add Globex as a competitor to monitor"*
* *"Which of my open-deal accounts did competitors touch this week?"*
* *"Show me every critical signal from Globex's founders and AEs in the last 30 days"*
* *"Who at Northwind Trading have our competitors been talking to?"*
* *"Log that comment to the CRM, then snooze the rest of that thread for a week"*
* *"Show me the latest competitor report and which accounts are at risk"*
## Authentication
Clustr's MCP server supports two auth methods:
* **OAuth (sign-in)** — authorize in your browser; Clustr issues and refreshes tokens automatically. No key to manage. Recommended for Claude Code, Claude Desktop, and ChatGPT.
* **API key** — the same key as the [REST API](/authentication), set via the `CLUSTR_API_KEY` environment variable. Best for headless or shared setups.
## Troubleshooting
| Issue | Solution |
| ------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| `CLUSTR_API_KEY environment variable is required` | Set the `CLUSTR_API_KEY` env var in your client config |
| Authentication errors | Verify your API key is correct and active in [API settings](https://app.clustr-ai.com/api) |
| Tools not appearing | Restart your AI client after updating config |
| Rate limited | Wait a moment and retry. The error message includes retry timing. |
| Large responses truncated | Use `page` and `page_size` parameters to paginate results |