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 from Settings → 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 Bible button 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 selected pen name has not completed Social Studio setup. Open Settings, select that pen name, and connect at least one social destination. See the Social Studio provisioning section for the complete flow.

Email campaign send returns 503

A 503 means delivery could not begin. Confirm the pen name's sender is active, run campaign preflight, and retry after the reported service issue. The draft remains saved and no recipients are marked sent until delivery actually starts. Use the request id in the error when contacting support.

“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?