# MCP Integration Guide

**Last Updated:** 2026-03-29

This document describes the MCP (Model Context Protocol) servers configured for this project, when to use each, how they relate to direct API integrations, and governance.

## Overview

MCPs extend Cursor's agent with tools for performance audits, Excel inspection, URL fetching, web search (open-websearch), filesystem operations, GitHub/HubSpot/Notion queries, and more. **Rules must instruct the agent when to use tools**—see `.cursor/rules/mcp-usage.mdc`.

### Configured MCPs

| MCP | Purpose | Auth |
|-----|---------|------|
| Excel | Read/inspect generated .xlsx, debug template output | None |
| Fetch | Fetch URLs as HTML, JSON, plain text, or Markdown | None |
| Firecrawl | Scrape, crawl, search, extract — AI-ready markdown; uses credits | API key (Free 500 one-time; Hobby 3k, Standard 100k, Growth 500k/month) |
| Figma | Design-to-code, read design context from Figma links | OAuth |
| Filesystem | Read/write files, list dirs, search (scoped to workspace) | None |
| GitHub | PRs, issues, repo operations | PAT required |
| HubSpot | Ad hoc read-only CRM in chat; bulk work → scripts | OAuth — *May fail (DCR); reinstall + fallbacks: [HUBSPOT_MCP_OAUTH_SETUP.md](HUBSPOT_MCP_OAUTH_SETUP.md)* |
| Lighthouse | PageSpeed audits, Core Web Vitals | None |
| MarkItDown | Convert PDF, Word, Excel, images to Markdown | None |
| Notion | Sync docs, query workspace | OAuth |
| Sequential Thinking | Structured reasoning for complex planning | None |
| Serper | Google search, real SERPs — organic results, knowledge graph, people also ask | API key (free tier: 2,500 credits) |
| Web Search | Web search, SERP research — free, no API key (DuckDuckGo, Bing, Brave) | None |

## Security

- **Never commit `mcp.json`** — it may contain tokens. It is in `.gitignore`.
- **Never hardcode real credentials** in `mcp.json.example` — use placeholders only.
- **Rotate credentials immediately** if ever exposed (shared in chat, committed by mistake).
- **Optional:** Use `python3 v2/scripts/dev-helpers/setup-mcp-config.py` (with `--env-file .env`) to generate `mcp.json` from env vars.

## Setup

See [.cursor/README-MCP.md](../../.cursor/README-MCP.md) for quick setup. Copy `mcp.json.example` to `mcp.json`, add tokens, restart Cursor.

**HubSpot OAuth:** See [HUBSPOT_MCP_OAUTH_SETUP.md](HUBSPOT_MCP_OAUTH_SETUP.md) for MCP Auth App creation, **reinstall checklist**, and OAuth flow. Connection may still fail in Cursor due to **DCR** (see that doc); use **PHP scripts + Private App token** or **MCP Inspector** as fallback.

## HubSpot: MCP vs PHP/scripts vs Operations Hub

Use the right layer for **speed**, **reproducibility**, and **quality**—they complement each other.

| Dimension | **HubSpot MCP** (Cursor chat, OAuth) | **PHP/scripts + `HUBSPOT_API_TOKEN`** | **Operations Hub / workflows** (in HubSpot) |
|-----------|--------------------------------------|----------------------------------------|-----------------------------------------------|
| **Best for** | Spot-check a contact or deal, exploratory questions, quick debugging with a human in the loop | Large exports, CRM Search pagination, **10k result cap** handling, audits ([`v2/scripts/hubspot/audit-leadsource-utm-discrepancies.php`](../systems/hubspot/HUBSPOT_LEADSOURCE_UTM_AUDIT.md)), affiliate sync ([`v2/helpers/hubspot-affiliate-api.php`](../../v2/helpers/hubspot-affiliate-api.php)) | Always-on routing, **enrich when empty**, approvals, data-quality automation |
| **Chat / agent cost** | Each query uses MCP tool turns; many calls add up toward the **40/80 tool** limit (HubSpot ≈ **10 tools**) | One CLI run; predictable duration; no per-message tool budget | N/A in Cursor |
| **Output quality** | Natural-language answers; risk of incomplete pagination if the agent stops early | **Reproducible** artifacts (CSV/JSON), versioned logic in repo | Consistent for all CRM users |
| **Auth** | Per-user OAuth + MCP install | Env / [`hubspot-api-key.php`](../../v2/config/hubspot-api-key.php.example) via [`hubspot-config.php`](../../v2/config/hubspot-config.php) | HubSpot user permissions |

**Anti-patterns:** Do not use MCP for **bulk writes** (remote MCP is **read-only**). Do not replace **lead capture** or **production sync** with MCP. For “all contacts in 90 days” style work, prefer **`audit-leadsource-utm-discrepancies.php`** or other scripts under `v2/scripts/hubspot/` plus [`v2/helpers/hubspot-crm-search.php`](../../v2/helpers/hubspot-crm-search.php).

**Cursor + DCR:** If HubSpot MCP OAuth starts working in Cursor (static client support or product change), retry the flow in [HUBSPOT_MCP_OAUTH_SETUP.md](HUBSPOT_MCP_OAUTH_SETUP.md) and watch [this Cursor forum thread](https://forum.cursor.com/t/custom-mcp-client-no-option-to-disable-dynamic-client-registration-dcr-and-use-static-mcp-client-id-in-cursor-ide/110638) for updates.

## MCP vs Direct API Matrix

**Production code paths use direct API/scripts. MCP is for AI-assisted queries, debugging, and exploratory tasks.**

| Integration | Direct API / Scripts | MCP | Use API When | Use MCP When |
|-------------|----------------------|-----|--------------|--------------|
| HubSpot | `v2/helpers/hubspot-affiliate-api.php`, `v2/helpers/hubspot-crm-search.php`, cron sync, `v2/scripts/hubspot/audit-leadsource-utm-discrepancies.php` | HubSpot MCP | Affiliate sync, lead capture, production writes, bulk audits, CI | Ad hoc contact/deal lookup in chat (if OAuth works); else use scripts |
| GitHub | git CLI | GitHub MCP | Commits, branches, local workflow | Create PRs, search issues, repo operations in chat |
| Figma | `fetch-figma-file.py`, REST API | Figma MCP | Scripts, CI, token-based automation | Design-to-code in chat, paste link |
| Notion | (none in codebase) | Notion MCP | — | Sync docs, query workspace |
| Excel | `template-generator.php`, `template-cli.php` | Excel MCP | Generate templates (production code path) | Inspect output, verify formulas, debug corruption, check structure, verify data validation, compare templates |
| Fetch | (none in codebase) | Fetch MCP | — | Single-URL fetch, schema validation, competitor checks |
| Firecrawl | `v2/helpers/firecrawl-remediate.php` (Scrape-first, 1 credit/URL) | Firecrawl MCP | Competitor analysis when cURL returns sparse content | Use **firecrawl_scrape** (markdown); avoid firecrawl_extract (22–32 credits) |
| Serper | (none in codebase) | Serper MCP | — | Google SERP research when real rankings needed |
| Web Search | (none in codebase) | Web Search MCP | — | General web search (DuckDuckGo, Bing, Brave) |

**No conflict:** HubSpot MCP is read-only; production writes use the affiliate API. GitHub MCP adds PR/issue operations; git handles commits.

## Initiative → MCP Mapping

| Initiative / Task | MCP(s) |
|-------------------|--------|
| Comparison pages bulk edit | Filesystem, Multi-Edit |
| Schema validation | Fetch |
| Performance audit | Lighthouse |
| SERP / competitor research | Serper (Google) or Web Search (free) |
| Design implementation | Figma (user-level) |
| Blog content research | Web Search, Fetch (search → fetch URLs); Firecrawl for crawl/extract |
| Debug affiliate sync (one record) | HubSpot MCP if connected; else MCP Inspector or `hubspot-affiliate-api.php` / scripts |
| Bulk HubSpot CRM analysis | **Scripts only** (not MCP)—see [HUBSPOT_LEADSOURCE_UTM_AUDIT.md](../systems/hubspot/HUBSPOT_LEADSOURCE_UTM_AUDIT.md) |
| Lead source vs UTM reconciliation | Direct API: `php v2/scripts/hubspot/audit-leadsource-utm-discrepancies.php` — see `docs/systems/hubspot/HUBSPOT_LEADSOURCE_UTM_AUDIT.md` |
| Excel template debug/inspection | Excel |
| PR creation | GitHub |

## When to Use Which

| Task Type | Recommended Tool |
|-----------|------------------|
| Validate schema | Fetch MCP (fetch URL, inspect JSON-LD) or Google Rich Results Test |
| Scrape/fetch content | Fetch MCP (single URL, free) or Web Search → Fetch (multi-page); Firecrawl **firecrawl_scrape** (1 credit) when Fetch insufficient; avoid firecrawl_extract |
| Performance audit | Lighthouse MCP or `npx lighthouse [url]` |
| Debug affiliate sync | HubSpot MCP **or** PHP scripts / API (prefer scripts for bulk) |
| Inspect Excel template output, verify formulas, debug corruption | Excel MCP |
| Bulk edit comparison pages | Filesystem MCP + Multi-Edit |
| Create PR after changes | GitHub MCP |
| Complex planning | Sequential Thinking MCP |
| Convert doc to Markdown | MarkItDown MCP |
| Sync runbook to Notion | Notion MCP |
| SERP research, competitor content | Serper MCP (Google) or Web Search MCP (free) |
| Implement design from Figma link | Figma MCP |

## Tool Limit (40/80)

Cursor has a **40-tool performance threshold** and **80-tool hard limit**. Exceeding 40 tools may cause slowdowns; exceeding 80 may randomly disable tools.

### Tool Count Audit

| MCP | Est. Tools | Notes |
|-----|------------|-------|
| GitHub | ~25 | create_pr, search_issues, get_file, etc. |
| Excel | ~15 | read, write, formulas, charts |
| Figma | ~5 | get_screenshot, get_design_context, metadata |
| Lighthouse | ~2 | run_audit, get_performance_score |
| Fetch | ~4 | fetch_html, fetch_json, fetch_txt, fetch_markdown |
| Firecrawl | ~5 | scrape, crawl, search, extract |
| Serper | ~2 | google_search, scrape |
| Web Search | ~5 | search, multi-engine |
| Filesystem | ~6 | read, write, list, search, etc. |
| HubSpot | ~10 | contacts, deals, companies, etc. |
| Notion | ~4 | search, read, etc. |
| MarkItDown | ~1 | convert_to_markdown |
| Sequential Thinking | ~3 | think, revise, etc. |
| **Total** | **~82** | At limit; disable low-priority MCPs when not needed |

### Always Enabled (Core Workflows)

Keep these on for day-to-day work:

| MCP | Why |
|-----|-----|
| **Filesystem** | Bulk edits, search, multi-file operations — used constantly |
| **Fetch** | Schema validation, URL content, competitor checks — lightweight (4 tools) |
| **Lighthouse** | Performance audits before deploy — quick to run |

### Enable Per Project / Initiative

Turn on when starting a specific effort:

| MCP | Enable When |
|-----|-------------|
| **GitHub** | Creating PRs, triaging issues, repo operations |
| **Excel** | Debugging template generator, inspecting .xlsx output, verifying formulas, checking structure |
| **Web Search** | General web search (free) |
| **Serper** | Google SERP research when real rankings needed — uses credits (2,500 free) |
| **Firecrawl** | Crawl/extract when Fetch insufficient; uses credits — enable on demand |
| **Figma** | Design-to-code, implementing from Figma links |

### Enable On Demand (Per Task)

Turn on only for the task, then disable:

| MCP | Enable When |
|-----|-------------|
| **MarkItDown** | Converting PDF/Word/Excel to Markdown |
| **Notion** | Syncing docs, querying workspace |
| **Sequential Thinking** | Complex multi-phase planning |

### Disable (Known Issues / Low Value)

| MCP | Reason |
|-----|--------|
| **HubSpot** | If OAuth repeatedly fails (**DCR**), disable to avoid connection noise; keep config in `mcp.json` for retries when Cursor/HubSpot improve auth—see [HUBSPOT_MCP_OAUTH_SETUP.md](HUBSPOT_MCP_OAUTH_SETUP.md) |

### Recommended Disable List (if performance degrades)

When tools become unresponsive or slow, disable in Settings → MCP:

- **HubSpot** – if tools show persistent auth errors after [reinstall + OAuth](HUBSPOT_MCP_OAUTH_SETUP.md), disable until Cursor supports static OAuth or the forum workaround applies; use scripts for bulk HubSpot work
- **MarkItDown** – use only when converting docs
- **Sequential Thinking** – use only for complex planning tasks
- **Notion** – use only when syncing/querying Notion

## Verification

1. **Validate config:** Run `python3 v2/scripts/dev-helpers/validate-mcp-config.py` before first use
2. Restart Cursor after config changes
3. Settings → Tools & MCP → confirm servers appear
4. In Chat: "Run a Lighthouse audit on https://www.ordio.com" or "What MCP tools do you have?"

### Smoke Test (per-MCP)

Use these prompts in Cursor Chat to verify each MCP:

| MCP | Test Prompt |
|-----|-------------|
| Fetch | "Use Fetch MCP to get https://www.ordio.com" |
| Firecrawl | "Use Firecrawl MCP to scrape https://www.ordio.com" (requires API key) |
| Lighthouse | "Run a Lighthouse audit on https://www.ordio.com" |
| Filesystem | "List files in v2/pages" |
| Excel | "Use Excel MCP to inspect v2/systems/excel-template-generator/output/generated-templates/dienstplan-excel-vorlage.xlsx" or "Read formulas from template.xlsx" |
| Web Search | "Search web for Ordio" |
| Serper | "Use Serper MCP to search Google for Ordio Schichtplanung" (requires API key) |

## Next Steps (Post-Implementation)

1. **Restart Cursor** – Pick up mcp-usage.mdc and all MCP config
2. **Test MCPs** – Run "Lighthouse audit on https://www.ordio.com/tools/minijob-rechner" and one other (e.g. Excel, Fetch)
3. **OAuth** – Complete Notion and HubSpot OAuth when first using their tools
4. **Rule validation** – Run `make rules` or `bash scripts/maintain-rules.sh` before committing rule changes
5. **Share with team** – Point developers to `.cursor/README-MCP.md` and `docs/development/MCP_INTEGRATION.md`

## References

- **Governance rule:** `.cursor/rules/mcp-usage.mdc`
- **Quick setup:** `.cursor/README-MCP.md`
- **Figma MCP:** [FIGMA_API_INTEGRATION.md](FIGMA_API_INTEGRATION.md)