MCP and API

Connect an AI assistant (MCP)

Give Claude Code, Cursor, Windsurf, VS Code or any MCP client direct access to your SEOForge articles, content plan, rankings and Google data.

SEOForge runs a Model Context Protocol server. Once your AI assistant is connected, you can ask it questions about your site in plain language, and it answers with your real SEOForge, Search Console and Analytics data instead of guessing.

text

https://www.seoforge.ai/api/mcp

Use the www. address. The bare seoforge.ai domain redirects, and some MCP clients don't follow redirects.

Connect your assistant#

Create an API key
In SEOForge, open Settings → API & MCP. Give the key a name (for example "Claude Code"), choose which projects it can see, choose Read only or Read & write, then click Create key.
Copy the key straight away. It starts with sf_live_ and is shown only once. See API keys and limits for what each option does.
Settings → API & MCP, with the Create a key row filled in
Add SEOForge to your client
Run this in your terminal, replacing YOUR_API_KEY:
bash
claude mcp add --transport http --scope user seoforge https://www.seoforge.ai/api/mcp --header "Authorization: Bearer YOUR_API_KEY"
--scope user makes SEOForge available in every folder. Without it, Claude Code only loads the server in the folder you ran the command from. Claude Code stores the key in plain text in ~/.claude.json, so revoke it in SEOForge if that file is ever shared.
Add this to your client's MCP configuration file (for Cursor, that's ~/.cursor/mcp.json):
json
{ "mcpServers": { "seoforge": { "type": "http", "url": "https://www.seoforge.ai/api/mcp", "headers": { "Authorization": "Bearer YOUR_API_KEY" } } } }
Clients name these fields slightly differently. If yours doesn't connect, check its docs for how it configures a remote HTTP server with a custom header.
Check the connection
Restart your client. In Claude Code, run claude mcp list and look for seoforge with a connected status. Then ask a question, such as "List my SEOForge projects."

What you can ask#

Every question below works with a read-only key:

Which of our published articles get the most Google clicks?
Which articles get impressions but almost no clicks?
How have our Google clicks changed over the last 90 days?
Which tracked keywords are stuck on page 2?
Which search queries bring impressions but no article yet?
What should we write next based on our content plan?

With a Read & write key, the assistant can also add items to your content plan, start article generation, edit article drafts and change tracked keywords. No key can publish to your live site, and article edits keep the previous version so you can restore it.

Ready-made reports#

The server ships two prompts that run a full report in one step. In Claude Code, type:

/mcp__seoforge__article_performance: how your published articles perform in Google.
/mcp__seoforge__content_opportunities: queries and keywords worth writing about next.

Both take an optional project name.

Choose which tools load#

Your assistant sees the default toolsets unless you ask for others. Add ?toolsets= to the server URL to load more:

text

https://www.seoforge.ai/api/mcp?toolsets=core,content,insights,keywords,serp

Use ?toolsets=all to load everything. Fewer tools keep your assistant's context small, so only add the sets you use.

Toolset	What it covers	Default
`core`	Projects and settings	Yes
`content`	Articles, content plan and writing actions	Yes
`search_console`	Google Search Console data	Yes
`analytics`	Google Analytics data	Yes
`insights`	Analyses that combine data and recommend actions	Yes
`monitoring`	Alerts, annotations, rank changes, reports	No
`indexing`	Google indexing, sitemaps and Core Web Vitals	No
`serp`	Search results from Google, Bing, YouTube and more	No
`keywords`	Keyword metrics, ideas and trends	No
`domains`	Domain and competitor metrics	No
`backlinks`	Backlink data	No
`audit`	Page analysis and site audits	No
`local`	Local search	No

The project, article, content plan, rank tracking, Search Console and Analytics tools are always loaded, whatever you pass. The tool reference lists every tool in each set.

Limits#

60 requests per minute per key. Every message your client sends counts, including the handshake and the tool list. Going over returns 429 rate_limited; wait a minute and retry.
Paid SEO data (search results, keyword, domain and backlink data) is free during the beta, up to a daily limit of about 5,000 credits per account. It resets at 00:00 UTC. Each response shows what it would have cost under meta.cost.
Cached results. Search data is reused for up to 24 hours, keyword data for 30 days, and domain and backlink data for 7 days. Pass max_age (seconds) to accept older data, or fresh: true to fetch new data.
Article generation counts toward your plan's monthly article limit, and adding tracked keywords counts toward your keyword limit.

Troubleshooting#

Error	What it means	What to do
`401 missing_api_key`	No key was sent, or it doesn't start with `sf_live_`	Check the `Authorization: Bearer` header in your client config
`401 invalid_api_key`	The key was revoked or mistyped	Create a new key
`402 subscription_required`	The account has no active subscription or trial	Reactivate your plan in Settings → Billing & Plan
`402 project_unpaid`	That project isn't on a paid plan	Upgrade the project, or use another one
`403 insufficient_scope`	A write tool was called with a read-only key	Create a Read & write key
`404 project_not_found`	The key can't see that project	Use a key set to All my projects, or ask the project owner to invite you
`429 rate_limited`	More than 60 requests in a minute	Wait for the `Retry-After` time
`429 daily_data_limit`	Today's paid data limit is used up	Wait until 00:00 UTC, or rely on cached data

Tool referenceEvery tool, grouped by toolset.REST APICall the same data from your own code.