Troubleshooting

“Invalid client credentials” (401)

The connector has credentials but they're wrong, missing, or revoked.

1. Open Settings → API Keys & Connectors.
2. Under Claude Cowork Connectors, generate a fresh credential pair. Copy both values; the secret is shown only once.
3. In Cowork: Settings → Connectors, click the StorytellerOS connector, scroll to Advanced settings, paste the new client id and secret, click Save.
4. The connector re-authenticates within a few seconds.

If you still get 401 after a fresh pair: confirm you generated the credentials in the same StorytellerOS account that's signed in to Cowork. Each pair is bound to a specific user.

“Connection has expired” / “Connection issue”

The connector's tokens expired and refresh failed — usually because the credential pair was revoked or rotated. Same fix as above: generate a fresh pair and paste it in.

No stos_* tools at all in the toolkit

The connector probably wasn't added (or was deleted).

1. In Cowork: Settings → Connectors → Add custom connector.
2. Name: StorytellerOS. URL: https://storytelleros.com/api/mcp.
3. Open Advanced settings and paste a credential pair fromSettings → API Keys & Connectors.
4. Click Add. The tools appear within a few seconds.

“Add custom connector” dialog has locked credential fields

This happens when a plugin auto-installs a connector — Cowork locks the fields because it thinks the plugin manages them. The StorytellerOS plugin deliberately does NOT bundle a connector to avoid this. If you see locked fields, you're probably looking at a different plugin's connector entry; add a fresh one via the global “Add custom connector” path.

“I have multiple pen names but I only see one's data”

Scoped tools default to the active / primary pen name. Pass the penNameId argument to switch:

stos_titles_list({ penNameId: "pn_def456..." })
stos_chapters_list({ penNameId: "pn_def456...", bookId: titleId })
stos_finance_transactions_list({ penNameId: "pn_def456..." })

The selector doesn't carry across calls automatically — include it on every step in a multi-step flow. See the pen-names skill in the skills reference for the full pattern.

Story bible looks truncated

The story-bible skill saves entries one at a time on purpose — if a generation gets cut off, you should still see every record that landed before the cut. To resume:

1. Ask Claude to “list characters for [title]” — confirms what made it in.
2. Ask Claude to “continue the bible for [title], skipping the ones you already saved”.

If you want the full one-shot extraction from an uploaded manuscript instead, use the in-dashboard Extract Story Biblebutton on the title page — it runs server-side and handles map-reduce when the manuscript exceeds the AI provider's context window.

Social work stops with “pen name not connected”

The pen name doesn't have an aaProfileIdyet — it isn't mapped to an Author Automations profile. See the social hand-off provisioning section for the fix. The short version: sign in to authorautomations.social and map (or create) an AA profile to match this STOS pen name.

Email campaign send returns 503

Expected — for now. The platform-side send engine is still in stub status; the/api/v1/email-campaigns/[id]/sendendpoint surfaces a friendly 503 with a “next update” message. The draft is saved fine; the actual send lights up when the send infra ships. Tracked in our roadmap.

“Update” button greyed out in Cowork

Cowork's marketplace cache hasn't caught up. Three-dot menu on the marketplace (not the plugin) → Check for updates. If it stays greyed out for more than a day, remove and re-add the marketplace.

Still stuck?