SearchBlueprint exposes an MCP (Model Context Protocol) server at /api/mcp, so an assistant that speaks MCP (Claude Desktop, Claude Code, Cursor, any MCP client with remote-server support) can call the product's tools mid-conversation. Ask "where does odeliabridal.com rank for wedding gown rental in Singapore" and it answers with a live lookup. Hand it a content API key and it can also ask "write an article on bridal alterations for the Odelia project, then publish it as a draft to WordPress" and drive the product end to end.
The server speaks JSON-RPC 2.0 over plain HTTP POST. No SDK, no session, no cookies.
Two tiers of tools
Public tools need no key. They compute over what you send them and never touch a workspace.
| Tool | Returns |
|---|---|
rank_check | A domain's live Google organic position for a keyword (0 = not in the top 100) |
ai_presence | Whether Google AI Overview and AI Mode show or cite a domain for a keyword |
page_meta | A URL's title, meta description, H1 and headings |
Workspace tools appear in tools/list only when the request carries a valid content API key, and every one of them is scoped to what that key can see. A key minted for one project reaches exactly that project; a workspace key reaches every project in the workspace; nothing reaches another workspace.
| Tool | Does |
|---|---|
list_projects | The projects (websites) the key can see, each with the grade of its latest finished audit |
list_articles | Generated articles, newest first. Same fields as GET /api/v1/articles |
generate_article | Starts writing an article for a keyword (optional title and brief). Spends article credits. Returns a job |
get_article_status | Where that job stands: queued, drafting, revising, done or failed, plus queue position and the article_id once written |
list_integrations | A project's publishing connections with their id, health and draft-vs-live default |
publish_article | Publishes an article through one connection. Reports the recorded publish event and its verification state |
get_latest_audit | The latest finished audit: score, grade, verdict, check totals, per-category scores and top recommendations |
rank_history was removed on 2026-09-17 and has not come back; the keywords you track and their history are on each website's Rankings page. check_rank still checks one keyword live.
generate_article returns a job you poll, and publish_article reports published only once the article is reachable at its public URL. Call the MCP tools directly has the full request flow.
Get a key
Workspace tools use the same content API keys as the REST API. In the product, open a project, go to Publishing, and create a content API key under the pull API section; the plaintext sbk_... is shown once and stored only as a hash, so copy it then. Send it on every request as Authorization: Bearer sbk_... or as an X-API-Key header. A revoked or unknown key is treated exactly like no key: the public tools still work and the workspace tools are not listed.
Connect your assistant
Claude Code, from a terminal:
claude mcp add --transport http searchblueprint https://searchblueprint.io/api/mcp \
--header "Authorization: Bearer sbk_YOUR_KEY"
Leave the --header off for the public tools only.
Claude Desktop, in claude_desktop_config.json (needs an MCP client that supports remote HTTP servers; older builds route remote servers through mcp-remote):
{
"mcpServers": {
"searchblueprint": {
"command": "npx",
"args": [
"mcp-remote",
"https://searchblueprint.io/api/mcp",
"--header",
"Authorization: Bearer sbk_YOUR_KEY"
]
}
}
}
Then ask a question that needs one of the tools. The assistant discovers them on connection. For a set of prompts written against these tools, with a paste-first brief and a cadence for each, see the Claude SEO playbook.
Call it directly
The server works without an assistant too. Call the MCP tools directly has the curl requests for every step, the argument conventions, and the refusal codes.
Limits and usage
- Public tools: 30 calls per minute per IP address. Workspace tools: 60 calls per minute per API key, counted separately. Past either, the call returns a JSON-RPC error with the message
Rate limited. generate_articlespends article credits exactly as the product does, and refuses with402when the workspace is out. It also refuses a keyword the project already has an article for (409, with the existing article id) so an assistant cannot write the product's own cannibalising twin.publish_articleruns the publish gate first. An article with unfilled placeholders, refusal text or two H1s is refused with422and the specific issue, the same as clicking Publish.- Nothing is cached between calls, which means two identical
rank_checkcalls a minute apart both pay for a live lookup. - The endpoint is public by design; the key is the only thing that opens workspace data, so treat it like a password.
If something isn't working
The assistant says the server won't connect. Check the URL is /api/mcp exactly, and that your client supports remote (HTTP) MCP servers. Some support only local stdio servers; mcp-remote bridges those.
Only three tools show up. The key was not sent, or it was revoked. Test with the tools/list curl above: with a valid key you get ten tools.
generate_article answered but nothing arrives. Poll get_article_status; queue_ahead tells you how many jobs run first, and error carries the reason if it failed.
publish_article says sent: true but state is checking or not_live. The write worked; the page is not yet reachable at its public URL. checking resolves itself within minutes. not_live means the host answered 404 past the grace window, which is usually a permalink or theme mismatch to fix on the site.