cf-connect

name	cf-connect
description	Set up a specific MCP connector from the ContentForge registry with step-by-step instructions tailored to its transport — verified endpoint URL for HTTP connectors, env vars plus a ready-to-paste .mcp.json entry for npx connectors, credential acquisition guidance, and post-setup verification. Triggers on "/contentforge:cf-connect", "connect WordPress", "set up the Notion connector", "how do I add Google Sheets", "a skill says a connector is missing". Status always comes from scripts/connector-status.py (never memory) and endpoints from .mcp.json.connectors-reference; fuzzy-matches names like wp or gsheets. Setup guidance only — for services not in the registry it hands off to /contentforge:cf-add-integration, and /contentforge:cf-integrations shows the full status dashboard.
argument-hint	[connector-name]
effort	low

/contentforge:cf-connect — Guided Connector Setup

Set up a specific MCP integration for ContentForge with step-by-step instructions tailored to the connector's transport type. Handles HTTP connectors (OAuth-based), npx connectors (API keys, environment variables, .mcp.json entry), unknown connector names (fuzzy matching), and post-setup verification.

The ground truth about connectors

ContentForge ships with an empty .mcp.json ("mcpServers": {}). This is deliberate (v3.9.0 Cowork-safety decision): no connector auto-connects when the plugin is installed. Every connector is opt-in — the user adds it to .mcp.json (or connects it at the platform level in Cowork/Desktop Settings → Integrations).

Never claim a connector is pre-wired or already connected. All status claims must come from running python scripts/connector-status.py — never from this file or from memory.

When to Use

Use /contentforge:cf-connect <name> when:

• You want to connect a specific service (e.g., /contentforge:cf-connect wordpress)
• A skill told you a connector is missing and suggested using this command
• You're setting up a new ContentForge installation and configuring integrations
• You need the exact environment variables and .mcp.json entry for an npx connector
• You want to verify an existing connector is working correctly

What This Command Does

1. Look Up Connector — Find the connector in the registry, handle typos and close matches
2. Check Current Status — Determine if already configured or needs setup
3. Present Setup Instructions — Tailored to transport type (HTTP vs npx)
4. Guide Credential Acquisition — Where to get API keys, which permissions to set
5. Provide .mcp.json Entry — Ready-to-paste configuration
6. Verify After Setup — Confirm environment variables are set and configuration is valid

Required Inputs

Required:

• Connector name — The service to connect (e.g., notion, wordpress, google-sheets, canva)
• Fuzzy matching is supported: wp matches wordpress, gsheets matches google-sheets, ga matches google-analytics

Optional:

• Environment — cowork or claude-code (auto-detected if not specified)

What Happens

Step 1: Look Up Connector (Instant)

Run the setup guide lookup:

python scripts/connector-status.py --action setup-guide --name <connector>

This returns:

• Connector metadata (name, category, description, transport type)
• Whether it's already configured in this installation
• Setup steps specific to the transport type
• Skills unlocked by this connector
• For npx: required environment variables and .mcp.json entry

If the connector name is not found, check common aliases before showing an error:

Input	Matches To
wp, wordpress	wordpress
gsheets, sheets, google-sheets	google-sheets
gdrive, drive, google-drive	google-drive
ga, ga4, google-analytics	google-analytics
gsc, search-console	google-search-console
gcal, calendar	google-calendar
x, twitter	twitter-x
li, linkedin	linkedin-publishing
ig, insta	instagram
hs, hubspot	hubspot-cms
sarvam	sarvam-ai

If no match is found after alias lookup, run python scripts/connector-status.py --action list-available and present the actual list.

Step 2: Check Current Status (Instant)

python scripts/connector-status.py --action check --name <connector>

This returns connected or not_connected, plus (for npx connectors) which env vars are set vs missing. Render exactly what the script reports.

If already configured: confirm to the user, list the skills it enables (from the script JSON), and stop — no action needed.

If not configured, proceed to Step 3.

Step 3: Present Setup Instructions

Instructions differ based on transport type. Both types require the user to add an entry to .mcp.json (or connect at the platform level) — nothing is pre-wired.

HTTP Connectors (e.g., Notion, Canva, Figma, Webflow, Slack, Gmail, Google Calendar, Ahrefs)

HTTP connectors are the easiest: one .mcp.json entry, no API keys for OAuth-based ones, and they work in both Cowork and Claude Code.

Setup pattern to walk the user through:

1. Get the verified endpoint URL. Use the endpoint from the setup-guide script output, cross-checked against .mcp.json.connectors-reference (the plugin's catalog of verified HTTP endpoints). Do not guess endpoint URLs from memory — unverified URLs waste the user's time.
2. Add the entry to .mcp.json in the plugin root:

   "notion": {
     "type": "http",
     "url": "<verified endpoint from the reference file>"
   }
   

   In Cowork/Claude Desktop, the platform-level integration (Settings → Integrations) may be simpler — mention it when available.
3. Restart the session so the new entry is picked up.
4. Authorize on first use. The first time a skill accesses the connector, the platform shows an OAuth prompt. Sign in and grant permissions. The token is managed by the platform afterward.

npx Connectors (e.g., WordPress, Google Sheets, Semrush, DeepL)

npx connectors require environment variables and a .mcp.json entry. They work in Claude Code only (Cowork cannot run local Node.js servers).

Setup pattern:

1. Get the package name and env vars from python scripts/connector-status.py --action setup-guide --name <connector>.
2. Verify the npm package actually exists before recommending it:

   npm view <package-name> version
   

   If the package doesn't exist or looks abandoned (no updates in 12+ months, negligible downloads), tell the user and search npm for a maintained alternative rather than proceeding.
3. Obtain credentials from the service (e.g., WordPress: admin panel → Users → Profile → Application Passwords; create one named "ContentForge" and note the site URL).
4. Set environment variables (shell profile or .env loaded before Claude Code starts; on Windows: System Properties → Environment Variables, then restart the terminal):

   export WORDPRESS_SITE_URL="https://your-site.com"
   export WORDPRESS_AUTH_TOKEN="your-application-password"
   

5. Add the .mcp.json entry (use the exact block from the setup-guide output):

   "wordpress": {
     "command": "npx",
     "args": ["-y", "<verified-package-name>"],
     "env": {
       "WORDPRESS_SITE_URL": "${WORDPRESS_SITE_URL}",
       "WORDPRESS_AUTH_TOKEN": "${WORDPRESS_AUTH_TOKEN}"
     }
   }
   

6. Restart Claude Code and verify (Step 5).

Never hardcode credentials in .mcp.json or plugin files — always reference environment variables.

Step 4: Handle Unknown Connectors

When a connector name is not in the registry and no fuzzy match exists:

1. Say clearly it's not in the registry.
2. Suggest the closest same-category connectors from --action list-available output.
3. Offer manual configuration: an HTTP entry ("type": "http", "url": ...) if the service publishes an MCP endpoint, or an npx entry if a maintained npm MCP package exists (verify with npm view first).
4. Note: manually added connectors work with Claude but won't appear in /contentforge:cf-integrations until added to the registry.
5. For a fully guided custom flow, hand off to /contentforge:cf-add-integration.

Step 5: Verify After Setup

For npx connectors, after the user follows the setup steps:

1. Re-run python scripts/connector-status.py --action check --name <connector> and render the result (env vars set/missing, .mcp.json entry found).
2. Remind the user to restart Claude Code — .mcp.json is read at startup only.
3. Suggest a first test, e.g. /contentforge:cf-publish --platform=wordpress --status=draft for WordPress.

For HTTP connectors, verification happens implicitly: the OAuth prompt appears on first real use.

Output

The complete setup guide includes:

Section	Description
Connector Info	Name, category, description, transport type (from script)
Current Status	Configured or not, with details (from script)
Setup Steps	Numbered walkthrough tailored to transport type
Skills Unlocked	Which ContentForge skills this connector enables (from script)
Credential Requirements	For npx: env vars needed with set/missing status
.mcp.json Entry	Ready-to-paste JSON block
Environment Notes	Cowork vs Claude Code compatibility, Node.js requirements
Verification Steps	How to confirm the connector works after setup

Troubleshooting

"Unknown connector" even though you typed the right name

• Connector names use lowercase kebab-case: google-sheets, not Google Sheets or googlesheets
• Try the fuzzy match: the skill checks common aliases automatically
• Run python scripts/connector-status.py --action list-available to see all valid names

npx connector configured but skills still can't use it

• Restart Claude Code after modifying .mcp.json — changes are read at startup only
• Verify the npm package name (npm view <pkg> version)
• Check that Node.js and npx are in your PATH: npx --version

Environment variables set but still showing "missing"

• Variables must be exported, not just assigned: export VAR=value
• .env files must be loaded before the Claude Code session starts
• On Windows, set them in System Properties → Environment Variables, then restart the terminal

OAuth prompt never appears for an HTTP connector

• HTTP connectors authenticate only when a skill actively requests data from them
• Confirm the entry exists in .mcp.json and the session was restarted after adding it

"npx: command not found"

• Install Node.js 18+ from https://nodejs.org, then verify node --version and npx --version

Connector works in Claude Code but not in Cowork

• npx connectors are Claude Code only — they require local Node.js
• In Cowork, prefer HTTP connectors or platform-level integrations (Settings → Integrations)
• Run /contentforge:cf-integrations to see which configured connectors are Cowork-compatible

Example Workflows

Workflow 1: Set Up WordPress Publishing

1. /contentforge:cf-connect wordpress
   -> Follow steps: verify package on npm, get application password, set env vars, add to .mcp.json
2. Restart Claude Code
3. /contentforge:cf-integrations
   -> Verify WordPress shows as configured (from script output)
4. /contentforge:create-content "Your Topic" --type=blog --brand=YourBrand
5. /contentforge:cf-publish --platform=wordpress --status=draft

Workflow 2: Add Google Sheets for Batch Processing

1. /contentforge:cf-connect google-sheets
   -> Follow steps: create service account, download credentials JSON, set env var, add to .mcp.json
2. Restart Claude Code
3. /contentforge:batch-process <sheet URL>
   -> Reads requirements from the sheet, processes them one at a time (checkpointed queue)

Workflow 3: Connect SEO Tools for Data-Driven Briefs

1. /contentforge:cf-connect ahrefs
   -> HTTP connector: add the verified endpoint to .mcp.json, restart, authorize on first use
2. /contentforge:cf-brief "AI in Healthcare 2026" --brand=AcmeMed
   -> Brief now includes real keyword data from Ahrefs

Optional Connectors (Tier-2 External Validators)

The following connectors are optional and enable enhanced validation passes during specific pipeline phases. They are auto-detected if available (via MCP discovery) and never required — the built-in validators run everywhere without them.

Connector	Service Type	Use Case
AI-detection (optional)	any MCP-served detector (e.g. a Hugging Face Space)	Phase 6.5 external validation pass — advisory only; the built-in tell-scan runs everywhere without it

Agent Used

None. This skill is entirely script-driven using scripts/connector-status.py.

Related Skills

• /contentforge:cf-integrations — Full integration status dashboard
• /contentforge:cf-add-integration — Guided flow for services not in the registry
• /contentforge:create-content — Main content production pipeline
• /contentforge:batch-process — Sequential, checkpointed batch processing

---

Script: python scripts/connector-status.py --action setup-guide --name <connector> Network Required: No for status checks (reads local config and env vars); yes only for npm view package verification