Manual
Product site My Page

REST API and MCP Integration

Last updated · Published · Sorabun Editorial Team

Turn WordPress into an MCP server so Claude and Cursor can create, read, edit and schedule articles, read rankings and goals, the site profile and audit and AI visibility results, queue SNS posts and read inquiries. Each key has its own permissions, expiry and rate limits. Connect from claude.ai and ChatGPT without a key (OAuth). REST API and Abilities API too

WordPress becomes an MCP server

With the Pro or Cloud edition installed (including the free trial), this WordPress site works as an MCP server. Just register the URL and a key with an MCP client such as Claude Code, Claude Desktop, or Cursor, and you can ask things like "write an article with the keyword XX" or "read the article you made last week and summarize it." You don't need any extra software or a Node.js wrapper.

There's a single MCP endpoint (using Streamable HTTP; it accepts JSON-RPC over POST).

https://your-site/wp-json/sorabun/v1/mcp

Clients with no place to paste a key, such as the connectors in claude.ai and ChatGPT, can connect with just this URL, without creating a key (Connect from claude.ai and ChatGPT without a key (OAuth)).

Create a key

To use MCP clients or the REST API, first create a key.

  1. Open Sorabun > Settings > REST API / MCP Integration
  2. Under Create a new key, enter a name (where you'll use it, for example "Claude Code on my PC"), choose the article permission, any other permissions (editing existing posts, security status, numbers, SNS posts, inquiries), and an expiry
  3. Click Create key. The key (a string starting with sbk_) appears at the top of the screen
The key is shown only once, right after you create it

Sorabun doesn't store the key itself, only a value for checking it (a hash mixed with your site's secret). Once you reload the screen, you can't see it again. Copy it into your MCP client or 1Password right away. If you lose it, revoke it in the list and create a new one.

Use a separate key for each place you use it. If one leaks, you can revoke just that key. The list shows each key's name, its prefix (such as sbk_1a2b3c4d…, so you can tell which config file holds which key), permissions, expiry, last used date, and when and by whom it was created.

Permissions

Choose what each key can do. Article permissions come in three levels, and each level can also do everything the levels below it can.

PermissionWhat it allows
Read published postsList and read published posts, and read site info (list_posts / get_post / site_info). Only what visitors can see: no drafts, scheduled, private or password-protected posts, and only the free part of paid or LINE-only posts
Create draftsAll of the above, plus creating, rewriting and generating articles from URLs (as drafts), checking job progress (create_article / rewrite_article / article_from_url / get_job / list_jobs), and editing drafts (update_post). It sees, and can edit, only the jobs and drafts made with this key
PublishAll of the above, plus publishing (post_status set to publish). It can read every post and job (the same as the key in earlier versions)

Besides the article permission, you can add each of these permissions to a key. None of them is on by default.

PermissionWhat it allows
Edit existing posts and the site profile, and set publish timesEdit published, scheduled and private posts, and drafts not made with this key (update_post), set or cancel when a post is published (schedule_post / unschedule_post), and update the site profile (update_site_profile). Add it together with Publish
Read the security statussecurity_status (see below)
Read rankings, goals and other numbersRank tracking results, goals (KPIs) and progress, a Search Console summary, and article ideas (list_rankings / list_kpis / search_console_summary / list_article_ideas / refresh_article_ideas). The site profile, the technical audit, broken links, AI recommendation and AI citation results, and new and almost-ranking Search Console queries (get_site_profile / get_technical_audit / list_broken_links / get_ai_recommendations / list_ai_citations / search_console_queries). Goals can include paid-post sales and inquiry counts
Queue SNS postsRead, add and cancel queued posts on X (list_social_posts / schedule_social_post / cancel_social_post). Only administrators can add it
Read inquiriesThe list of inquiries and each one in full (list_inquiries / get_inquiry), including visitors' names, email addresses and messages. Only administrators can add it

An MCP client only sees the tools its key may use. Calls the key isn't allowed to make are refused with HTTP 403.

Why SNS posts are a separate permission

A post on social media can't be taken back, reaches your followers right away, and goes out under your own account, not just your site. Someone you trust to publish articles isn't necessarily someone you want speaking on your social accounts (and the other way round). Making it a level above Publish would also hand article publishing to an AI you only want to handle social posts, so it's a separate permission. On top of that, SNS posts an AI adds wait for a person to approve them before they're sent, following your "SNS Auto-Posting" setting (whether drafts go straight into the queue; by default they don't).

A key that can create drafts can also ask for rewrites, but not of posts it can't read in full (paid posts, LINE-only posts, password-protected posts, other people's drafts, scheduled posts). Otherwise the rewrite would hand back content the key isn't allowed to read.

Expiry

Choose 30 days, 90 days, 1 year or no expiry. Expired keys are refused with 401. Starting 14 days before a key expires, Sorabun shows a notice at the top of its screens. Create a new key, switch over to it, and revoke the old one.

Rate limits

Each key can make up to 600 calls an hour, and create up to 50 articles a day (the calls that cost AI fees: from a keyword, from a URL, and rewrites). Beyond that, Sorabun returns HTTP 429 with Retry-After (seconds to wait). The daily count resets at midnight in your site's time zone.

600 calls an hour leaves room even when an AI makes 10 articles at once and checks each one's progress every 30 to 60 seconds; the limit is there to stop a runaway agent. 50 articles matches how many you can request at once with bulk creation. Developers can change both with the sorabun_api_key_limits filter.

Records

Calls made with a key are recorded under "API keys" in the Activity Log: the key's name, the tool or route called, the result, and the post or job ID. Sorabun never records the contents, such as keywords or extra instructions, the article text, or the key itself. Repeated reads of the same thing (such as progress checks every 30 seconds) are combined into one line per 10 minutes, with a count.

Refused calls (wrong key, expired, missing permission, over a limit) are recorded too, combined into one line per 10 minutes so brute-force attempts don't flood the log. Creating and revoking keys is also recorded, along with who did it.

Previous key (sites updated from an earlier version)

Earlier versions had a single key that could do everything. So that updating doesn't break your MCP settings or automations, that key was moved over as Previous key, with every article permission and no expiry. (If you had turned on "Let MCP read the security status" in the earlier version, it can read the security status too.) It was replaced with a hash during the move, so its value can no longer be shown the way earlier versions did.

Permissions added later (editing existing posts, numbers, SNS posts, inquiries) are not added to the previous key or to keys made in earlier versions. Updating never lets a key do something it couldn't do before. If you need them, create a new key with those permissions.

Create keys with only the permissions and expiry each place needs, switch your settings over, and then revoke the previous key.

Keys stop working if your site's secret changes

Keys are checked using the salts in wp-config.php (AUTH_KEY and AUTH_SALT). If they change, for example when you move the site or regenerate the salts, none of your keys can be checked any more and the list marks them as unusable. Create new keys. (API keys for other services need to be entered again for the same reason.)

Register with an MCP client

Claude Code

claude mcp add --transport http sorabun "https://your-site/wp-json/sorabun/v1/mcp" \
  --header "Authorization: Bearer <your key>"

Cursor / Windsurf / VS Code (for config files that let you specify a URL and headers)

{
  "mcpServers": {
    "sorabun": {
      "url": "https://your-site/wp-json/sorabun/v1/mcp",
      "headers": { "Authorization": "Bearer <your key>" }
    }
  }
}

Claude Desktop (for clients that can't add headers from the settings screen, go through mcp-remote. Requires Node.js 18 or later)

{
  "mcpServers": {
    "sorabun": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://your-site/wp-json/sorabun/v1/mcp",
               "--header", "Authorization: Bearer <your key>"]
    }
  }
}

Put your key where it says <your key>. Right after you create a key, the screen shows these examples with the real key filled in (it disappears when you reload).

If you'd rather not write the key into a config file, keep it in 1Password and pass it in only at startup (Using 1Password).

You can also ask for article drafts and checks from My Page in your browser, without an MCP client (View and manage sites from My Page (web)). My Page connects through your license, a separate mechanism that doesn't use these keys.

Which tools are available?

ToolWhat it doesPermission needed
create_articleCreate an article from a keyword. Returns a job_id right awayCreate drafts (Publish, to publish)
rewrite_articleRewrite an existing article. The result is saved as a draftCreate drafts
article_from_urlCreate an article from a URL or a YouTube videoCreate drafts (Publish, to publish)
get_job / list_jobsCheck generation progressCreate drafts
list_posts / get_postList articles and read their content (up to 20,000 characters)Read published posts
site_infoSite name, edition, generation defaults, and the number of articles Sorabun has createdRead published posts
update_postEdit a post's title, body and excerpt. The previous version is kept as a revisionCreate drafts (only drafts made with this key); Edit existing posts and the site profile, and set publish times (with Publish) for any other post
schedule_post / unschedule_postSet when a post is published (a scheduled post), or cancel the schedule and turn it back into a draftEdit existing posts and the site profile, and set publish times (with Publish)
security_statusRead the security status (see below)Read the security status
list_rankingsRank tracking results (each keyword's position, previous and best position, trend, whether an AI Overview cited you, and Search Console numbers)Read rankings, goals and other numbers
list_kpisEach goal's current value, progress, forecast for the end of the period, and statusRead rankings, goals and other numbers
search_console_summarySearch Console clicks, impressions, CTR and average position (the recent period and the one before)Read rankings, goals and other numbers
list_article_ideas / refresh_article_ideasRead or remake article ideas (remaking runs at most once a day)Read rankings, goals and other numbers
get_site_profileRead the site profile (the Site Diagnosis fields, key pages, competitors and the research log)Read rankings, goals and other numbers
update_site_profileUpdate the site profile (every change applies, or none does)Edit existing posts and the site profile, and set publish times (with Publish)
get_technical_auditThe last technical SEO audit and Core Web VitalsRead rankings, goals and other numbers
list_broken_linksBroken, redirected and questionable links the link checker foundRead rankings, goals and other numbers
get_ai_recommendationsThe last AI recommendation (LLMO) measurementRead rankings, goals and other numbers
list_ai_citationsAI citation check results by keywordRead rankings, goals and other numbers
search_console_queriesNew search queries, and queries close to page one, from Search ConsoleRead rankings, goals and other numbers
list_social_posts / schedule_social_post / cancel_social_postRead, add and cancel queued posts on XQueue SNS posts
list_inquiries / get_inquiryThe list of inquiries (subject and date) and one inquiry in fullRead inquiries

For keys without the Publish permission, get_post returns only what visitors can see. For paid and LINE-only posts that's the free part, and restricted is set to paywall or line.

The three tools that create articles let you choose how each article is made. Anything you leave out uses your settings.

ParameterWhat it setscreate_articlerewrite_articlearticle_from_url
lengthLength in characters (0 to 20000). 0 lets the AI decide from search intentSite default if omittedSite default if omittedAI fits the source if omitted
toneWriting style (desumasu / dearu / casual)YesYesYes
diagramsNumber of diagrams (0 to 5; -1 lets the AI add them only where they help)YesYesYes
eyecatchWhether to generate a featured imageYesKeeps the current imageYes
custom_promptExtra instructions for this article only (up to 2,000 characters)YesYesYes

The length is a target for the outline, so the finished article won't match it exactly. If you ask for "about 6,000 characters, polite style, no diagrams," the AI turns that into these parameters.

Article generation is asynchronous. The tool returns a job_id right away, and the article takes a few minutes to finish. The server tells the AI to "check get_job every 30 to 60 seconds" and "save as a draft rather than publish unless asked to," so it usually behaves this way without you saying anything.

What the AI in an MCP client can do

Over MCP, the AI can only use the tools above that the key's permissions allow. It can't change settings, delete articles, or manage keys. The only ways to take a post live are the post_status parameter of create_article and article_from_url, and schedule_post; all of them need the Publish permission (schedule_post also needs Edit existing posts and the site profile, and set publish times). The default is draft.

Editing and scheduling posts (update_post / schedule_post / unschedule_post)

update_post changes only what you pass: the title (title), the body (content, as HTML) and the excerpt (excerpt). The body is replaced as a whole, so the AI reads the post with get_post (format set to html) first.

  • The previous version is kept as a WordPress revision (revision_id), so you can restore it from "Revisions" in the admin. On sites that turn revisions off, published, scheduled and private posts are not edited (they couldn't be restored; drafts can still be edited)
  • A key can edit only the drafts (and pending posts) made with that key. Editing published, scheduled and private posts, and drafts made in the admin or with another key, needs the Edit existing posts and the site profile, and set publish times permission (added together with Publish). Keys from earlier versions, including the previous key, don't have it (they could never write their own text into existing posts)
  • For posts whose body is longer than 20,000 characters, replacing the body is refused: get_post returns the body cut at 20,000 characters, so writing it back would lose the rest. The title and excerpt can still be edited
  • Posts someone has open in the editor are not edited (one of the two edits would be lost when the other saves)

schedule_post turns a draft, pending or already scheduled post into a scheduled post that goes live at the time you set (it needs the Edit existing posts and the site profile, and set publish times and Publish permissions). Pass the time (publish_at) in your site's time, such as 2026-12-01 09:00, or as ISO 8601 with a time zone offset. It must be at least one minute ahead (WordPress publishes a post right away when the scheduled time has passed). Just like publishing when an article is created, these posts are not scheduled:

  • Posts whose quality review is still running, and posts the quality review held back
  • Posts whose body still has instructions left for a person (photo slots or work notes)

Published posts can't be rescheduled (unpublish them in the admin). unschedule_post turns a scheduled post back into a draft.

Reading the numbers (rankings, goals, Search Console, article ideas, audits, AI visibility)

Give a key Read rankings, goals and other numbers, and you can ask "Did our rankings go up since last month?" or "Will we hit this month's goal?"

  • list_rankings: results from Rank Tracking. Post IDs are returned only for posts visitors can see
  • list_kpis: progress on each goal in Goals and Reports (counted the same way as on that screen)
  • search_console_summary: adds up the Search Console numbers Sorabun records from Site Kit every day. It doesn't ask Google directly, so the last 2 or 3 days may be missing
  • list_article_ideas / refresh_article_ideas: the ideas for what to write next from "SEO Insights." Remaking them costs AI and search fees, so a key can do it at most once a day (if the saved ideas are newer than that, they're returned as they are)
  • get_technical_audit: the last result of the Technical Audit (each check's level, explanation and related post IDs) and the home page's Core Web Vitals. It doesn't run a new audit
  • list_broken_links: results from the Link Checker. Choose broken links (broken), redirects (redirect) or links to look at (warning). It doesn't re-check them
  • get_ai_recommendations: the last AI Recommendations (LLMO) measurement (how often you were recommended, with its range, by AI assistant, the comparison criteria, other names recommended, sources, which of your pages were cited, the evidence check, history and per-question counts). Answer texts aren't returned
  • list_ai_citations: AI citation check results by keyword (the result per assistant, source hosts and history)
  • search_console_queries: the new queries and almost-ranking queries from "SEO Insights." The result is kept for a day and fetched from Site Kit again when older (the Search Console API is free). Keys read it as the administrator who connected Site Kit

All of these only read. There are no tools that start paid runs (measuring AI recommendations now, checking AI citations). Questions to Gemini and ChatGPT cost different amounts depending on the model you chose, and Sorabun has no per-question estimate for them, so it can't promise "run only up to this cost." Start those from the admin screens.

Post IDs and titles are returned only for posts visitors can see (published, no password). Broken links are likewise limited to links used in posts visitors can see (keys with Publish get everything).

Reading and updating the site profile (get_site_profile / update_site_profile)

The AI can read and update what you wrote in Site Diagnosis (topic, readers, area, aims, goals, topics to avoid) along with key pages, competitors and the research log. Have it read the profile before SEO work, and it builds on what you've already told Sorabun, and checks the research log so it doesn't pay for the same research twice.

  • Reading (get_site_profile) needs Read rankings, goals and other numbers. Competitors and research are internal information you haven't published, so keys that can only read published posts don't see it
  • Updating (update_site_profile) needs Edit existing posts and the site profile, and set publish times (with Publish). The profile and key pages go into every article Sorabun writes from now on, so it carries the same weight as editing existing posts
  • One call can change the fields (fields), key pages, competitors and the research log together. Either every change applies or none does; if one is wrong, it says which one and why
  • Key pages are matched by URL and competitors by domain (http and https, www and a trailing / count as the same page). Re-adding without a role or note keeps the stored one
  • Entries written by an AI are marked "MCP," and entries written on the screen are marked "you"
  • Each update is recorded in the activity log

Queuing SNS posts (list_social_posts / schedule_social_post / cancel_social_post)

Give a key Queue SNS posts, and it can add posts on X that promote a published post (without a password) or a scheduled post to the SNS Auto-Posting queue.

  • Don't put the post's URL in the text (text). Sorabun adds the URL and hashtags the way your "SNS Auto-Posting" settings say. Text that's too long is refused, not cut
  • If you leave out the time (at), it goes into the nearest free posting time from your settings
  • Posts an AI adds wait as drafts for approval (they go straight into the queue only if you've set "SNS Auto-Posting" to queue drafts without checking). Read them in the admin, then approve them
  • cancel_social_post cancels a post that hasn't been sent yet. Posts already on X can't be taken back

Reading inquiries (list_inquiries / get_inquiry)

Give a key Read inquiries, and it can read the inquiries you receive. The list (list_inquiries) has only the subject, date and verdict (whether it looks like sales or a bot). Names, email addresses and messages come back only one inquiry at a time (get_inquiry). The IP fingerprint and the verdict's score and reasons are never returned.

This is personal data

Inquiries contain visitors' names, email addresses and messages. Only administrators can add this permission, and no key has it by default. Give it only to the keys that need it. Each read is recorded in the Activity Log with the key's name and the inquiry's ID (not its contents). Inquiry text is written by visitors, so the tool descriptions tell the AI to treat it as something to read, not as instructions.

Reading the security status (security_status)

Give a key Read the security status, and the AI in an MCP client using that key can read the results of the daily security monitor. Ask "Is there anything on my site I should fix right away?" and it answers with:

  • Known vulnerabilities in installed plugins, themes and WordPress (severity, CVE and the fixed version). As the data source (Wordfence Intelligence) requires, the source and its copyright and license notices come with them, and the AI is told to show them too
  • Urgent (security fix) updates you haven't applied yet
  • WordPress core files that were changed, are missing, or don't belong
  • How many login lockouts happened in the last 7 days (it never returns the usernames tried or IP addresses)
  • Which hardening options (such as XML-RPC) are on

It only reads. It doesn't run a new scan, change settings, or update anything. You fix things under "Security / Speed" in the admin.

Give it only to the keys that need it

A leaked key would let someone create articles, and with this permission, also see where your site is weak. You can also make a key that only reads the security status (set its article permission to "Don't use"). After using a key with new permissions, reconnect your MCP client to see the tool.

Connect from claude.ai and ChatGPT without a key (OAuth)

Custom connectors in claude.ai and ChatGPT connect with just the MCP URL, and usually have no place to paste a key. Sorabun also supports the MCP authorization flow (OAuth 2.1). When you connect, this site's login and "Allow" screen opens, and the connection is made when you allow it. You don't need to create a key. Keys keep working as before.

The URL to enter is the same MCP endpoint.

https://your-site/wp-json/sorabun/v1/mcp

How to connect

Screen names are those of the English interface (as far as we could confirm in Anthropic's and OpenAI's documentation in November 2026).

claude.ai (Free, Pro, Max)

  1. Open Customize > Connectors, then choose Add and Add custom connector
  2. Enter a name and the URL above, then click Continue
  3. Keep the authentication settings that Claude reads and marks as Detected, then click Add
  4. Click Connect. This site's login and "Allow" screen opens

On Team and Enterprise plans, an Owner adds it under Organization settings > Connectors with Add and Custom, and each member clicks Connect under Customize > Connectors.

ChatGPT

  1. Open ChatGPT Plugins (chatgpt.com/plugins), then choose + and Add custom MCP server
  2. Enter a name and a description, and put the URL above under Connection
  3. Choose the authentication, read the warning, click I understand and want to continue, then Create as a plugin

Check OpenAI's documentation for which plans and workspace policies allow this.

Claude Code

claude mcp add --transport http sorabun "https://your-site/wp-json/sorabun/v1/mcp"

Don't add a header (--header). After adding it, open /mcp inside Claude Code to authenticate.

Only sites on https that are reachable from the internet

claude.ai and ChatGPT can only connect to https sites. They also connect from Anthropic's and OpenAI's side, so they can't reach a site that only runs on your own computer (Claude Code connects from your computer, so you can try it with an http://127.0.0.1 site).

The allow screen

If you aren't logged in, the login screen comes first. After you log in, the screen shows:

  • What the app calls itself: if the app publishes its information at a URL (a Client ID Metadata Document), that place is shown too (claude.ai, chatgpt.com and so on). The name of an app that registered itself (dynamic registration) is whatever it claims, and can't be verified
  • Where it returns after you allow: the place, such as claude.ai or chatgpt.com, in large type. Tell apps apart by this, not by the name. When it returns to this computer (127.0.0.1 or localhost), a warning is shown too
  • Who it acts as: the user who is logged in
  • Permissions to allow: the same four as keys. The ones the app asked for are checked to begin with. Anything you uncheck is not allowed
  • Expiry: 30 days, 90 days or 1 year

You can only allow permissions within your own WordPress capabilities.

PermissionWho can allow it (WordPress capability)
Read published postsAnyone who can log in (read)
Create draftsContributors and above (edit_posts)
PublishEditors and administrators (publish_posts and edit_others_posts, because a key that can publish can read every article, including other people's drafts)
Read the security statusAdministrators (manage_options)

If more permissions are added to keys, who can allow them follows the same lines as keys (permissions only administrators can put on a key are administrator-only with OAuth too). The permission to edit existing posts ("Edit existing posts and the site profile, and set publish times") can only be allowed together with "Publish". Permissions the app didn't ask for are never checked to begin with.

If that person's WordPress capabilities are lowered later, the connection's permissions are lowered too. Deleting that user stops the connection.

claude.ai first asks for "Read published posts" and "Create drafts". If it is later asked to publish, claude.ai asks for permission again (you can also check "Publish" on the allow screen from the start).

Tokens and expiry

  • Access tokens expire after 1 hour, and the app replaces them by itself (with a refresh token)
  • Each time a refresh token is used, it is replaced with a new one. If an old, already replaced one is used, it may have been stolen, so every token of that connection is stopped (the Activity log records "Stopped an OAuth connection (possibly stolen)"). A reused authorization code is handled the same way
  • A connection ends after 30 days without use, or when the expiry you chose comes. To reconnect, click "Allow" again
  • When the same person connects the same app again, the old connection is replaced by the new one
  • Tokens only work at the MCP endpoint (not at REST API routes such as /articles)
  • Once connected, it's treated like a key: up to 600 calls per hour and 50 articles per day per connection. Calls are recorded under "API keys" in the activity log with the name OAuth "app (user)"
  • Sorabun doesn't store the values of tokens or authorization codes. It only stores hashes mixed with the site's secret

Connected apps and revoking

"Sorabun > Settings > REST API / MCP Integration" lists Connected apps with the app, the person who allowed it, permissions, last used and expiry. Click Revoke and that app stops working right away. People who aren't administrators can revoke the ones they allowed under "Sorabun: Connected apps (OAuth)" on their profile screen.

To stop OAuth connections altogether, click Stop in the same section. Apps connected with OAuth stop working (the connections remain, and switching back to Use makes them work again). Keys keep working.

If it won't connect (/.well-known/ isn't reached)

claude.ai and ChatGPT read https://your-site/.well-known/oauth-authorization-server to learn how to connect (the specification fixes this location). If the section shows Reached, you're fine. If it shows Not reached:

  • If your permalinks are set to "Plain", change them to something else under "Settings > Permalinks"
  • If WordPress lives in a subdirectory (such as https://example.com/blog/), the top of the site (https://example.com/) isn't WordPress, so the request doesn't arrive as is. Pass requests that start with /.well-known/oauth- to WordPress's index.php in your server settings. The section shows example settings for your site (Apache and nginx)

The other document (the protected resource metadata) is announced in a header (WWW-Authenticate) when the MCP endpoint answers a call without a key with 401, pointing to a REST location (/wp-json/sorabun/v1/oauth/protected-resource), so it can be read even if /.well-known/ isn't reached.

Supported specifications

Sorabun follows the MCP authorization specification (version 2026-07-28, and it also works with clients of version 2025-11-25). Apps can register with a Client ID Metadata Document (the client_id is an https URL; claude.ai and ChatGPT try this first) or with dynamic client registration (RFC 7591). PKCE is S256 only, and return addresses must be https or on this device (127.0.0.1 or localhost). Clients that use their own address scheme (such as cursor://) should connect with a key.

You can also call it as a REST API

With the same key, you can also trigger article generation from Zapier, Make, or your own scripts.

Authentication

Attach your key to the request header (Authorization: Bearer <your key> works too).

X-Sorabun-Key: <your key>

Endpoints

MethodPathPurposePermission needed
POST/wp-json/sorabun/v1/articlesStart article generationCreate drafts (Publish, if post_status is publish)
GET/wp-json/sorabun/v1/jobs/<id>Check a job's statusCreate drafts (only jobs made with this key; every job with Publish)
GET/wp-json/sorabun/v1/jobsList recent jobsCreate drafts (as above)

The following parameters can be passed in an article generation request.

  • keyword (required)
  • type: optimization type
  • length: character count
  • post_status: draft or publish
  • custom_prompt: additional instructions
  • tone: writing style (desumasu / dearu / casual)
  • diagrams: number of diagrams (0 to 5; -1 lets the AI add them only where they help)
  • eyecatch: whether to generate a featured image (true / false)

In the REST API, leaving out length lets the AI decide the length from search intent (in MCP, create_article uses the site default instead). Any other parameter you leave out uses your settings.

Errors

HTTPcodeCause and fix
401sorabun_no_key / sorabun_bad_keyNo key, or the wrong key (a revoked key ends up here too)
401sorabun_key_expiredThe key has expired. Create a new one
403sorabun_forbiddenThe key doesn't have permission for this (data.required_scope names the permission needed)
403sorabun_not_your_jobThe job was made with another key or from the admin
429sorabun_rate_limited / sorabun_article_limitOver the hourly call limit or the daily article limit. Wait the number of seconds in Retry-After

On the MCP endpoint, a missing permission comes back as HTTP 403 (JSON-RPC error -32003), and the daily article limit as HTTP 429 (-32029) with Retry-After.

Handling your keys

Anyone with a key can do whatever its permissions allow. If you register it with an external service, check that service's access controls. If you suspect a key has been exposed, revoke it in the list on the settings screen.

You can also use the WordPress Abilities API (WordPress 6.9 and later)

Starting with WordPress 6.9, plugins can register their features with WordPress as "abilities." Sorabun registers the same functions as the MCP tools above as abilities in the sorabun category. (On WordPress 6.8 and earlier, it does nothing.)

AbilityWhat it runs (MCP tool)WordPress capability needed
sorabun/create-articlecreate_articleedit_posts (publish_posts to publish)
sorabun/rewrite-articlerewrite_articleedit_posts (and being able to edit that post)
sorabun/article-from-urlarticle_from_urledit_posts (publish_posts to publish)
sorabun/get-job / sorabun/list-jobsget_job / list_jobsedit_posts (below Editor, only your own jobs)
sorabun/list-posts / sorabun/get-postlist_posts / get_postread (posts you can't edit show only what visitors see)
sorabun/site-infosite_inforead
sorabun/security-statussecurity_statusmanage_options
sorabun/update-postupdate_postedit_posts (publish_posts for published, scheduled and private posts), and being able to edit that post
sorabun/schedule-post / sorabun/unschedule-postschedule_post / unschedule_postpublish_posts, and being able to edit that post
sorabun/list-rankings / sorabun/list-kpis / sorabun/search-console-summarylist_rankings / list_kpis / search_console_summaryedit_posts (the same as the Rank Tracking and Goals and Reports screens)
sorabun/list-article-ideas / sorabun/refresh-article-ideaslist_article_ideas / refresh_article_ideasedit_posts
sorabun/get-site-profile / sorabun/list-ai-citations / sorabun/search-console-queriesget_site_profile / list_ai_citations / search_console_queriesedit_posts (the same as the Site Diagnosis, Rank Tracking and SEO Insights screens)
sorabun/update-site-profileupdate_site_profilepublish_posts
sorabun/list-broken-linkslist_broken_linksedit_others_posts (the same as the Link Checker screen)
sorabun/get-technical-audit / sorabun/get-ai-recommendationsget_technical_audit / get_ai_recommendationsmanage_options (the same as the Technical Audit and AI Recommendations screens)
sorabun/list-social-posts / sorabun/schedule-social-post / sorabun/cancel-social-postlist_social_posts / schedule_social_post / cancel_social_postmanage_options
sorabun/list-inquiries / sorabun/get-inquirylist_inquiries / get_inquirymanage_options

Abilities run with the permissions of the logged-in WordPress user, not the keys above. They follow the same lines as the admin screens, so the key rate limits don't apply.

  • WordPress REST API: List them at /wp-json/wp-abilities/v1/abilities?category=sorabun and run one at /wp-json/wp-abilities/v1/abilities/<ability>/run (log in with an application password, for example). Read-only abilities use GET (input in the input query parameter), sorabun/cancel-social-post uses DELETE (also with the input query parameter), and the others use POST (input in the body). Calls that can't be accepted in the current state (a post someone has open, a review still running, cancelling a post that was already sent, and so on) return 409
  • MCP Adapter: On sites with the WordPress MCP Adapter (mcp-adapter) installed, Sorabun's abilities are available from the adapter's default server too (every Sorabun ability is marked public)
  • Inputs and outputs: Every ability comes with JSON Schemas for its input and output, and with the read-only, non-destructive and idempotent hints