/contentforge:cf-connect — Guided Connector Setup

Script location. If your host does not set ${CLAUDE_PLUGIN_ROOT}, the scripts are in this plugin's scripts/ folder, next to skills/. Run them with Python 3.10 or newer: python, or python3 where python is not found (macOS, many Linux systems).

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 no `.mcp.json` (it is gitignored). 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 their own .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 "${CLAUDE_PLUGIN_ROOT}/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 "${CLAUDE_PLUGIN_ROOT}/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:

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

Step 2: Check Current Status (Instant)

python "${CLAUDE_PLUGIN_ROOT}/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.

1. Restart the session so the new entry is picked up.
2. 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 (vendor-published packages only)

ContentForge gives a runnable npx command only for a package the service's vendor publishes, and the list is config/verified-npx-packages.json (the package name, the npm account expected on it, the vendor's repository). Today that is DeepL. npx -y <name> downloads and runs whatever is published under that name with the user's API keys in its environment, so a community package, or a name nobody has registered, is never offered.

Every other connector whose setup-guide says "transport": "manual" has no verified connector. For those, relay the guide's options and stop there: the vendor's own MCP server if it publishes one (an HTTP address from the vendor's documentation), an aggregator entry from .mcp.json.connectors-reference, or skip it. Do not search npm for a package, guess a package name, suggest npx -y for it, or write environment variables for it. If the user mentions a community package themselves, say it is an unverified third party and that they should read its source and check its publisher before running it; give no command for it.

For a connector whose guide says "transport": "npx" (a verified package), the pattern is:

1. Get the package name and env vars from python "${CLAUDE_PLUGIN_ROOT}/scripts/connector-status.py" --action setup-guide --name <connector>.
2. Obtain credentials from the service (for DeepL: an API key from the DeepL account page).
3. Set environment variables (shell profile or .env loaded before Claude Code starts; on Windows: System Properties → Environment Variables, then restart the terminal):

   export DEEPL_API_KEY="<your DeepL API key>"

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

   "deepl": {
     "command": "npx",
     "args": ["-y", "deepl-mcp-server"],
     "env": {
       "DEEPL_API_KEY": "${DEEPL_API_KEY}"
     }
   }

1. 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. Do not offer an npx entry: ContentForge gives a command only for the vendor-published packages in config/verified-npx-packages.json.
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 "${CLAUDE_PLUGIN_ROOT}/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-translate on a short paragraph for DeepL.

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

Output

The complete setup guide includes:

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 "${CLAUDE_PLUGIN_ROOT}/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.

Agent Used

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

Related Skills

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

Script: python "${CLAUDE_PLUGIN_ROOT}/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