---
name: affinity-connect-mcp
description: Downloadable optional skill for using Affinity Connect over MCP. Use after connecting an Affinity MCP API token to Claude, Perplexity, ChatGPT, OpenClaw, Hermes, GitHub Copilot, or another MCP-capable assistant. Covers role-aware access, safe tool use, website/CRM/reporting workflows, and current Gemini-backed Affinity guidance.
---

# Affinity Connect MCP Helper

This skill helps an AI assistant use Affinity Connect tools well after the MCP
connection is already configured.

The skill is optional. The MCP API token connects the tools; this file gives the
assistant operating guidance so it chooses the right tools, asks better
questions, and avoids unsafe changes.

## Required Connection Details

Use the hosted Affinity MCP endpoint:

```text
https://api.v2.affinitydesign.ca/mcp/http
```

Authentication uses an Affinity API key with the `mcp:access` scope.

When the client asks for a header, use:

```text
X-API-Key: afk_YOUR_KEY_HERE
```

Never store a real `afk_...` key in a public repo, shared screenshot, prompt
template, or reusable skill file.

## Access Levels

### Agency

Agency operators may use either:

- **Agency MCP master key** from Config -> Agency MCP for trusted internal work
  across agency-managed connections.
- **Per-client API key** from a client's API Keys tab for scoped client access.

Default to per-client keys for contractors, temporary assistants, client-specific
work, or narrow access. Use Agency MCP master keys only for trusted internal
operators who are allowed to see and operate across the agency's managed
connections.

### Client

Client users are business-owner portal users. They should request an Affinity MCP
API token from their agency representative.

The token is scoped to the client's business workspace and enabled plugins. If a
tool is missing, ask the agency representative to adjust the token or plugin
access.

### User

User accounts are restricted client team-member workflows. They should also
request an Affinity MCP API token from their agency representative.

Expect narrower access than a business-owner client account. Respect missing
tools or denied operations as intentional unless the user says the agency already
approved wider access.

## App Setup Patterns

### Claude Code

Use HTTP transport:

```bash
claude mcp add --transport http affinity-connect https://api.v2.affinitydesign.ca/mcp/http \
  --header "X-API-Key: afk_YOUR_KEY_HERE"
```

For a team-shared project config, keep the key in an environment variable:

```json
{
  "mcpServers": {
    "affinity-connect": {
      "type": "http",
      "url": "https://api.v2.affinitydesign.ca/mcp/http",
      "headers": {
        "X-API-Key": "${AF_MCP_API_KEY}"
      }
    }
  }
}
```

### Claude Web or Desktop

Add a custom connector named `Affinity Connect`.

Use:

```text
https://api.v2.affinitydesign.ca/mcp/http
```

When Claude opens the authorization screen, paste the `afk_...` API key. If your
Claude Desktop version uses JSON config instead, use the HTTP MCP config above.

### Perplexity, ChatGPT, OpenClaw, Hermes, GitHub Copilot

Use the same hosted MCP URL and API-key header pattern:

```json
{
  "name": "Affinity Connect",
  "url": "https://api.v2.affinitydesign.ca/mcp/http",
  "headers": {
    "X-API-Key": "afk_YOUR_KEY_HERE"
  }
}
```

If the app asks for a secret/header pair, the header name is `X-API-Key` and the
secret value is the `afk_...` token.

## First Checks After Connecting

Always start a new Affinity MCP session by checking what the current token can
see.

Ask or run:

```text
List the Affinity tools you have available and group them by plugin.
```

Then summarize:

- which client or agency scope appears to be active
- which plugins are available
- whether write-capable tools are present
- whether anything important is missing for the user's request

Do not assume a tool exists just because this skill mentions a workflow. The API
key and plugin restrictions are the source of truth for the current session.

## Common Plugin Areas

Available tools depend on the token's plugin list. Common plugins include:

| Plugin | Typical use |
| --- | --- |
| `core` | Client info, agent lookup, call history, availability |
| `ghl` | GoHighLevel contacts, appointments, opportunities, notes |
| `ghl-social` | GoHighLevel social planner and analytics |
| `wordpress` | Connected WordPress content, taxonomies, SEO, Elementor |
| `github` | Connected repo reads, working-branch commits, pull requests |
| `ga4` | Google Analytics reporting |
| `gbp` | Google Business Profile locations, attributes, images, performance |
| `google-ads` | Google Ads read/audit workflows and landing-page context |
| `meta-ads` | Meta Ads insights, proposals, creative loops, guarded apply workflows |
| `cloudflare` | Cloudflare website bindings, DNS, Pages/deployment feedback |
| `vercel` | Vercel project bindings, deployments, deployment feedback |
| `image-generation` | Brand-aware image generation and design ideation |
| `verification` | Provider-neutral post-write verification |

## Operating Rules

1. Verify scope before acting. Know whether the session is agency-wide,
   client-scoped, or user-scoped.
2. Prefer read and plan steps before writes.
3. For write-capable operations, explain the intended change and wait for user
   confirmation when the action affects websites, CRM records, ads, billing,
   publishing, DNS, deployments, or repository contents.
4. Never reveal, log, or repeat raw API keys, OAuth tokens, payment data, lead
   PII, customer records, or private client details unless the user explicitly
   asks for their own data and the tool returns it for that scoped account.
5. Treat tool errors and missing tools as useful evidence. Do not pretend a
   change happened if the tool did not confirm it.
6. When a write returns a verification hint or a verification tool is available,
   run verification before calling the work complete.

## Website And Content Workflows

When using WordPress or GitHub tools:

- Identify the target website first if multiple sites are connected.
- Read current content before editing.
- Keep changes bounded to the requested page, post, component, or asset.
- For WordPress Elementor work, prefer inspect -> plan -> preview -> apply when
  those tools are available.
- For GitHub-backed sites, expect commit-first workflows on the configured
  working branch. Do not assume direct writes to `main` are allowed.
- After a write, verify with public URL checks, deployment evidence, or the
  `verification` plugin when available.

## CRM, Calls, And Appointments

When using GHL or call tools:

- Confirm the contact or opportunity before updating it.
- Use exact dates, times, phone numbers, and time zones in confirmations.
- Do not send outbound messages or initiate calls without explicit user intent.
- Summarize actions with the contact/opportunity identifier returned by tools
  when available.

## Reporting And Analytics

When using GA4, GBP, ads, reporting, or billing tools:

- State the date range and comparison period.
- Separate observed data from recommendations.
- Avoid overstating causality. Use language like "correlates with" unless the
  tool or data proves cause.
- For client-facing summaries, keep language plain and action-oriented.

## Gemini-Backed Affinity Work

Affinity uses Gemini-backed systems for voice, prompts, and model-powered
workflows. When the user asks to change Gemini behavior, model settings, prompts,
Live API behavior, or voice-agent instructions inside an Affinity repo:

- Consult the repo's current Gemini guidance first when available:
  - `.github/skills/gemini-api-dev/SKILL.md`
  - `.github/skills/gemini-interactions-api/SKILL.md`
  - `.github/skills/gemini-live-api-dev/SKILL.md`
  - `docs/gemini/gemini-prompt-guide.md`
  - `docs/gemini/google-live-api-ref.md`
- Do not invent Gemini model IDs.
- Prefer the repo's current allowed model names and gateway helpers over older
  examples from memory.
- For Gemini Live API work, pay special attention to realtime input rules,
  session limits, interruption handling, and processing all parts in each server
  event.

## Prompt Starters

Use these when beginning a session:

```text
List the Affinity MCP tools available in this session and tell me what client or agency scope this token appears to have.
```

```text
Before making changes, inspect the connected website/repo and propose the smallest safe plan.
```

```text
After any write, verify the public result or deployment state before saying it is complete.
```

```text
If a requested tool is missing, tell me which plugin or token permission my agency rep should enable.
```

## Troubleshooting

### No tools appear

Check that the key has `mcp:access`, the client is active, and the app is using
the HTTP MCP URL.

### Some tools are missing

The API key likely has plugin restrictions, or the client does not have that
connection enabled. Ask the agency admin to check the key's plugin list.

### Unauthorized or invalid key

The key may be wrong, revoked, inactive, or copied with extra whitespace. Ask for
a fresh key if needed.

### Writes do not publish

Some website and repository tools intentionally write to drafts, working
branches, or provider queues first. Inspect the returned status and run
verification before reporting completion.