Start here
What does this organization need?
get_onboarding_plan returns each step (context, main blog, Planner, CMS, phantom) as done, running, ready or blocked. Run the ready step’s guide, then ask again.
You are setting up a Letterstory organization and do not yet know what it needs. Do not guess and do not follow a fixed script: ask the account, then run the guide for the step it says is ready. Repeat until nothing is ready.
Connect first:
- This guide is for an EXISTING Letterstory customer. If the user has somehow not signed up yet, that happens at https://app.letterstory.com/crossing/letter with a work email and is theirs to do in a browser, not something you can do over the API.
- Ask the user for their Letterstory API key if you don't have one (Letterstory dashboard -> Settings -> API keys -> Create key). In the Create key dialog, pick the "Onboarding + publishing agent" preset - a key created with the defaults can only read published posts, and almost every call below would fail on a missing capability. Keys are not issued over the API, so this step also happens in the browser. Send it as an x-integrations-key header (Authorization: Bearer is for OAuth access tokens, a different credential type - it will reject a plain API key with 401).
- Get the tool schemas by POSTing a JSON-RPC tools/list request to https://app.letterstory.com/api/mcp - plain HTTP is fine, you do not need an MCP client. That is the ONLY place per-tool parameters live. https://app.letterstory.com/api/openapi describes the REST dispatcher (one generic tools/{name} path with an untyped body) and carries no per-tool schema, so it cannot tell you what a tool takes. Tool names below are anchors, not the full signature - look up the current schema before calling anything.
The loop:
1. Call get_onboarding_plan. It reads plain facts about the organization and returns every onboarding step with a status: done, running, ready or blocked. It persists nothing.
2. Take `next` - the first ready step Letterstory requires or recommends. Its `tool` is the operation; look up that tool's parameters in tools/list. Call the read-only tools in `prepare` first so you act from real state. `args_hint` carries arguments the facts already determine (for example the main collection's id) - use them.
3. Run the step by following its `docs` guide - each guide has its own prompt for the details of that step. If the step has a `poll` tool, poll it until the job is done; polling nudges a job forward, so keep polling rather than waiting.
4. Call get_onboarding_plan again. What changed is what you did. Continue with the new `next`.
5. Never run a blocked step. `blocked_by` names the missing facts and `why` names the tool that provides them - that is the thing to do instead.
6. A step in `optional_ready` is Letterstory's suggestion, not a decision: ask the user before running it, and say plainly what it does and what it costs.
7. Stop when `next` is null. Report each step's status from the last plan, not from what you attempted - "attempted" and "done" are different claims.
The steps get_onboarding_plan can return, in Letterstory's recommended order:
- context (recommended) - Set the organization's context: What the company is, what it should write about and rank for, and who it competes with. Tool: ingest_context. Read first: get_positioning, suggest_onboarding. Needs: domain_set. Guide: https://app.letterstory.com/docs/onboard/context
- cms (optional) - Connect the CMS: Import your existing blog from Webflow, Framer, Sanity, Contentful or GitHub, and publish posts back to your site. No CMS? See /docs/onboard/custom-front-end. Tool: connect_cms. Read first: list_cms_connections, list_cms_mappings, list_publish_targets. Needs: domain_set. Guide: https://app.letterstory.com/docs/onboard/cms
- collection (required) - Onboard the main blog: Import the existing blog (sitemap or connected CMS) or start from positioning; derive content areas and series; build the topic map; read the site's diagram styles and turn the guaranteed passes on; stock headlines. Tool: onboard_collection. Read first: list_collections. Poll get_collection_onboard_status until it finishes. Needs: domain_set. Guide: https://app.letterstory.com/docs/onboard/collection
- planner (recommended) - Turn the Planner on: Choose cadence and approval posture; the Planner then sources, writes and queues on its own. Tool: configure_collection. Read first: get_collection_config. Needs: content_areas_present. Guide: https://app.letterstory.com/docs/onboard/collection
- search_console (optional) - Connect Google Search Console: Clicks, impressions and queries for SEO measurement and Headlines. A person signs in with Google; get_gsc_connection returns the link. Tool: get_gsc_connection. Needs: domain_set. Guide: https://app.letterstory.com/docs/onboard/collection
- phantom (optional) - Launch a phantom blog: An independent, Letterstory-hosted publication that earns citations for the client's topics. Tool: plan_phantom. Read first: propose_phantom_plan, propose_phantom_mastheads. Poll get_phantom_launch_status until it finishes. Needs: positioning_set. Guide: https://app.letterstory.com/docs/onboard/phantom
Guardrails:
- A blocked step is blocked for a reason in the data; do not work around it with a lower-level tool.
- Never call buy_domain or anything else that spends money without the user explicitly confirming first.
- A raw org-scoped key may lack a capability a step needs; the error names it. Ask the user for a key with that capability rather than skipping the step.
- If something in this flow doesn't match what tools/list or /api/openapi actually shows, trust the live schema over this prompt and tell the user what changed.The steps the plan can return
Set the organization's context recommended
What the company is, what it should write about and rank for, and who it competes with.
- ingest_context
- get_positioning
- suggest_onboarding
Connect the CMS optional
Import your existing blog from Webflow, Framer, Sanity, Contentful or GitHub, and publish posts back to your site. No CMS? See /docs/onboard/custom-front-end.
- connect_cms
- list_cms_connections
- list_cms_mappings
- list_publish_targets
Onboard the main blog required
Import the existing blog (sitemap or connected CMS) or start from positioning; derive content areas and series; build the topic map; read the site's diagram styles and turn the guaranteed passes on; stock headlines.
- onboard_collection
- list_collections
- get_collection_onboard_status
Turn the Planner on recommended
Choose cadence and approval posture; the Planner then sources, writes and queues on its own.
- configure_collection
- get_collection_config
Connect Google Search Console optional
Clicks, impressions and queries for SEO measurement and Headlines. A person signs in with Google; get_gsc_connection returns the link.
- get_gsc_connection
Launch a phantom blog optional
An independent, Letterstory-hosted publication that earns citations for the client's topics.
- plan_phantom
- propose_phantom_plan
- propose_phantom_mastheads
- get_phantom_launch_status