# Narrareach Connector and Automation API

Connect AI assistants and automation tools to Narrareach without sharing your publishing-platform passwords.

- MCP connector: https://www.narrareach.com/mcp
- MCP tool reference: https://www.narrareach.com/docs/mcp-tools.md
- OpenAPI 3.1 contract: https://www.narrareach.com/openapi.json
- Human-readable documentation: https://www.narrareach.com/api-docs

## How access works

MCP clients use Narrareach OAuth. Users sign in and approve access for their own account. REST, Make, and n8n workflows use a scoped automation token created in Narrareach settings. Grant only the permissions required by the workflow and keep automation tokens in the calling tool's credential store.

## Personal accounts and teams

Use `list_workspaces` to discover the teams and writers your MCP connection can access. Team selectors are currently accepted by `list_content_versions`, `create_article_from_note`, `list_notes`, `get_note`, `schedule_note`, `list_linkedin_destinations`, `list_social_accounts`, `list_instagram_destinations`, `list_scheduled_items` (Notes only), `get_stats_insights`, `get_voice_profile`, `save_voice_preference`, `add_voice_material`, `decide_voice_suggestion`, `update_voice_rule`, `remove_voice_rule`, and `undo_voice_change`. Other tools use your personal account; check the per-tool reference before sending `workspace` or `writer`. REST, Make, and n8n use the account that created the automation token.

## Find a scheduled item

For Notes and social posts, use `list_notes`, then `get_note` with the returned `id`. Keep `workspace` on team calls. For articles, use `list_scheduled_posts` and locate the schedule `id`, not the draft id. Personal schedules can be changed with `reschedule_scheduled_item` or `cancel_scheduled_item`; team Note changes currently use the dashboard.

## Claude

Narrareach is an official Claude connector. In Claude, open Connectors, find **Narrareach**, select Connect, and complete Narrareach sign-in. If it isn't listed for your account, add a custom connector named **Narrareach** with the URL `https://www.narrareach.com/mcp` and leave advanced client credentials empty.

## ChatGPT

[Open the official Narrareach plugin](https://chatgpt.com/plugins/plugin_asdk_app_6a885b3638348191852d1a62404b855d).

1. Open the official Narrareach listing and install the plugin.
2. Connect your account when prompted. Sign in with the same email you use for Narrareach and review the requested permissions.
3. In a new chat, type @ and select Narrareach. Ask it to show your connected accounts and existing drafts before scheduling.

On a phone or tablet, open the listing in a browser if you cannot find it in the app. Availability depends on your account and workspace settings.

If Substack asks for a verification code and your connection supports it, enter the emailed code in the same conversation. You do not need a desktop extension for that step. If the code box closes, send the code as a normal reply in that conversation. Continue with the same saved draft and wait for scheduling confirmation.

For optional custom setup, open [ChatGPT Plugins](https://chatgpt.com/plugins) in a browser, select Add (or the plus button), then Add custom MCP server. Enter Narrareach and `https://www.narrareach.com/mcp`, choose OAuth, and leave client ID and client secret empty. Review the warning, select I understand and want to continue, then Create as a plugin. Complete sign-in and install it. If these controls are unavailable, use the official listing or ask your workspace administrator. See [OpenAI’s custom connection guide](https://developers.openai.com/plugins/deploy/connect-chatgpt#add-the-mcp-server).

## Gemini

In Gemini Settings → Connected Apps, add a custom app using `https://www.narrareach.com/mcp`. Complete sign-in, then select `@Narrareach` in a chat when explicit connector selection is needed. Availability depends on Google's current account and region requirements.

## Notion Agents

On a Notion Business or Enterprise plan, ask your workspace admin to enable custom MCP servers and approve `https://www.narrareach.com/mcp` if connections are restricted. For Notion Agent on web or desktop, use Settings → Connections → Discover → Add Custom MCP. For a Custom Agent, use that agent's Settings → Tools & Access → Add connection → Custom MCP server. Enter `https://www.narrareach.com/mcp` and complete Narrareach OAuth sign-in; do not paste an API token or client secret. Notion Agent and each Custom Agent require separate connections. Keep confirmation enabled for write tools, and restrict who can interact with a Custom Agent because it uses the connected user's Narrareach permissions. See https://www.narrareach.com/api-docs#notion-agent for the full setup guide.

## Make

Use Make's HTTP module with a scoped Narrareach automation token. Follow the agent-ready guide at https://www.narrareach.com/docs/make.md and use https://www.narrareach.com/openapi.json as the request contract.

## n8n

Install `n8n-nodes-narrareach`, add a scoped Narrareach credential, and use the native actions for scheduling Articles and Notes, status, rescheduling, cancelling, reader activity, and Stats outcomes. Start workflows from Note events with n8n's Webhook node. See https://www.narrareach.com/docs/n8n.md.

## MCP tools

Narrareach exposes 48 documented public tools, plus 2 pilot tools shown only to eligible accounts, across workspaces, drafts, Notes, articles, media, audience activity, writing voice, inspiration, and analytics. Read https://www.narrareach.com/docs/mcp-tools.md for the complete allowlisted reference.

To edit a personal-account, text-only queued LinkedIn post before publishing starts, inspect readiness and queued text, then use `amend_scheduled_note_content` to preview the replacement. Apply only after confirmation. This does not edit media posts or scheduled article content. Article readiness links to the Narrareach draft, not a verified copy on the publishing platform. Read the [scheduled LinkedIn editing guide](https://www.narrareach.com/api-docs#edit-scheduled-linkedin).

Official Narrareach plugin: new or changed tools become available after OpenAI approves them. Installing again or reconnecting does not bypass that review. Try a new chat with Narrareach selected once the update is available.

Custom connection: open its settings in ChatGPT in a browser. If Refresh is available, select it, check the tool list, then start a new conversation. Reconnect or Change connection may only repeat sign-in; they do not confirm that new tools were added.

If Refresh is missing or Substack verification is still unavailable, contact Narrareach support with the missing action and whether you use the official plugin or a custom connection. Keep your existing draft and publishing accounts connected. A managed workspace may need an administrator to review and enable new actions.

Read the [connection guide](https://www.narrareach.com/api-docs#refresh-tools).

## REST API

The public OpenAPI 3.1 document at https://www.narrareach.com/openapi.json is the authoritative REST contract. Send `Authorization: Bearer NARRAREACH_API_TOKEN`, use only the scopes declared by the operation, and parse non-success responses through the stable public error envelope.

## Webhooks

Narrareach can POST an event to your HTTPS endpoint when a scheduled Note publishes or fails. Webhooks are included in Full Agentic Mode. Add an endpoint in Settings → Integrations → REST API & webhooks; registration happens in the app, not with an automation token. Each endpoint receives both Note events and has its own signing secret, shown once when you add it. Use **Test** to send a `webhook.test` event.

### Webhook events

- `note.published` — a Note was published. `data.note.postUrl` holds the platform URL when the platform returns one.
- `note.failed` — a Note could not be published. `data.note.error` holds the reason.
- `webhook.test` — sent only by **Test**.

Scheduled Notes send events for Substack, LinkedIn, X, Threads, Instagram, Facebook, TikTok, and Pinterest. Notes posted right away through `POST /api/v1/notes` send events for every platform. Articles do not send webhook events yet, and scheduled Bluesky Notes may not send them; use the status endpoints for those.

Each Note platform sends its own event. The JSON body looks like this:

```json
{
  "id": "stable event id",
  "event": "note.published",
  "createdAt": "2026-10-07T13:00:05.000Z",
  "data": {
    "note": {
      "id": "note id",
      "draftId": null,
      "platform": "SUBSTACK",
      "content": "Note text",
      "status": "POSTED",
      "scheduledFor": "2026-10-07T13:00:00.000Z",
      "postedAt": "2026-10-07T13:00:04.000Z",
      "postUrl": "https://...",
      "externalPostId": "platform post id",
      "imageUrls": [],
      "attachments": [],
      "error": null
    },
    "source": { "product": "narrareach" }
  }
}
```

### Verify and handle deliveries

- Headers: `X-Narrareach-Event`, `X-Narrareach-Delivery`, `X-Narrareach-Timestamp`, and `X-Narrareach-Signature` in the form `t=TIMESTAMP,v1=SIGNATURE`.
- To verify, compute an HMAC-SHA256 hex digest of `TIMESTAMP.RAW_BODY` using the signing secret and compare it with `v1`. Use the raw request body, not re-serialized JSON, and reject old timestamps.
- Respond with any 2xx status within 8 seconds. Other responses and timeouts are retried with increasing delays, up to 5 attempts in total.
- The same event can arrive more than once. Use the body's `id` to ignore duplicates.
- Deliveries are sent within about a minute of the event.


## Safe retry pattern

1. Use a stable idempotency key derived from the source record where supported.
2. Persist accepted Narrareach identifiers immediately.
3. After a timeout, check the right content list or returned status id. For REST create requests with no returned id, replay the identical request with the same idempotency key. MCP agents should not resubmit until the earlier result is known.
4. Retry temporary failures with bounded backoff.
5. Send authorization and validation failures to credential or editorial review.

## Media

Public HTTPS media URLs can be scheduled where supported. MCP clients can use `upload_media` for image or video bytes before scheduling. In ChatGPT, a file the user attaches in the chat goes in `upload_media` `file`; use the returned `publicUrl` when scheduling. Local `file:` and `blob:` references are not fetchable by a remote service.

## Safety and privacy

- Never paste platform passwords, browser sessions, or automation tokens into a chat or shared workflow export.
- Confirm destination, schedule, and audience before calling a write tool.
- Use the narrowest workspace and token scopes available.
- Treat returned advisories as status information unless the operation explicitly fails.
- Public documentation describes supported contracts only; it does not expose private application or provider implementation.

## Troubleshooting

- **401:** reconnect OAuth or replace an invalid automation credential.
- **403:** verify workspace access and required scope.
- **Validation error:** follow the public `error.resolution` and correct the request rather than retrying unchanged data.
- **Timeout:** inspect status before retrying with the same idempotency key.
- **Hosted MCP client cannot reach localhost:** use the production HTTPS connector URL.