# VarynForge MCP server

> **Read your site. Forge your next ten articles.** With briefs.

VarynForge is an SEO research SaaS that exposes its full workflow as MCP tools. Connect once from Claude Desktop, Cursor, Claude Code, Codex, or any MCP-compatible host — then ask your agent to set up a project, hand it your article ideas, and forge writer-ready briefs the host agent uses as its writing prompt.

- **Free tier**: forge briefs from your own ideas, 10/day
- **Paid tier**: run research to discover data-backed keyword opportunities and ranked competitor pages, then forge briefs from them. From $75/mo.
- **30+ tools** across projects, research runs, keywords, clusters, competitors, content plans, briefs, and writer guidance
- **OAuth-secured** (Better Auth) — no API keys to manage

🔗 [**Landing page + install snippets**](https://www.varynforge.com/mcp?utm_source=github_mcp_repo&utm_medium=readme) · [**Pricing**](https://app.varynforge.com/pricing?utm_source=github_mcp_repo&utm_medium=readme) · [**Marketing site**](https://www.varynforge.com?utm_source=github_mcp_repo&utm_medium=readme)

---

## Endpoint

```
https://app.varynforge.com/api/mcp
```

Streamable HTTP transport. OAuth 2.1 with dynamic client registration. On first tool call from your host, a browser window opens to sign in once.

## 60-second install

### Claude Desktop

Built-in Connectors UI — no config file needed.

1. Open Claude Desktop → **Settings → Connectors**
2. Click **Add custom connector**
3. Paste the URL: `https://app.varynforge.com/api/mcp`

<details>
<summary>Or paste this into <code>claude_desktop_config.json</code></summary>

```json
{
  "mcpServers": {
    "varynforge": {
      "url": "https://app.varynforge.com/api/mcp"
    }
  }
}
```

</details>

### Claude Code

```bash
claude mcp add --transport http varynforge https://app.varynforge.com/api/mcp
```

### Codex (CLI + IDE extension)

```bash
codex mcp add varynforge --url https://app.varynforge.com/api/mcp
```

If this is the first MCP server in Codex, you may need to enable the `experimental_use_rmcp_client` flag in `~/.codex/config.toml`.

### Cursor

One-click install — open this URL in Cursor:

```
cursor://anysphere.cursor-deeplink/mcp/install?name=varynforge&config=eyJ1cmwiOiJodHRwczovL2FwcC52YXJ5bmZvcmdlLmNvbS9hcGkvbWNwIn0=
```

<details>
<summary>Or paste this into <code>.cursor/mcp.json</code></summary>

```json
{
  "mcpServers": {
    "varynforge": {
      "url": "https://app.varynforge.com/api/mcp"
    }
  }
}
```

</details>

### VS Code

One-click install:

```
https://insiders.vscode.dev/redirect/mcp/install?name=varynforge&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fapp.varynforge.com%2Fapi%2Fmcp%22%7D
```

## Tool catalog (30+ tools, 8 categories)

### Projects + niche

- `create_project` — Create a new project from a website URL or niche description. Returns immediately; niche analysis and asset mapping run asynchronously.
- `list_projects` — List all projects for the authenticated operator.
- `get_project` — Get one project's niche profile, target audience, and research status.
- `get_project_asset` — Get the asset (website / product) associated with a project.
- `get_project_overview` — At-a-glance read on a project — niche summary, keyword stats, top-priority suggestions.
- `update_niche` — Update a niche profile (name, industry, language, country).

### Research lifecycle

- `start_research_run` — Trigger a research run (paid; one credit).
- `get_research_status` — Poll the latest run — runId, status, progress percent, elapsed seconds, last error.

### Keywords + opportunities

- `list_keywords` — List keywords tracked for a project — text, difficulty, intent, volume bucket.
- `get_keyword_detail` — Get a keyword's ranking pages and related project keywords.
- `list_opportunities` — List ranked content opportunity clusters. Goal filters: `fast_wins`, `high_intent`, `authority_building`, `competitor_gap`.
- `get_opportunity_detail` — Get a cluster's top-20 keywords, top-10 pages, top-5 podium, linked suggestions.

### Competitors

- `list_competitors` — List companies tracked as competitors for a project.
- `get_competitor_detail` — Company detail in a project context — top pages, top keywords.
- `set_competitor_importance` — Mark a competitor important / default / ignored.
- `add_competitor_by_domain` — Add a competitor by domain (e.g. example.com).

### Pages

- `list_pages` — List ranked pages tracked for a project.
- `get_page_dossier` — Page dossier — title, URL, target keywords, content analysis, rankings.

### Content plan + suggestions

- `list_article_suggestions` — List article suggestions in a project's content plan.
- `get_article_suggestion` — Get an article suggestion's details and brief availability.
- `add_article_suggestion` — Add a bare article suggestion (title + optional intent).
- `create_article_suggestion_with_input` — Free-tier path: create a brief-ready suggestion from your own input (title, keywords, intent, audience, angle).
- `delete_article_suggestion` — Delete an article suggestion and its brief.
- `update_article_status` — Move an article through `planned` → `generating_brief` → `brief_ready` → `out_for_writing` → `monitoring`.
- `create_content_plan_from_opportunities` — Harvest top-30 opportunity clusters from a completed research run into a content plan.

### Brief generation + writer handoff

- `generate_article_brief` — Forge a writer-ready brief. Idempotent: returns the existing brief without consuming quota; pass `force: true` to regenerate. Free: 10/day. Paid: unlimited.
- `get_article_brief` — Get the full brief. Pass `compact=true` to drop `referenceArticles`; editorial fields stay populated.
- `download_brief_markdown` — Get the brief assembled as inline markdown (≤8K chars) for the host agent to use as a writing prompt.

### Agent guidance

- `get_instructions` — VarynForge workflow guide for the host agent (free vs paid paths, token-economy rules, walls).
- `get_account_status` — Current plan, limits, locked tools, upgrade URL, plans summary.
- `get_writer_system_prompt` — Writer system prompt the host agent loads before drafting articles.

## How walls work

Paywalled tools and rate limits never throw a generic error. They return a structured payload your agent reads directly:

```json
{
  "error_code": "PAYMENT_REQUIRED",
  "reason": "Research runs require a paid plan",
  "remaining": 0,
  "reset_at": null,
  "upgrade_url": "https://app.varynforge.com/pricing?utm_source=mcp&utm_medium=tool_wall",
  "upgrade_rationale": "...",
  "what_unlocks": "Data-backed keyword opportunities, competitor pages, content plans",
  "alternative_free_actions": ["create_article_suggestion_with_input", "..."]
}
```

This lets your host agent surface the next step verbatim — including five alternative free actions when applicable.

## Tags

`seo` · `content` · `keyword-research` · `briefs` · `agent-tools` · `ai-writing`

## Registry / catalog presence

- **Official MCP Registry**: [`com.varynforge/server`](https://registry.modelcontextprotocol.io/v0.1/servers?search=com.varynforge/server)
- **Glama**: [glama.ai/mcp/connectors/com.varynforge/server](https://glama.ai/mcp/connectors/com.varynforge/server)
- **Marketing landing page**: [www.varynforge.com/mcp](https://www.varynforge.com/mcp)

## Repository scope

This repo is intentionally documentation-only — a public landing surface for catalog moderators and host operators. The MCP server itself is a hosted service at the endpoint above; the implementation lives in the (closed-source) `varyn-forge` application.

For source-of-truth listing copy (for catalog submissions), see [`varyn-marketing/public/mcp-listing-content.md`](https://github.com/bogdibota/varyn-marketing/blob/main/public/mcp-listing-content.md).

## Support + feedback

- Open an issue on this repo for catalog metadata corrections or install guide bugs.
- Product questions / billing: `hello@varynforge.com`.

---

© VarynForge. Hosted MCP server is proprietary; this documentation repo is freely linkable and quotable.