NewsCordHeadless docs
Open dashboard
On this page
MCP connector

Connect your AI assistant to Headless.

Headless speaks MCP, the open protocol Claude, ChatGPT, thaura.ai and a growing set of assistants use to work with outside tools. Connect your organisation once and your assistant can read your campaigns, build drafts, write letters with the Strategist and answer questions about your list, your broadcasts and your credits. Publishing and sending stay with you.

https://headless.newscord.org/mcp
OAuth 2.133 toolsReads and drafts onlyDisconnect any time
Quickstart

Three ways in, one address.

01

Claude

Open Settings, then Connectors, then Add custom connector. Paste the address above. Claude opens a browser window: sign in with your Headless account and approve.
02

ChatGPT

Open Settings, then Connectors, and add a custom connector with the same address. Approve the connection in the browser window that opens.
03

thaura.ai and any MCP client

thaura.ai connects the same way: add the address and approve the sign-in when it opens. Any other MCP client works too. The endpoint speaks streamable HTTP with JSON responses and no session state, discovery works through the standard well-known documents, and dynamic client registration is supported, so most clients connect with the address alone.

Check it worked: ask your assistant about your organisation.

You:        What is my NewsCord organisation?
Assistant:  You are Riverline Trust, on the Growth plan, with
            4,120 credits. This connection holds the editor role.
Authentication

Sign in, not keys.

Your assistant signs in with OAuth 2.1 with PKCE. There is no key to copy. A consent screen picks the organisation, shows the role the connection will hold, and lists what it will and will not be able to do.

CredentialLifetime
Access token1 hour
Refresh token30 days, rotated on every use
Authorisation code5 minutes, single use

The connection’s role is checked live on every call: demote or remove a member and their assistant loses access at the same moment. Disconnect any assistant at any time in Settings. Older access keys still work and can be revoked in the same place; new ones are no longer issued.

/.well-known/oauth-protected-resource
/.well-known/oauth-authorization-server
Boundaries

What it can and cannot do.

It will be able to
  • Read your campaigns, mailing list size and credit balance
  • Build and edit draft campaigns, and write letters with the Strategist
  • See how many people a broadcast would reach, and how past ones did
It will not be able to
  • Publish a campaign, or send any email
  • See your supporters’ names or email addresses
  • Spend money or buy credits

Those stay with you, in the dashboard.

Tool reference

33 tools, by category.

A viewer connection sees the read tools. An editor or owner connection can also build drafts and use the Strategist. No tool publishes, sends or spends, whatever the role.

Writes the draftmarks a tool that changes draft state.Editor and ownermarks a tool viewers do not see.

Organisation and context

Who the connected organisation is. The recommended first calls.

get_org_context

Who the connected organisation is: name, plan, credit balance and the role this connection holds. The recommended first call.

get_credit_balance

The organisation's current credit balance.

Reading campaigns

Everything about existing campaigns, the channel catalogue and the media directory.

list_campaign_channels

The catalogue of campaign channels a campaign can send through, with what each one reaches, its credit cost per supporter and its required fields.

list_campaigns

Every campaign in the organisation with status, channel count and submission totals.

get_campaign

One campaign in full: the saved draft and the published version supporters see.

get_screening_status

Whether the content screen held a campaign, and the reasons shown to the organisation.

list_campaign_revisions

Published versions of a campaign, newest first, with the content of any version on request.

estimate_campaign_costEditor and owner

Credits per supporter for a campaign as it stands, and how many supporters the current balance covers.

search_outlets

Search the media directory and see how a complaint to each outlet is routed. Outlets outside the directory cannot be delivered to.

Building campaigns

Draft writes only. Nothing here publishes; a person does that in the dashboard.

create_campaignWrites the draftEditor and owner

Create a draft campaign with a working name. Nothing becomes public.

update_campaign_draftWrites the draftEditor and owner

Save the full builder state of a draft in one write: channels, letters, questions and variation settings.

add_campaign_channelWrites the draftEditor and owner

Add one channel to a draft. The merge happens server side, so nothing already on the campaign can be lost.

add_campaign_questionWrites the draftEditor and owner

Add one supporter question to a draft and get back the placeholder that inserts its answer into letters.

edit_campaign_headlineWrites the draftEditor and owner

Change a live campaign's headline and share description without republishing it.

end_campaignWrites the draftEditor and owner

Stop a campaign accepting supporters. Reversible.

reopen_campaignWrites the draftEditor and owner

Let an ended campaign accept supporters again.

delete_campaign_draftWrites the draftEditor and owner

Permanently delete a campaign that has never been published. A live campaign cannot be deleted.

restore_campaign_revisionWrites the draftEditor and owner

Rebuild the draft from an earlier published version. What is live stays untouched.

The Strategist

The same drafting engine the Studio uses, with the same checks.

draft_campaign_letterWrites the draftEditor and owner

Write a supporter letter with the Strategist. Name a campaign and channel and it drafts into that channel and saves the result; it asks for anything missing, such as the article link, rather than inventing it.

refine_campaign_letterWrites the draftEditor and owner

Revise a letter from one instruction. With a campaign and channel named it revises what the channel holds and saves it back.

suggest_campaign_targetsEditor and owner

Suggest named recipients with public inboxes for a campaign's aim. Every suggestion is returned unverified, for a person to check.

check_campaignEditor and owner

Run the publish gate's checks on a draft: house style, required channel inputs and length, with an optional persuasion critique.

draft_broadcast_emailEditor and owner

Draft a subject and body for an email to the organisation's own subscribers. It writes the draft and sends nothing.

Mailing list

Aggregates only. No tool returns a subscriber's name or address.

get_maillist_summary

Mailing list size and how many people can currently be mailed. Counts only, never anyone's details.

list_segments

Saved audience segments, each with a plain English description of who it selects.

get_subscribe_link

The shareable signup link and the embed snippet for the organisation's subscribe form.

Broadcasts

Read and stop. There is deliberately no tool that sends.

preview_broadcast_audience

How many people a broadcast to the chosen segments would reach after deduplication and suppressions.

list_broadcasts

Recent broadcasts with delivery, bounce, complaint and unsubscribe counts and rates.

get_broadcast_status

The state of one broadcast, including one part way through sending.

cancel_broadcastWrites the draftEditor and owner

Stop a queued or part-sent broadcast. Credits for unsent recipients return when the queue next runs.

Billing

Reads only. Nothing here can charge a card or spend a credit.

get_billing

Balance, recent credit history with reasons, and daily spend for the last thirty days.

get_auto_topup_settings

The auto top-up configuration: on or off, threshold, pack and card state. Read only.

get_topup_link

Where a person goes to buy credits. There is no purchase tool.

Deliberately missing

There is no publish tool (it arrives with an explicit human confirmation step), no send tool, no contact export and no purchase tool. Those absences are the design, not the backlog.

Errors

One slug, one sentence.

When something fails, the tool returns a short machine slug and one plain English sentence written to be read aloud, and your assistant is expected to relay it rather than guess. Asking for something that does not exist reads the same whether the id belongs to another organisation or to nothing: identifiers are not an oracle.

not_found      That does not exist, or this organisation cannot see it.
held           This was held for review by the content screen and has
               not gone live.
Security and limits

The guarantees.

  • 600 tool calls per organisation per hour. Checking the connection is free.
  • Strategist tools share the organisation’s hourly drafting budget with the Studio.
  • Calls cap at 120 seconds.
  • The connector is stateless and answers JSON only. Protocol versions 2025-06-18, 2025-03-26 and 2024-11-05.
  • A failed sign-in is an opaque 401. The response points clients at the discovery document rather than explaining what was wrong.
  • No tool returns a supporter’s name or address. Counts only, and tests pin it.
Coming soon

What arrives next.

  • PlannedPublishing a campaign from your assistant, behind an explicit confirmation step.
  • PlannedListings in the assistant connector directories, so you can add Headless without typing an address.
  • PlannedMore tools.
  • PlannedContinued hardening.

Connect an assistant today from Settings in your dashboard.