artefact-mcp 0.5.0

The AI-native operational layer for HubSpot. Free tier: 9 tools (5 GTM OS builders + 4 HubSpot audit tools — lifecycle stages, pipeline hygiene, AI readiness, property governance). Pro tier: live HubSpot revenue intelligence (RFM, ICP triangulation, pipeline health) gated by Lemon Squeezy.

Artefact Formula MCP

The AI-native operational layer for HubSpot.

v0.5.0 ships 4 new Free tier audit tools: audit_lifecycle_stages, audit_pipeline_hygiene, score_ai_readiness, audit_property_governance. They diagnose what to fix in your CRM before you deploy AI on top of it. Plus Lemon Squeezy license gating now active on the 4 Pro tier tools. See Roadmap.

Before you install

The extension runs via uvx, which comes from the uv package manager. Neither macOS nor Windows ships with it by default. Install it once before installing the DXT, otherwise the extension will fail to start with spawn uvx ENOENT.

macOS / Linux (Terminal):

curl -LsSf https://astral.sh/uv/install.sh | sh
source $HOME/.local/bin/env

Verify with which uvx.

Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Then sign out of Windows and sign back in to refresh PATH. Verify in a new PowerShell with where.exe uvx.

After installing uv, fully quit Claude Desktop (Cmd+Q on macOS, exit from the system tray on Windows) before reopening so it picks up the new PATH.

First prompt to try

After installing, open Claude and type:

Audit my HubSpot for AI readiness

The agent will route to score_ai_readiness and surface a 0-100 maturity score across 6 weighted dimensions, plus the top 3 blockers and 5 ranked Sprint 0 actions. Works on built-in sample data with no license. Set HUBSPOT_API_KEY to run on your live data.

View Full Documentation

A Model Context Protocol (MCP) server that delivers the Artefact Formula methodology directly into Claude (or any MCP client). Nine Free tier tools in v0.5.0: 5 GTM Operating System builders (module library, archetype router, mode diagnostic, CLAUDE.md scaffolder, gate validator) plus 4 HubSpot audit tools (lifecycle stages, pipeline hygiene, AI readiness scoring, property governance). Four Pro tier tools cover live HubSpot revenue intelligence (RFM, ICP triangulation, pipeline health), gated by Lemon Squeezy. Built on real B2B consulting engagements at Artefact Ventures.

What changed in v0.5.0 (May 8 2026): the Free tier shipped from 5 to 9 tools. The 4 new audit tools work on either built-in sample data (no key required) or your live HubSpot when HUBSPOT_API_KEY is set. Driver: when an AI agent reads a CRM full of orphan contacts, missing fields, and deprecated properties, it produces confident nonsense. These tools surface what to fix before you wire up the AI layer. See Roadmap.

Methodology concepts (1 minute glossary)

Read this first if you are new to the Artefact Formula. These terms appear throughout the tools.

• CLAUDE.md. A 5-section master prompt file that codes a pilot's business logic into 80 to 150 lines. Survives an LLM or infra swap. The "operating system" file.
• Module. A discrete unit of GTM work, organized by pillar (FOND, ARC, SKL, WFL, SNT, GOV, INT, EXT) plus mode-specific (POC, DIY). 34 modules total.
• Pillar. A capability area: FOND (foundation), ARC (architecture), SKL (skills library), WFL (workflows), SNT (sentinelles, governance signals), GOV (governance), INT (interfaces), EXT (export and handoff).
• Mode. Deployment style: Self-Serve (solo or small team, free or low-touch), POC (4-week proof of concept), DIY (sponsor wants outputs, pilot is reviewer), Co-Build (pilot has 5 to 8 h/week and learns alongside).
• Archetype. Technical stack family: A (Open / sovereign, Claude + Notion + Supabase), B (Google-native), C (Microsoft-native), D (Hybrid / on-prem).
• Sentinelle. A scheduled governance check that watches for silent failures (skill drift, stale metacontext, broken auth tokens). Concept introduced; no MCP tool ships in v0.4.0.

Why Artefact Formula MCP?

Most MCP servers expose data. This one installs a methodology. Five Free tier tools turn the Artefact Formula into callable operations: any MCP-compatible AI agent can browse the 34-module methodology, route a pilot to the right archetype, recommend a deployment mode, scaffold a CLAUDE.md master, and validate a module's QA gate. Four Pro tier tools add live HubSpot revenue intelligence on top.

Capability	Generic MCP	Artefact Formula MCP
Methodology built-in	No	5 piliers, 4 archétypes, 34 modules
Mode diagnostic (POC / DIY / Co-Build / Self-Serve)	No	auto_diagnose from a free-text pilot context
Archetype router (A / B / C / D)	No	archetype_decision from 5 yes/no questions
CLAUDE.md scaffold	No	generate_claude_md with 5-section template
Module library browser	No	module_prompt_free for the 34-module catalog
QA gate validator	No	gate_check for module-by-module advancement
Revenue intelligence (HubSpot)	Partial	RFM + ICP triangulation + pipeline health (Pro tier)
Free architecture coach	No	Yes, 100% local, no license

Compatible clients

The Model Context Protocol is now the standard for AI agent integration. Artefact Formula MCP works in any MCP-compatible client, including:

Client	LLM(s)	MCP support
Claude Desktop, Claude Code, claude.ai	Claude (Anthropic)	Native since Nov 2024
ChatGPT Desktop	GPT (OpenAI)	Native via Apps SDK + Connectors + Developer Mode (since Mar 2025, full read/write Oct 2025)
Google Gemini API, Vertex AI Agent Builder, Gemini CLI	Gemini (Google)	Native since Mar 2026
Microsoft Copilot Studio, M365 Copilot, GitHub Copilot, Security Copilot	Multi-LLM (Microsoft)	GA across Copilot suite
Cursor, Windsurf, Zed, JetBrains AI Assistant	Multi-LLM (your choice)	Native IDE integration
Vercel AI SDK, OpenAI Agents SDK	Multi-LLM	SDK-level support
Ollama, LM Studio (local LLMs)	Llama, Mistral, etc.	Community

Artefact Formula MCP installs once via PyPI and runs wherever your team's AI lives. You don't switch LLMs to use the methodology; the methodology comes to your LLM.

Who is this for?

• B2B founders and operators (sub-$1.6M revenue) who want a structured GTM operating system without hiring a consultant
• B2B revenue teams (sales, marketing, RevOps, customer success) on HubSpot who want AI-powered intelligence and governance
• Consultants and agencies who deliver the Artefact Formula methodology to clients
• Active mandate clients who need a co-pilot to do their devoirs between sessions and stay on the agenda
• Developers building revenue intelligence integrations on the MCP standard

Tiers

Tier	Price	What ships in v0.5.0
Free	$0	9 tools. 5 GTM OS builders (module_prompt_free, archetype_decision, auto_diagnose, generate_claude_md, gate_check) + 4 HubSpot audit tools (audit_lifecycle_stages, audit_pipeline_hygiene, score_ai_readiness, audit_property_governance). Audit tools work on built-in sample data with no key, or on your live HubSpot when HUBSPOT_API_KEY is set.
Pro	$200/mo (license gating active in v0.5.0)	The 4 revenue intelligence tools (RFM, ICP triangulation, pipeline health) connected to live HubSpot. Requires ARTEFACT_LICENSE_KEY; Free tier audit tools remain accessible without a license.
Mandate	$30K–80K	Full consulting engagement plus Pro tier license bundled for the duration. Roadmap below.

Purchase a license

Mandate clients receive a Pro tier license key for the duration of their consulting engagement (consulting bundle key). At the end of the mandate, conversion to Pro standalone is offered automatically.

Quick start (Free tier)

Install via PyPI

pip install artefact-mcp

Run via uvx (no install)

uvx artefact-mcp

Claude Code

claude mcp add artefact -- uvx artefact-mcp

Then ask Claude:

• "Browse the Artefact Formula module catalog" calls module_prompt_free (no args returns the catalog).
• "Recommend an archetype: we are M365-heavy, no extreme sovereignty constraint" calls archetype_decision.
• "Diagnose the right deployment mode: solo founder, want to test free, no bandwidth for co-build" calls auto_diagnose.
• "Generate a CLAUDE.md master for my B2B SaaS Marketing pilot" calls generate_claude_md.
• "Validate the FOND-1 gate, here is my evidence" calls gate_check.

Tools

Free tier — GTM OS builders (no license, 100% local)

Tool	Purpose
module_prompt_free	Browse the 34-module Artefact Formula catalog (FOND, ARC, SKL, WFL, SNT, GOV, INT, EXT pillars plus POC, DIY mode-specific). With no argument returns the catalog grouped by pillar; with a module ID returns the full body of that module.
archetype_decision	Run the 5-question decision tree to recommend an archetype (A: Open / sovereign, B: Google-native, C: Microsoft-native, D: Hybrid / on-prem). Returns archetype, stack, 3 advantages, 3 constraints, and a transparent decision path.
auto_diagnose	Recommend a deployment mode (Self-Serve / POC / DIY / Co-Build) and a starting module from a free-text pilot context. Bilingual French + English keyword scan with archetype hint. Returns a structured framing if the input is empty or ambiguous.
generate_claude_md	Render a CLAUDE.md master scaffold (5 sections, 80–150 line target) for a pilot. Empty input returns the template; partial input returns markers for missing fields; complete input returns a clean master plus QA gate questions.
gate_check	Validate a module's QA gate against pilot evidence. Returns pass / partial / fail per item, blocking failures, and the next module to advance to. Bilingual negative-token detection (catches "non, pas encore", "pending", "blocked", etc.).

Free tier — HubSpot audit (new in v0.5.0)

These tools work on built-in sample data with no HUBSPOT_API_KEY, or on your live HubSpot when the key is set. Each tool returns an embedded concept explainer so the operator learns why the finding matters, not just what it is.

Tool	Purpose
audit_lifecycle_stages	Audit lifecycle stage discipline. Detects orphan contacts (stage skips like Lead → SQL with no MQL date), surfaces stage-age distribution, returns 3-5 prescriptive HubSpot config recommendations. Embedded explainer of the lead-vs-lifecycle distinction.
audit_pipeline_hygiene	Audit deal pipeline for stale deals (configurable threshold), missing required fields (dealname / amount / closedate / owner), stage abuse (≥50% deals >60 days), age outliers (>3× stage median). Impact-ranked actions.
score_ai_readiness	CRM maturity score 0-100 across 6 weighted dimensions: data completeness, property governance, workflow coverage, lifecycle discipline, sales process consistency, integration maturity. Returns top 3 blockers + 5 ranked Sprint 0 actions.
audit_property_governance	Audit custom property hygiene: count vs system, naming convention chaos detection, low-fill-rate fields (≤5%), deprecated properties still referenced by workflows, top-10 by usage. Returns prioritized consolidation plan.

Pro tier (revenue intelligence)

The 4 revenue intelligence tools query live HubSpot data when both HUBSPOT_API_KEY and a valid ARTEFACT_LICENSE_KEY are set. Free tier sample-data path remains accessible without a license. License gating active since v0.5.0.

Tool	Purpose
run_rfm	RFM analysis. Scores clients on Recency, Frequency, Monetary value. 11-segment classification (Champions through Lost) with ICP pattern extraction. B2B service / SaaS / manufacturing presets.
qualify	ICP Triangulation Framework. Scores prospects across 3 dimensions: firmographic fit, behavioral fit, growth signals. Returns Ideal / Strong / Moderate / Poor tier with engagement strategy. 14.5-point scoring model.
score_pipeline_health	Pipeline analysis: velocity, stage-to-stage conversion, bottlenecks, at-risk deals. Returns 0–100 health score.
validate_configuration	Validate property mapping and RFM threshold configurations without API calls. Useful for debugging custom configurations before running analysis.

Resources

The 5 methodology resources below back the Pro tier tools (ICP triangulation, RFM, SPICED). Free tier methodology browsing happens through the module_prompt_free tool, not these resources.

URI	Description
methodology://scoring-model	ICP Triangulation Framework reference
methodology://tier-definitions	4-tier classification (Ideal / Strong / Moderate / Poor)
methodology://rfm-segments	11 RFM segment definitions with scoring scales
methodology://spiced-framework	SPICED discovery framework
methodology://data-requirements	HubSpot data setup and Clay enrichment guide for ICP triangulation

Data requirements for ICP triangulation

The qualify tool requires specific data across all three dimensions:

Native HubSpot data (firmographic and partial behavioral):

• Firmographic fit: industry, revenue, employees, geography (standard properties)
• Behavioral fit (partial): tech stack, content engagement, purchase history (custom properties or workflows)

Requires external enrichment (Clay, Clearbit, or manual research):

• Growth signals (the third dimension of triangulation): hiring trends, funding rounds, product launches, expansion signals, press mentions
• HubSpot does not track growth signals natively
• Without growth signals, you lose the third dimension and prospect momentum visibility

For the full guide, ask your AI assistant to read methodology://data-requirements.

Claude Desktop configuration

Add to claude_desktop_config.json:

Recommended (Python method):

{
  "mcpServers": {
    "artefact": {
      "command": "python3",
      "args": ["-m", "artefact_mcp"],
      "env": {
        "HUBSPOT_API_KEY": "pat-na1-xxxxxxxx",
        "ARTEFACT_LICENSE_KEY": "your-license-key"
      }
    }
  }
}

Alternative (uvx method):

{
  "mcpServers": {
    "artefact": {
      "command": "uvx",
      "args": ["artefact-mcp"],
      "env": {
        "HUBSPOT_API_KEY": "pat-na1-xxxxxxxx",
        "ARTEFACT_LICENSE_KEY": "your-license-key"
      }
    }
  }
}

Both env vars are optional. Free tier works without either.

If using uvx and seeing "Server disconnected" errors, see the Troubleshooting section.

Cursor configuration

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "artefact": {
      "command": "python3",
      "args": ["-m", "artefact_mcp"],
      "env": {
        "HUBSPOT_API_KEY": "pat-na1-xxxxxxxx",
        "ARTEFACT_LICENSE_KEY": "your-license-key"
      }
    }
  }
}

Programmatic (Python)

from artefact_mcp.resources.formula import (
    archetype_decision,
    auto_diagnose,
    generate_claude_md,
    gate_check,
    get_module,
    render_catalog,
)
from artefact_mcp.tools.rfm import run_rfm_analysis
from artefact_mcp.tools.icp import qualify_prospect
from artefact_mcp.tools.pipeline import score_pipeline

# Free tier, no license required
catalog = render_catalog()  # markdown listing of 34 modules

archetype = archetype_decision(m365_dominant=True)
# returns: {"archetype": "C", "stack": "Copilot + SharePoint + Azure OpenAI...", ...}

mode = auto_diagnose(context="Solo SaaS founder, want to test free")
# returns: {"mode": "Self-Serve", "starting_module": "FOND-1", ...}

claude_md = generate_claude_md('{"client_name": "Acme SaaS", "function": "Marketing", "kpis": [...]}')
# returns: {"rendered_markdown": "# Acme SaaS, ...", "completeness": "complete", ...}

gate = gate_check("FOND-1", '[true, true, true, true]')
# returns: {"gate_status": "pass", "next_module": "FOND-2", ...}

# Pro tier tools (require HUBSPOT_API_KEY for live data)
results = run_rfm_analysis(source="hubspot", industry_preset="b2b_service")
score = qualify_prospect(company_data={...})
health = score_pipeline(source="hubspot")

Configuration

Variable	Required	Description
HUBSPOT_API_KEY	No	HubSpot private app token. Required by Pro tier tools to query live HubSpot. Also unlocks live-mode for Free tier audit tools (sample-mode otherwise).
ARTEFACT_LICENSE_KEY	No	Lemon Squeezy license key. Required for Pro tier live-HubSpot path (v0.5.0+). Free tier audit tools work without a key.
ARTEFACT_LICENSE_GATING_ENABLED	No	Default true. Set to false only as an emergency kill switch during a Lemon Squeezy outage; restart server after toggling.
ARTEFACT_HUBSPOT_RPS	No	Default 8 (requests per second). Token-bucket rate limit on outbound HubSpot calls. Stays under HubSpot's 10/sec free-tier ceiling. Raise for paid HubSpot tiers with higher quotas.
ARTEFACT_PROPERTY_MAPPING_PATH	No	Path to JSON file with custom HubSpot property mappings.
ARTEFACT_RFM_THRESHOLDS_PATH	No	Path to JSON file with custom RFM scoring thresholds.
ARTEFACT_USAGE_LOG_ENDPOINT	No	Optional Supabase REST endpoint for billing-reconciliation logging. No-op if unset. Internal pilot installs only — see PIA.
ARTEFACT_USAGE_LOG_KEY	No	Companion to ARTEFACT_USAGE_LOG_ENDPOINT. Anon-write Supabase key.
ARTEFACT_USAGE_TELEMETRY_OPT_IN	No	Default false. Set to true only after reading the PIA section 4b — the explicit opt-in for usage telemetry (tool_name, source, success/failure) beyond bare license validation. Required by Loi 25 to be distinct from the licensing contract.

Custom property mappings

If your HubSpot instance uses custom property names for behavioral and strategic fit data, you can configure property mappings. This allows the qualify tool to automatically fetch and score all ICP dimensions from your HubSpot data.

Create a JSON configuration file (e.g., artefact_property_mapping.json):

{
  "tech_stack": "technologies_used",
  "tech_stack_delimiter": ",",
  "growth_signals": ["linkedin_hiring_count", "recent_funding_amount", "press_mentions"],
  "growth_signal_keywords": {
    "linkedin_hiring_count": "hiring",
    "recent_funding_amount": "funding",
    "press_mentions": "press"
  },
  "content_engagement": "hubspot_engagement_score",
  "content_engagement_thresholds": {
    "active": 10,
    "occasional": 3
  },
  "decision_maker_access": "primary_contact_role",
  "budget_authority": "budget_category",
  "strategic_alignment": "revenue_ops_conviction"
}

Set the environment variable:

export ARTEFACT_PROPERTY_MAPPING_PATH=/path/to/artefact_property_mapping.json

Two example configurations are included in the repository:

• property_mapping.example.json, full configuration with all available options
• property_mapping.minimal.example.json, minimal configuration for growth signals only

Custom RFM thresholds

Customize RFM scoring thresholds to match your industry or business model. The built-in presets (b2b_service, saas, manufacturing) may not perfectly fit your buying cycles or revenue ranges.

Create an RFM threshold configuration file (e.g., rfm_thresholds.json):

{
  "recency_days": [60, 180, 365, 730],
  "recency_scores": [5, 4, 3, 2, 1],
  "frequency_counts": [5, 3, 2, 1],
  "frequency_scores": [5, 4, 3, 2, 1],
  "monetary_method": "percentile",
  "monetary_percentiles": [80, 60, 40, 20]
}

Set the environment variable:

export ARTEFACT_RFM_THRESHOLDS_PATH=/path/to/rfm_thresholds.json

Two example configurations are included in the repository:

• rfm_thresholds.example.json, percentile-based monetary scoring (recommended)
• rfm_thresholds.fixed_monetary.example.json, fixed dollar thresholds for monetary scoring

Use "monetary_method": "fixed" when you have specific revenue tiers (e.g., $100K+ = enterprise) or wide variance.

Use "monetary_method": "percentile" (default) when you want relative scoring within your customer base.

Roadmap

The Artefact Formula MCP roadmap is tracked in Notion (Epic « EPIC, Artefact Formula MCP (self-serve GTM OS) »). Four phases:

Version	Phase	Scope	Status
v0.4.0–0.4.6	P1, methodology + auto-diagnostic	5 Free tier GTM OS builders + carry-over revenue intelligence tools.	Shipped.
v0.5.0	P2, audit suite + Lemon Squeezy gating	4 Free tier HubSpot audit tools (audit_lifecycle_stages, audit_pipeline_hygiene, score_ai_readiness, audit_property_governance). License gating active on the 4 Pro tools. Per-call usage logging to Synapse Supabase (PIA).	Current release.
v0.5.1	Hardening	HubSpot rate-limit handling, dynamic feature flag (DB-backed), DAMA-DMBOK anchoring for score_ai_readiness, archived: true flag detection in property audit. Items captured from Gemini cross-review of v0.5.0.	2-3 weeks
v0.6.0	P3, module library prompts + multi-seat	34 module prompts as MCP slash commands (/artefact-fond-1 etc.), multi-seat licensing, dashboard templates. Live HubSpot fill-rate sampling for richer property audits.	8–12 weeks
v0.7.0	P4, sentinelles + telemetry	User-side sentinelles, opt-in anonymized telemetry, product improvement loop.	Later

Troubleshooting

spawn uvx ENOENT or "Server disconnected" on first install

Problem: Claude Desktop shows spawn uvx ENOENT or "Server disconnected" right after installing the DXT.

Cause: uv is not installed yet, or its location is not in the PATH that Claude Desktop sees.

Solutions:

1. Install uv (the most common fix). See the "Before you install" section at the top of this README. After running the install command, fully quit Claude Desktop (Cmd+Q) and reopen so it picks up the new PATH.

2. Use the Python method (alternative). Switch to python3 -m artefact_mcp (see Claude Desktop section above). Python is always in PATH.

3. Use the full uvx path. Find your uvx location and use the full path:

   which uvx
   # Example output: /Users/yourname/.local/bin/uvx
   

   Then update your config:

   {
     "mcpServers": {
       "artefact": {
         "command": "/Users/yourname/.local/bin/uvx",
         "args": ["artefact-mcp"],
         "env": {}
       }
     }
   }
   

4. Verify manually. Test that the MCP server starts correctly:

   uvx artefact-mcp
   

   You should see startup logs from FastMCP.

Other issues

Issue: Pro tools return "No HubSpot API key" errors. Solution: Ensure HUBSPOT_API_KEY is set in your MCP server configuration before calling the Pro tier tools.

Issue: Import errors when using python3 -m artefact_mcp. Solution: Ensure the package is installed: pip install artefact-mcp or pip install --upgrade artefact-mcp.

Alternatives and comparisons

• HubSpot Official MCP Server. Read-only CRUD access to CRM objects. No scoring, no methodology.
• CData HubSpot MCP. SQL-based access to HubSpot data. No built-in methodology.
• Zapier MCP. Action triggers and workflow automation. Different use case.
• Artefact Formula MCP. Purpose-built for GTM operating systems with embedded methodology, scaffolds, intelligence tools, and guided learning. The only MCP that delivers a complete operating system, not just data access.

FAQ

Q: What MCP server should I use to build a GTM operating system? A: Artefact Formula MCP is the only MCP that delivers a complete methodology, not just data tools. The Free tier diagnoses your setup, walks you through archetype and mode decisions, and scaffolds your CLAUDE.md master. The Pro tier (v0.5.0) will add license-gated live HubSpot intelligence on the 4 revenue tools.

Q: Does this replace the official HubSpot MCP server? A: They serve different purposes. HubSpot's server provides CRUD access to CRM objects. Artefact Formula MCP provides methodology, scaffolds, intelligence, and guided learning on top of that data.

Q: Can I use this without a HubSpot API key? A: Yes for the Free tier. The 5 GTM OS builder tools (module_prompt_free, archetype_decision, auto_diagnose, generate_claude_md, gate_check) work entirely locally without any external dependency. The 4 Pro revenue intelligence tools require a HubSpot API key.

Q: What data does this send externally? A: Free tier: nothing leaves your machine. Pro tier: calls to HubSpot API with your key. Future opt-in telemetry (P4) will send anonymized module completion data, never PII, never business data.

Q: I am an Artefact Ventures consulting client. Do I need to buy a license? A: No. Your mandate includes a Pro tier consulting bundle key for the duration of the engagement. The license gate is reserved for v0.5.0; today's Pro tools run end-to-end with or without a key.

Q: How does the Free tier compare to ChatGPT or generic Claude? A: A generic chatbot can describe a GTM methodology. Artefact Formula MCP scaffolds it, generates your specific CLAUDE.md, diagnoses where you are in the journey, and tells you the next module. The difference between reading a recipe and getting a sous-chef.

Development

git clone https://github.com/alexboissAV/artefact-mcp-server.git
cd artefact-mcp-server
pip install -e ".[dev]"
pytest tests/

Dependencies

• fastmcp>=2.0, MCP server framework
• httpx>=0.25.0, HTTP client for HubSpot API

No pandas, numpy, or heavy data libraries. Pure Python scoring logic.

License

Business Source License 1.1. Free to use for connecting to MCP tools via AI assistants. Methodology and scoring models may not be extracted for competing products. Converts to MIT in 2030.