All docs

MCP server

Credential: API token

BirchSeek serves a Model Context Protocol endpoint at https://api.birchseek.com/v1/mcp/sse. An agent connected to it can research keywords, start a pipeline run, approve each gate and publish.

Protocol revision 2024-11-05, transport HTTP with SSE. A client that asks for a later revision is answered with 2024-11-05 and can carry on from there.

Mint an API token

Settings → Account → API tokens. Name it, pick its scopes, pick an expiry, create.

The secret looks like bsk_mcp_… and is shown once. BirchSeek stores only its hash. Revoking a token ends every session holding it within a minute.

Connect your MCP client

{
  "mcpServers": {
    "birchseek": {
      "type": "sse",
      "url": "https://api.birchseek.com/v1/mcp/sse",
      "headers": { "Authorization": "Bearer bsk_mcp_…" }
    }
  }
}

The token goes in the Authorization header. There is no query-string fallback.

To check a connection by hand:

curl -N https://api.birchseek.com/v1/mcp/sse -H "authorization: Bearer $TOKEN"
# event: endpoint
# data: /v1/mcp/messages?sessionId=0199f0c8-…

The first frame is always the endpoint event. Post JSON-RPC frames to that path; answers arrive on the stream.

Token scopes

Scope	Grants
`projects:read`	Projects, connectors, internal links, calendar
`projects:write`	Create projects, approve internal links
`pipeline:read`	Runs, articles, scores, claims
`pipeline:write`	Start, retry and cancel runs; keyword research; edit drafts; resolve claims
`approve`	Approve and reject the topic, brief and draft gates
`publish`	Publish and reschedule articles

publish is off unless you tick it. A token without it can take an article to the publish gate and no further.

MCP tools

Tool	Scope	Does
`list_projects`	`projects:read`	Your projects
`get_project`	`projects:read`	Readiness: connectors, links, context docs, quota
`create_project`	`projects:write`	New project, with an optional sitemap crawl
`list_connectors`	`projects:read`	Publishing connectors and their status
`list_internal_links`	`projects:read`	Link inventory, suggested and approved
`approve_internal_links`	`projects:write`	Approve suggested links so articles can use them
`get_calendar`	`projects:read`	Scheduled publishes and due refreshes
`research_keywords`	`pipeline:write`	Start keyword discovery
`list_opportunities`	`pipeline:read`	Ranked keyword opportunities
`start_pipeline_run`	`pipeline:write`	Start a run from an opportunity, a topic, or nothing
`get_pipeline_run`	`pipeline:read`	Run state plus `next_action`
`list_pipeline_runs`	`pipeline:read`	Runs for a project
`approve_gate`	`approve`	Approve the pending gate by name
`reject_gate`	`approve`	Reject it with a note
`publish_article`	`publish`	Resolve the publish gate and ship
`retry_pipeline_run`	`pipeline:write`	Retry from the failed step
`cancel_pipeline_run`	`pipeline:write`	Cancel a run
`reschedule_publish`	`publish`	Move a scheduled publish
`get_article`	`pipeline:read`	Metadata, scores, sections, body
`get_article_claims`	`pipeline:read`	Every claim and its verification state
`update_article_body`	`pipeline:write`	Replace the body; returns fresh scores
`regenerate_section`	`pipeline:write`	Rewrite one section
`resolve_claim`	`pipeline:write`	Cut a claim or replace its source

Nine birchseek:// resource templates cover projects, runs and articles; birchseek://runs/{id} and birchseek://articles/{id} are subscribable. Three prompts ship with the server: publish_one_article, triage_review_queue, plan_content_batch.

The approval loop

Every run has four gates, and an agent has to resolve all four. Address them by name.

Gate	Payload	Rejecting
`topic_approval`	`{opportunity_id}`	cancels the run
`brief_approval`	`{}`, or `{section_plan, meta_options}` to edit	re-runs research with your note
`draft_review`	`{}`	re-runs drafting with your note
`publish_approval`	`{connector_id, publish_date?, slug_override?}`	cancels the run

get_pipeline_run returns a next_action naming the one move to make:

`next_action.kind`	Move
`wait`	Poll again, or subscribe to the run resource
`approve_gate`	Approve, using the payload schema in the answer
`resolve_claims`	`get_article_claims`, then `resolve_claim`
`edit_draft`	`regenerate_section` or `update_article_body`
`retry_run`	`retry_pipeline_run`
`blocked`	Quota or subscription; the answer says which
`done`	Stop

draft_review refuses until the content score is 70 or higher, the SEO score is 80 or higher, and there are no critical SEO issues or unresolved claims. next_action lists the failing checks before you try, and a refused approval returns them one per line.

An approval made with a token is recorded as yours, tagged with the token.

Publishing

publish_article needs the publish scope and a connector whose status is ok. Test the connector first (GitHub, WordPress, Ghost, Webflow, Shopify, Wix, Notion, GoHighLevel, webhook).

A publish_date in the future schedules the publish instead of shipping it now. Omit it to publish immediately.

Limits

600 tool calls per hour, per token.
2 active runs per account, 30 articles per billing period.
5 keyword research runs per project per day; 3 sitemap imports per project per day.
4 concurrent sessions per token; a session with no traffic for 10 minutes closes.

Troubleshooting

401 on connect - the bearer is missing, revoked, expired, or is an access token rather than a bsk_mcp_ token.
403 on connect - a browser Origin header that is not https://birchseek.com. Non-browser clients send no Origin and are fine.
403 on a message - the sessionId belongs to a different token. Open your own stream.
-32001 - a request arrived before notifications/initialized. Finish the handshake.
gates_not_green - the draft is below the bar. The message lists every failing check.
too_many_active_runs - two runs are already open. Finish or cancel one.
quota_exceeded - the period’s 30 articles are spent. Parked runs resume when the next period opens.