# RankOrg - Developer Docs (Integrations, API & MCP)

> RankOrg is a multi-tenant SEO automation platform. It publishes generated SEO articles to a hosted subdomain, a custom domain, WordPress, or any endpoint via signed webhooks - and exposes the whole engine to AI assistants (Claude, ChatGPT, Cursor) through a Model Context Protocol (MCP) server.

## Docs pages

- Human docs index: https://rankorg.com/docs
- Publishing integrations: https://rankorg.com/docs/integration
- MCP for AI agents: https://rankorg.com/docs/mcp

# RankOrg - Publishing Integrations

Configure where generated SEO articles go live: RankOrg-hosted domains, your own domain, WordPress, or signed webhooks.

## Publishing destinations

Every RankOrg site publishes to one destination. The canonical URL points at that destination so the same article does not compete with itself across domains.

- **Hosted subdomain** (e.g. `yourname.rankgt.com`): The fastest path — a RankOrg-hosted blog on a *.rankgt.com subdomain with automatic TLS. Live in seconds, no DNS changes.
- **Custom domain** (e.g. `blog.yourdomain.com`): Point a subdomain at RankOrg with a single CNAME. RankOrg issues TLS automatically and sets the canonical URL to your domain so there's no duplicate indexing.
- **Proxy subpath** (e.g. `yourdomain.com/blog/*`): Serve the blog under a path on your existing root domain (e.g. /blog) via a reverse proxy, so the content ranks on your primary domain's authority.

## WordPress integration

Publish generated articles straight into a self-hosted or WordPress.com site via the WordPress REST API. RankOrg creates each post with status 'publish'.

- Connect fields:
  - `siteUrl`: Your WordPress site URL, e.g. https://mysite.com.
  - `username`: A WordPress user with permission to publish posts.
  - `appPassword`: A WordPress Application Password (Users → Profile → Application Passwords). Not your login password.
- Auth: HTTP Basic (username + application password), sent to /wp-json/wp/v2/posts.
- Credentials are verified against /wp-json/wp/v2/users/me at connect time and stored encrypted.

## Webhooks

RankOrg POSTs a signed JSON event to your endpoint every time an article publishes, so you can sync content into any CMS, cache, or pipeline.

- Event: `article.published` (version 2026-06-09)
- Request headers:
  - `X-RankOrg-Event`: The event type, e.g. article.published.
  - `X-RankOrg-Delivery`: Unique delivery id (matches payload.id).
  - `X-RankOrg-Timestamp`: Unix seconds when the request was signed.
  - `X-RankOrg-Signature`: sha256=<hex HMAC> — see verification below.
- Signature: HMAC-SHA256 over the string `{timestamp}.{rawRequestBody}` using your webhook secret (whsec_…). Recompute it and compare in constant time; reject if it doesn't match or the timestamp is stale.
- Delivery: Up to 3 attempts. Retried on HTTP 408, 425, 429, or any 5xx; a 2xx marks the delivery successful.

Example `article.published` payload:

```json
{
  "id": "evt_...",
  "version": "2026-06-09",
  "event": "article.published",
  "createdAt": "2026-07-03T09:00:00.000Z",
  "site": {
    "id": "site_...",
    "name": "Acme Blog",
    "slug": "acme",
    "canonicalHost": "blog.acme.com",
    "blogUrl": "https://blog.acme.com/blog"
  },
  "article": {
    "id": "art_...",
    "title": "…",
    "slug": "my-post",
    "url": "https://blog.acme.com/blog/my-post",
    "canonicalUrl": "https://blog.acme.com/blog/my-post",
    "metaDescription": "…",
    "contentHtml": "<h1>…</h1>",
    "heroImage": "https://…",
    "keywords": ["…"],
    "status": "published",
    "publishAt": "2026-07-03T09:00:00.000Z",
    "publishedAt": "2026-07-03T09:00:00.000Z"
  }
}
```

## Public web endpoints

- `/llms.txt` - AI discovery file — what RankOrg is, its pages, tools, and this API.
- `/robots.txt` - Crawler directives, including AI crawler access.
- `/sitemap.xml` - Full URL index for search engines.
- `/index.md` - Markdown twin of the homepage for AI answer engines.

## Related docs

- Developer docs: https://rankorg.com/docs
- MCP for AI agents: https://rankorg.com/docs/mcp


# RankOrg - MCP for AI Agents

Connect Claude, ChatGPT, Codex, Cursor, Grok, and other MCP-capable agents to research keywords, inspect schedules, edit drafts, generate articles, and publish content.

## MCP endpoint

- MCP server: `https://rankorg.com/api/mcp`
- Transport: Streamable HTTP (MCP). SSE disabled.
- Auth: personal access token, supplied either as `Authorization: Bearer rankorg_...` or as a `?token=rankorg_...` query param on the URL.
- Token management: create and revoke tokens at https://rankorg.com/settings.
- Tools: read tools inspect your account; write tools edit content, schedules, or publishing state.

## Agent setup

### Claude

```text
https://rankorg.com/api/mcp?token=YOUR_TOKEN
```

```text
Use the RankOrg MCP server. First get my site context, then list my scheduled articles for the next 7 days as a concise list with title, publish date, status, slug, and article ID.
```

### ChatGPT

```text
https://rankorg.com/api/mcp?token=YOUR_TOKEN
```

```text
Use the RankOrg MCP server. First get my site context, then list my scheduled articles for the next 7 days as a concise list with title, publish date, status, slug, and article ID.
```

### Codex

```bash
echo 'export RANKORG_API_KEY="rankorg_your_token_here"' >> ~/.zshrc
source ~/.zshrc
```

```toml
[mcp_servers.rankorg]
url = "https://rankorg.com/api/mcp"
bearer_token_env_var = "RANKORG_API_KEY"
```

### Cursor

```json
{
  "mcpServers": {
    "rankorg": {
      "url": "https://rankorg.com/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}
```

### Grok

```text
https://rankorg.com/api/mcp?token=YOUR_TOKEN
```

If your client supports headers, use:

```text
Authorization: Bearer YOUR_TOKEN
```

## Tools

### `getSiteContext` (read)

Returns the user's site (domains) and business/niche profile. Agents should call this first to ground everything else.

- Parameters: none

Example prompt: "What business is my RankOrg account set up for?"

### `listContent` (read)

Lists the user's articles. Use filter='today' to see what publishes today, 'scheduled' for upcoming, 'published' for live posts, or 'all'.

- Parameters:
  - `filter` ("today" | "scheduled" | "published" | "all") - optional: Which slice of content to return. Defaults to 'all'.

Example prompt: "What content is scheduled to publish today?"

### `getContent` (read)

Returns a single article's full HTML content, title, meta description, status and schedule by id. Call before editing so you have the current draft.

- Parameters:
  - `id` (string) - required: The article id.

Example prompt: "Show me the draft titled '…' so I can review it."

### `getSearchPerformance` (read)

Returns the site's Google Search Console performance — clicks, impressions, CTR, average position, top pages, top queries, and a daily trend. Reports a clear next step when Search Console isn't connected yet.

- Parameters: none

Example prompt: "How is my content performing in Google search?"

### `getTopicalMap` (read)

Returns the topical map — clusters → topics → subtopics → keywords with demand (volume/CPC), keyword difficulty, rankability scores, and which keywords already have scheduled or published articles.

- Parameters: none

Example prompt: "What keywords are we targeting, and which are still open?"

### `updateContent` (write)

Edits an article's title, HTML content, and meta description. The title cannot change once an article is published (SEO stability).

- Parameters:
  - `id` (string) - required: The article id.
  - `title` (string) - required: New title.
  - `content` (string) - required: Full article body as HTML.
  - `metaDescription` (string) - required: New meta description.

Example prompt: "Tighten the intro of that draft and update the meta description."

### `researchKeywords` (write)

Generates a keyword profile — head keywords plus specific long-tail search phrases — from the user's business profile, and saves it to their account.

- Parameters: none

Example prompt: "Research keywords for my business."

### `generateArticle` (write)

Generates the next SEO article, picking the highest-priority keyword from the topical map and scheduling it into the next open publish slot.

- Parameters: none

Example prompt: "Write and schedule my next article."

### `publishContent` (write)

Publishes a scheduled article live immediately. This is public and irreversible-ish — only call after the user explicitly confirms.

- Parameters:
  - `id` (string) - required: The article id to publish now.

Example prompt: "Publish that article now."

### `rescheduleContent` (write)

Moves a planned article to a different future date, or skips it to free the day. Only un-generated planned days (DRAFT pre-plan rows) can be moved or skipped; moving onto another planned day swaps the two.

- Parameters:
  - `id` (string) - required: The planned article id.
  - `action` ("move" | "skip") - required: Move to a new date, or skip the day.
  - `newDate` (string) - optional: Required for 'move': new publish date (YYYY-MM-DD), must be in the future.

Example prompt: "Move tomorrow's post to Friday."

### `mergeContent` (write)

Consolidates duplicate or overlapping published posts. The primary survives; each merged post becomes a permanent 308 redirect to it, so the old URLs keep passing SEO equity to the survivor.

- Parameters:
  - `primaryId` (string) - required: The post to keep (must be published).
  - `mergedIds` (string[]) - required: Posts to merge into the primary (become redirects).

Example prompt: "These two posts overlap — keep the stronger one and redirect the other."

### `unmergeContent` (write)

Reverses a merge: restores a merged post to published so its URL serves content again instead of redirecting.

- Parameters:
  - `id` (string) - required: The merged article id to restore.

Example prompt: "Undo that merge — bring the old post back."

## Related docs

- Developer docs: https://rankorg.com/docs
- Publishing integrations: https://rankorg.com/docs/integration


## Internal routes

RankOrg's other `/api/*` routes (authentication, billing webhooks, cron publishers, tenant resolution) are internal infrastructure secured by their own secrets. Integrate via the MCP endpoint above.