Call the MCP tools directly

You don't need an assistant to use the MCP server. Every tool is a plain JSON-RPC 2.0 call over HTTP POST to https://searchblueprint.io/api/mcp, so a script or an automation tool can write and publish articles the same way Claude does. This page is the reference for those calls. To connect an assistant instead, see Connect the MCP server.

Before you begin

The workspace tools need a content API key. Connect the MCP server covers where to create one and how to send it. Without a key, tools/list returns only the three public tools.

List the tools a key can see

curl -X POST https://searchblueprint.io/api/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sbk_YOUR_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

With a valid key you get ten tools. With no key, or a revoked one, you get three.

Write an article and publish it

To write and publish an article:

Start it with generate_article:

curl -X POST https://searchblueprint.io/api/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sbk_YOUR_KEY" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"generate_article","arguments":{"keyword":"bridal gown alterations singapore","brief":"Aim at brides 6 to 8 weeks out. Mention turnaround times."}}}'

Keep the job_id from the result, {"job":{"job_id":"...","status":"queued",...}}, and poll it:

-d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"get_article_status","arguments":{"jobId":"JOB_ID"}}}'

Once article_id is set, get an integrationId from list_integrations and publish:

-d '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"publish_article","arguments":{"articleId":"ARTICLE_ID","integrationId":"INTEGRATION_ID"}}}'

How long does an article take?

Minutes, not seconds. generate_article is long-running: the article-jobs cron drafts and revises it across several sweeps, so the tool returns a job and you poll get_article_status. The status moves through queued, drafting, revising, then done or failed. queue_ahead tells you how many jobs run first. When status is done, article_id is set and list_articles or GET /api/v1/articles/{id} returns the full text.

When is an article actually published?

publish_article defaults to the connection's own draft-vs-live setting, the one on the Publishing page. Pass status: "publish" or "draft" to override it for one call.

The response's state reads published only after the product fetched the public URL and found the article on it. A fresh publish usually comes back checking, because hosts deploy asynchronously and the verifier runs every few minutes behind a short grace window. A draft comes back unverified, since it has no public URL to check. sent: true means the CMS accepted the write and nothing more. It's the same rule the Publishing tab applies: a successful write isn't a successful publish.

Read the latest audit

For a workspace key, pass the project. A project-scoped key can leave projectId out.

-d '{"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"get_latest_audit","arguments":{"projectId":"PROJECT_ID"}}}'

Arguments and results

Argument names are camelCase (projectId, articleId, integrationId), and the snake_case spelling of each works too. That's deliberate: everything the tools return is snake_case, so a project_id read out of one response can go straight into the next call.
Results come back as one JSON text block in result.content[0].text.

Troubleshooting

A call comes back with isError: true. That's a refusal you can act on, returned as a result with an error message and an HTTP-style status. The common ones:

Status	Reason
`402`	The workspace is out of article credits
`409`	The project already has an article for that keyword; the existing article id comes back with it
`422`	The publish gate blocked the article: unfilled placeholders, refusal text or two H1s

An id outside the key's scope is refused the same way.

A call returns a JSON-RPC error instead. -32001 means you called a workspace tool with no key. -32601 means the tool name or method is unknown. Rate limited means you passed 30 calls a minute per IP on the public tools, or 60 a minute per key on the workspace tools.

Note that an identical rank_check or ai_presence call within 12 hours reuses the first call's answer instead of making a new live lookup.

For what shipped recently, see the changelog.