artefact-mcp 0.4.1

Artefact Formula MCP. GTM Operating System builder for B2B teams. Free tools (module library, archetype router, mode diagnostic, CLAUDE.md scaffolder, gate validator) plus Pro tier for HubSpot revenue intelligence (RFM, ICP triangulation, pipeline health).

Artefact Formula MCP

The GTM Operating System builder for AI-native B2B teams.

View Full Documentation

A Model Context Protocol (MCP) server that delivers the Artefact Formula methodology directly into Claude (or any MCP client). Five Free tools surface the GTM Operating System builder (module library, archetype router, mode diagnostic, CLAUDE.md scaffolder, gate validator). Four Pro tools cover HubSpot revenue intelligence (RFM, ICP triangulation, pipeline health). Built on real B2B consulting engagements at Artefact Ventures.

Strategic pivot, May 4 2026. This package now ships the full Artefact Formula GTM Operating System builder, not only the original Revenue Intelligence Tools (those continue to work and are now part of the Pro tier). See Roadmap for ship cadence.

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.4.0
Free	$0	The 5 GTM OS builder tools (module_prompt_free, archetype_decision, auto_diagnose, generate_claude_md, gate_check). 100% local, no license key.
Pro	$200/mo (license gating planned for v0.5.0)	The 4 revenue intelligence tools (RFM, ICP triangulation, pipeline health) connected to live HubSpot.
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 (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.).

Pro tier (revenue intelligence)

The 4 revenue intelligence tools query live HubSpot data when HUBSPOT_API_KEY is provided. Lemon Squeezy license gating arrives in 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 the 4 Pro tier tools to query live HubSpot data.
ARTEFACT_LICENSE_KEY	No	Lemon Squeezy license key. Reserved for v0.5.0 license gating; today the Pro tools run end-to-end without a key.
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.

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	P1, methodology + auto-diagnostic	5 Free tier tools (module_prompt_free, archetype_decision, auto_diagnose, generate_claude_md, gate_check) plus the 4 revenue intelligence tools (carry-over from v0.2.5, license gating arrives in v0.5.0).	Current release.
v0.5.0	P2, foundation tools + Lemon Squeezy gating	skill_scaffold, sentinelle_scaffold, cost_estimate, license gating on the 4 Pro tier tools, admin tool for consulting bundle keys.	4–8 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.	8–12 weeks
v0.7.0	P4, sentinelles + telemetry	User-side sentinelles, opt-in anonymized telemetry, product improvement loop.	Later

Troubleshooting

Server disconnected errors (uvx PATH issue)

Problem: Claude Desktop shows "MCP artefact: Server disconnected" error when using uvx as the command.

Cause: Claude Desktop (and other sandboxed applications) may not have access to uvx in your PATH. This commonly happens when uvx is installed via Homebrew (~/.local/bin/uvx) or curl (~/.cargo/bin/uvx).

Solutions:

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

2. 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": {}
       }
     }
   }
   

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