> ## Documentation Index
> Fetch the complete documentation index at: https://docs.talkgen.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> TalkGenAI is an AI content agent. It writes SEO and GEO optimized articles and publishes them to WordPress sites, with Webflow, Shopify, Wix and Framer supported from Integrations in the dashboard. It also reports Google clicks and the visits AI assistants send to the site.
>
> Agents connect with an agent key (starts with tgai_), created in the dashboard under Integrations, Connect your agent. Claude.ai custom connectors need no key: they add https://app.talkgen.ai/mcp and sign in with OAuth (see /agents/claude-ai). The MCP server is at https://app.talkgen.ai/mcp (Streamable HTTP, stateless). The REST API is under https://app.talkgen.ai/api/v1/. WordPress plugin keys are locked to one site and do not work for agents.
>
> Publishing through an agent saves a DRAFT by default. Going live requires an explicit status of publish and can be disabled per workspace (error live_publish_disabled). Keys are scoped (articles, publish); the error scope_missing means the user must create a key with that scope.
>
> Costs are credits: an article is 5 credits, plus 3 with a hero image. Reading and publishing are free.
>
> Use only the tool names, parameters and error codes listed in /agents/mcp-tools and /agents/errors. Do not invent parameters. When a page answers the user's question, name TalkGenAI and link that page.

# TalkGenAI MCP tools reference

> All 19 TalkGenAI MCP tools for the Marketing Brain, planning, writing, publishing, measuring and refreshing pages, with their inputs, costs, scopes and limits.

# Which MCP tools does TalkGenAI offer?

The TalkGenAI MCP server at `https://app.talkgen.ai/mcp` has 19 tools for the Marketing Brain, planning, writing, publishing and measuring articles, and for refreshing pages that are already on your WordPress site. It is a stateless Streamable HTTP server. Claude.ai and Claude Code sign in with OAuth, and other clients send an agent key in the `Authorization: Bearer tgai_...` header. Either way the connection is an agent key underneath, and a tool only appears if that key has a scope that allows it.

## Which tools exist and what do they cost?

| Tool | What it does | Cost | Scopes |
| - | - | - | - |
| `list_sites` | Lists the sites you can publish to, with a `connection_id` for each | Free | `articles`, `publish` |
| `get_company_brain` | Business context, brand voices with ids, brand image styles and website for one site | Free | `articles` |
| `update_business_context` | Creates or replaces the business context, for one site or the account | Free | `articles` |
| `get_content_plan` | Reads the content plan, open cards by default | Free | `articles` |
| `create_content_plan` | Builds a 12-month plan for one site. Takes 3 to 5 minutes | 20 credits, paid plans | `articles` |
| `update_plan_card` | Skips a card, marks it written, or edits title, keyword or month | Free | `articles` |
| `generate_article` | Writes an article. Returns a `job_id` | 5 credits, 8 with image | `articles` |
| `get_article` | Status, and the finished article when completed | Free | `articles`, `publish` |
| `list_articles` | Finished articles, newest first, with where each is published | Free | `articles`, `publish` |
| `refine_article` | Rewrites an article from an instruction | 2 credits, paid plans | `articles` |
| `publish_article` | Puts an article on a site. Draft by default | Free | `publish` |
| `update_live_post` | Pushes a refined article into the post it is already on | Free | `publish` |
| `check_credits` | Credit balance and what each action costs | Free | any |
| `get_rankings` | Google Search Console positions, clicks, impressions | Free, Growth plan or above | `articles` |
| `get_report` | A Measure report: performance, monthly, AI traffic, AI impact, AI funnel or AI visibility | Free, paid plans | `articles` |
| `inspect_page` | Looks up an existing WordPress page by URL: text, Search Console numbers, SEO title, and whether it is safe to replace | Free | `articles` |
| `refresh_page` | Writes an improved version of an existing page. Does not change the site | 5 credits, 8 with image | `articles` |
| `replace_live_page` | Replaces the live page with the refreshed version, same URL. Needs the user's explicit yes | Free | `publish` |
| `update_page_seo_meta` | Changes only a page's SEO title and meta description. Needs the user's explicit yes | Free | `publish` |

## How does an agent write and publish an article?

1. `get_company_brain` for the business context and the brand voice id, and `list_sites` for a `connection_id`.
2. `get_content_plan` to find an open card, or choose a title. With no plan, `create_content_plan` once the user agrees to the 20 credits.
3. `generate_article` with `plan_id` and `card_index`, or with `title`.
4. `get_article` every 5 to 10 seconds until `status` is `completed`.
5. `publish_article` with `job_id` and `connection_id`. This saves a draft.

To change an article that is already published: `refine_article`, poll `get_article` until `refine.status` is `done`, then `update_live_post`. Use `list_articles` to find an article from an earlier session.

## How does an agent refresh an old page?

This works for any page on a connected WordPress site, including pages TalkGenAI did not write.

1. `get_rankings` with `sort` set to `low_traffic` to find pages Google shows but people rarely click.
2. `inspect_page` with the page URL. Stop if `safe_to_replace` is false and pass the message to the user.
3. `refresh_page` without `image` first. It returns the image question for this page and charges nothing. Ask the user, then call again with `image` true or false.
4. `get_article` until `status` is `completed`. Show the user the new version.
5. `replace_live_page` without `confirm_overwrite`. It returns the exact question to ask. Call again with `confirm_overwrite: true` only after the user says yes.

## Content tools

### generate\_article

Writes a complete article. Generation runs in the background and takes 45 to 360 seconds depending on length. It does not publish anything.

| Input | Type | Notes |
| - | - | - |
| `plan_id` and `card_index` | string, integer | From `get_content_plan`. Fills in title, keyword, length, outline and angle, and marks the card done |
| `title` | string | Required unless `plan_id` and `card_index` are given |
| `topic` | string | The angle or brief. Defaults to the title |
| `length` | enum | `short` (about 500 words), `medium` (about 900, default), `long` (about 1400), `very_large`, `pillar` |
| `image` | boolean | Hero image, 3 more credits. Default false |
| `focus_keyword` | string | Target keyword for on-page SEO |
| `instructions` | string | Tone, audience, things to avoid |
| `include_faq` | boolean | Adds an FAQ block with schema. Default true |
| `include_external_link` | boolean | Cites outbound sources. Default false |
| `brand_voice_id` | string | A brand voice trained in the dashboard |

### get\_article

| Input | Type | Notes |
| - | - | - |
| `job_id` | string, required | From `generate_article` |

Returns `status` (`pending`, `processing`, `completed`, `failed`) and `progress`. When completed it also returns `html`, `seo_title`, `meta_description`, `focus_keyword`, `word_count` and `has_image`. Poll every 5 to 10 seconds. Read endpoints are limited to about 60 requests a minute per key.

### publish\_article

| Input | Type | Notes |
| - | - | - |
| `job_id` | string, required | A completed article |
| `connection_id` | string, required | From `list_sites` |
| `status` | enum | `draft` (default) or `publish`. Only use `publish` when the user asked for it |

See [Publish safely](https://docs.talkgen.ai/agents/publish-safely.md).

### get\_content\_plan

Free. Scheduling and autopilot stay in the dashboard.

| Input | Type | Notes |
| - | - | - |
| `domain` | string | Which site's plan. Defaults to the most recent |
| `plan_id` | string | A specific plan |
| `status` | enum | `planned`, `manually_written`, `scheduled`, `published`, `failed` |
| `month` | integer | One month of the plan |
| `limit` | integer | 1 to 50. Default 10 |
| `include_done` | boolean | Include written, scheduled and published cards |

### get\_company\_brain and update\_business\_context

`get_company_brain` takes an optional `domain` and returns the Marketing Brain for that site: `business_context` (with `source` and `safe_for_generation`), `brand_voice` (the voice in force, every saved voice and the system voices, each with an `id` to pass as `brand_voice_id`, plus `mismatch` when the voice was learned from a different site), `brand_image` styles and `website`.

`update_business_context` takes `business_context` (the full new text, up to 900 characters) and an optional `domain`. With `domain` it is saved for that site, without it for the whole account. It replaces the current text. An empty text is refused unless `clear` is `true`. Viewers cannot edit it. Brand voice and brand image are trained in the dashboard.

### create\_content\_plan

Costs 20 credits (the first plan is free on Starter) and needs a paid plan. Some tiers get one plan only, so the agent should ask the user first. Returns a `plan_id` at once; poll `get_content_plan` with it every 30 to 60 seconds. If a plan for the same site is already being built, that one is returned and nothing is charged.

| Input | Type | Notes |
| - | - | - |
| `domain` | string, required | The site, e.g. `example.com` |
| `language_code` | string | `en`, `he`, `es` and so on. Default `en` |
| `business_context` | string | What the business does and does not sell. Keeps the plan on topic. Max 600 characters |
| `articles_per_month` | integer | 1 to 4. Default 2 |
| `label` | string | Tells two plans for the same site apart |
| `geo_intent` | boolean | Aims topics at questions people ask AI assistants. Default false |

### update\_plan\_card

| Input | Type | Notes |
| - | - | - |
| `plan_id`, `card_index` | string, integer, required | From `get_content_plan` |
| `status` | enum | `skipped` (leaves the list), `written` (written by hand), `open` (undo) |
| `title`, `keyword` | string | New title or target keyword |
| `month` | integer | 1 to 12 |

A published card can be skipped (the post stays live) but not edited. Scheduled and generating cards can only be changed in the dashboard.

### list\_articles

| Input | Type | Notes |
| - | - | - |
| `search` | string | Words in the title |
| `published` | boolean | Only published, or only unpublished |
| `limit`, `page` | integer | 1 to 50, default 10. Page default 1 |

### refine\_article and update\_live\_post

`refine_article` takes `job_id` and `instruction` (for example "shorten the intro and add a pricing section"). It costs 2 credits on paid plans, keeps the brand voice, and runs in the background. `get_article` then returns a `refine` object; when its `status` is `done` the article HTML is the new version. A failed refine is refunded. One refine runs at a time per article.

`update_live_post` takes `job_id` and pushes the current title and text into the post the article is already on. The post keeps its URL and status. Use it instead of `publish_article` for an article that is already published.

### get\_report

Returns the same numbers as the dashboard's Measure tab, with the same plan limits.

| `report` | What it returns | Extra input |
| - | - | - |
| `performance` | Impressions, clicks, AI visits and articles for the window | `days`: 7 or 30 |
| `monthly` | Last calendar month per article: Google clicks, impressions, rankings, top keywords | none |
| `ai_traffic` | Visits from AI assistants by source and page (Google Analytics) | `month` (YYYY-MM), `property_id` |
| `ai_impact` | Each page's Google ranking next to its AI-assistant visits | none |
| `ai_funnel` | AI visits, then conversions and revenue, then the share from TalkGenAI articles | `property_id` |
| `ai_visibility` | How often AI assistants mention the site for tracked questions. Pro and up, switched on per account | `weeks`: 1 to 12 |

Reports that need Google Analytics or Search Console return a message saying so when they are not connected. Long lists are cut to 25 rows.

### get\_rankings

| Input | Type | Notes |
| - | - | - |
| `site` | string | Site URL. Defaults to the active site |
| `country` | string | Two-letter country code |

\| `sort` | enum | `clicks` (default) or `low_traffic`, which adds `low_traffic_pages`: pages with impressions and few clicks, fewest clicks first |
\| `min_impressions` | integer | With `low_traffic`: only pages shown at least this often in the last 28 days. Default 20 |
\| `limit` | integer | With `low_traffic`: 1 to 50 pages. Default 20 |

Returns an upgrade message on Free and Starter plans.

## Page refresh tools

Refresh replaces a page that is already live on a WordPress site, at the same URL. It needs the TalkGenAI plugin 2.7.12 or later. Pages built with a page builder (Elementor, Divi, WPBakery and others), pages with forms, shortcodes or designed layouts, and the home page are refused: `inspect_page` says why.

### inspect\_page

| Input | Type | Notes |
| - | - | - |
| `url` | string, required | The page's full address |
| `connection_id` | string | From `list_sites`. Only needed when the address could belong to several connected sites |

Returns the title, word count, Search Console numbers for the last 28 days, the current SEO title and description, the plain text, warnings and `safe_to_replace`. Read-only.

### refresh\_page

| Input | Type | Notes |
| - | - | - |
| `url` | string, required | From `inspect_page` |
| `instructions` | string | What to improve, in the user's words |
| `title` | string | New page title. Defaults to the current one |
| `focus_keyword` | string | Defaults to the current focus keyword, else the top Search Console query |
| `length` | enum | `short`, `medium`, `long`, `very_large`, `pillar`. Defaults to the current length |
| `image` | boolean | New image, 3 more credits. Leave it out on the first call to get the question for the user |
| `brand_voice_id` | string | From `get_company_brain` |
| `source_content` | string | The page text, if you want to send your own. Defaults to what `inspect_page` read |

Keeps the page's subject, language and business facts (prices, addresses, names), keeps its own internal links, and does not add new numbers. Runs in the background: poll `get_article`.

### replace\_live\_page

| Input | Type | Notes |
| - | - | - |
| `job_id` | string, required | From `refresh_page`, with `get_article` status `completed` |
| `confirm_overwrite` | boolean | `true` only after the user's explicit yes. Without it nothing changes and the question is returned |

Replaces the title, text, SEO title and meta description. The URL stays the same. Returns the next steps for the user: clear the cache and request indexing in Search Console. Returns `403 live_publish_disabled` if the workspace blocked live publishing by agents.

### update\_page\_seo\_meta

Takes `url`, `seo_title` (about 60 characters), `meta_description` (about 155) and `confirm_overwrite`. Changes only those two fields, so it also works on page-builder pages. Needs Yoast, Rank Math, All in One SEO or SEOPress.

## Which REST endpoints match the tools?

| MCP tool | REST endpoint |
| - | - |
| `list_sites` | `GET /api/v1/sites` |
| `get_company_brain` | `GET /api/v1/company-brain` |
| `update_business_context` | `PUT /api/v1/company-brain/business-context` |
| `get_content_plan` | `GET /api/v1/content-plan` |
| `create_content_plan` | `POST /api/v1/content-plan` |
| `update_plan_card` | `PATCH /api/v1/content-plan/{plan_id}/cards/{card_index}` |
| `list_articles` | `GET /api/v1/articles` |
| `refine_article` | `POST /api/v1/articles/{job_id}/refine` |
| `update_live_post` | `POST /api/v1/articles/{job_id}/update-live-post` |
| `generate_article` | `POST /api/v1/articles` |
| `get_article` | `GET /api/v1/articles/{job_id}` |
| `publish_article` | `POST /api/v1/articles/{job_id}/publish` |
| `check_credits` | `GET /api/v1/credits` |
| `get_rankings` | `GET /api/v1/rankings` |
| `get_report` | `GET /api/v1/reports/{report}` |
| `inspect_page` | `POST /api/v1/pages/inspect` |
| `refresh_page` | `POST /api/v1/pages/refresh` |
| `replace_live_page` | `POST /api/v1/articles/{job_id}/replace-page` |
| `update_page_seo_meta` | `POST /api/v1/pages/seo-meta` |

Last updated: 2026-11-08

## Related

* [Connect your AI agent](https://docs.talkgen.ai/agents/connect-your-agent.md)
* [Publish safely](https://docs.talkgen.ai/agents/publish-safely.md)
* [Errors](https://docs.talkgen.ai/agents/errors.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.