Brain API Reference

The Brain API is a public developer endpoint that exposes your MarketingSecrets.ai memory to any MCP-compatible client (Claude Desktop, Cursor, ChatGPT, or your own scripts). Authenticate with a per-user API key for read/write access to your entrepreneur profile, memory facts, and semantic memory.

Base URL & protocol

POST https://www.marketingsecrets.ai/api/mcp

JSON-RPC 2.0 over HTTP POST (Model Context Protocol). All requests must use HTTPS.

Authentication

Send your API key in the x-api-key header:

x-api-key: ms_YOUR_KEY

• Keys use the ms_ prefix + 64 hex characters (67 total).
• Generate keys in Chief of Staff → Manage → Memories → Connect an AI you already use (Advanced tab). The plaintext is shown once and is never kept server-side — it's stored as a SHA-256 hash. Revoke anytime.
• Every method needs a key, including the handshake. initialize, notifications/initialized, and ping all return -32001 Authentication required without one, so send your key on the very first request.

Tools

Categories for memory_save: business, audience, preferences, projects, imported, misc.

Inventory tools

These are read-only and paginated. They exist so a client can enumerate your Attractive Character material rather than having to already know a uuid.

Paging. Every list tool takes limit (default 25, maximum 50 — a larger value is clamped, not rejected) and offset (default 0). The response is a JSON object with an items array and a page object:

{
  "ok": true,
  "kind": "stories",
  "items": [{ "id": "…", "title": "…", "summary": "…", "themes": [], "emotion": "hope" }],
  "page": {
    "limit": 25,
    "offset": 0,
    "returned": 25,
    "total": 873,
    "has_more": true,
    "next_offset": 25
  },
  "hint": "Showing 25 of 873 stories (offset 0). More exist — call again with offset: 25."
}

Page by copying page.next_offset into the next call's offset, and stop when page.has_more is false. page.total is the real number of rows matching your call — never treat one page as the whole library.

Three limits are worth knowing:

• Story embeddings are never returned. list_stories and search_stories return id, ac_profile_id, title, summary, themes and emotion only; call get_story for the body.
• A page can be shortened to fit the response. If the rows on a page would exceed the response size budget, the tail is dropped, truncated_for_size is set to true, and page.returned/page.next_offset are adjusted so following next_offset still skips nothing.
• Hook paging walks stories. Hooks live inside their story rows, so list_hooks/search_hooks read a bounded window of stories per call and report it as scan. Page within the window with offset; when scan.capped is true the walk stopped short of your whole inventory, so continue with story_offset: <scan.next_story_offset> and offset: 0. Never conclude a hook does not exist from a single capped page.

Every inventory tool only ever sees the workspace that minted your key. An ac_profile_id argument is resolved against that workspace's own characters, so it accepts a character's name as well as its uuid.

Attractive Character write tools

These are the only correct way for a client to record an Attractive Character. Saving a persona with memory_save puts it in your Brain as a note and leaves your Attractive Characters page empty — that is not the same thing, and the write tools exist so a client never has to settle for it.

Four rules govern all five, and a client that ignores them gets a refusal rather than a surprise:

• What a client creates is yours to use straight away. A new character or voice is live the moment it is saved: you can open it, generate from it, add voices to it, and a routine may use it. There is no draft state and nothing to confirm — a client that tells you to go and approve the character is wrong.
• Every update needs base_revision. Read the record first (list_attractive_characters, get_attractive_character, list_voices, get_voice, or the revision a previous create/update returned) and send that revision value back as base_revision. If the record changed in between — most often because you edited it yourself in the app — nothing is written, and the refusal carries the live current_revision to merge against. A call without a base_revision is refused the same way. This is what stops a client from quietly overwriting your own edits.
• There is no delete. Removing a character, a voice or a story is an in-app action only.
• Apology text is not a story. save_attractive_character_story rejects placeholder content ("I couldn't find any stories…") instead of filing it, so a client that found nothing has to tell you rather than leave a phantom row behind.

A refused write comes back as a normal tools/call result with isError set to true and a JSON body explaining what to fix — not as a JSON-RPC error — because every one of these refusals is recoverable within the same conversation. The one exception is a connection with no workspace in scope, which fails with -32001.

A successful create or update returns the new revision, so a follow-up edit in the same conversation needs no extra read, plus a view_url like /home/<workspace>/attractive-characters/<id> to open what was just written.

Customer avatar write tool

Your customer avatars — the dream buyers you write to, as opposed to the character you write as — have their own create tool, for the same reason. Saving a persona with memory_save files it in your Brain as a note and leaves your Customer Avatars page empty.

Three things govern it:

• Several avatars are normal. Unlike an Attractive Character, a workspace is expected to have more than one dream buyer, so a second create is not treated as a mistake. What is caught is an accidental repeat: creating the same name twice within ten minutes, or creating a name that is saved with no profile yet (what the Create button on the Customer Avatars page makes), fills in the empty fields of the avatar that already exists, flagged already_created: true, instead of saving a duplicate. Values already saved are never overwritten.
• There is no update and no delete. Editing or removing an avatar is an in-app action only, on your Customer Avatars page. A client that wants to change one has to tell you rather than write a second copy.
• Only name is required. Everything else is optional on purpose: a thin avatar built from what you actually said beats a padded one, and demographics/psychographics are free-form objects so a client can record whatever it genuinely learned.

A successful create returns the new avatar_id, the full avatar row, and a view_url of /home/<workspace>/customer-avatars.

Every tool returns its payload as text on the JSON-RPC envelope at result.content[0].text. The sections below give the exact shape of that text per tool.

memory_search

Keyword search over your business brain. It covers the facts you saved, facts a teammate shared into the workspace, and the Team Brain.

Your query is split into words, and a fact matches when every word appears somewhere in its key or value, in any order — so stock watchlist finds a fact reading "current stock watchlist (Q3)". Matches come back newest-first.

When nothing matches every word, the search widens on its own, in order:

1. Any word instead of all of them, ranked by how many words each fact hits.
2. Translated and synonym keywords. A question asked in one language still finds a fact saved in another — asking Aký je môj cieľ reaches a fact stored as "September 2026 revenue target".

Short, distinctive queries are still the best input — one to four words like a name, a topic, or a metric. Fall back to memory_get_recent when a search comes up empty.

Arguments: query (string, required), limit (number, default 8)

Response lines are numbered and carry the category, plus the fact key when one exists:

1. [audience] ideal_customer: bootstrapped agencies doing $500K-$2M/yr
2. [business] pricing: $997 coaching, 4 slots per cohort

memory_get_profile

Returns the structured entrepreneur profile: business name, niche, audience, social handles, current focus.

Arguments: none ({})

Response text is one Label: value pair per line:

Business: Acme Agency
Niche: B2B SaaS marketing
Audience: bootstrapped SaaS founders doing $200K-$2M ARR
Current focus: launching a cold-email SOP

If nothing has been captured yet you get No entrepreneur profile found yet., and if the profile exists but is empty, Profile exists but is empty.

memory_save

Save a new fact to the brain. Indexed for semantic search and stored as a structured fact.

Arguments: content (string, required), category (string, default misc)

Returns a confirmation naming the category it filed under, e.g. Saved to brain (audience).

memory_get_recent

List the most recent structured facts in chronological order — no semantic ranking.

Arguments: limit (number, default 20)

Response lines are [category] key: value, unnumbered:

[audience] ideal_customer: bootstrapped agencies doing $500K-$2M/yr
[projects] q3_launch: cold-email SOP ships Sept 12

Example: search your Brain

curl -X POST https://www.marketingsecrets.ai/api/mcp \
  -H "x-api-key: ms_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "memory_search",
      "arguments": { "query": "who is my ideal customer?", "limit": 5 }
    }
  }'

The same call in TypeScript:

const res = await fetch('https://www.marketingsecrets.ai/api/mcp', {
  method: 'POST',
  headers: {
    'x-api-key': process.env.MS_BRAIN_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    jsonrpc: '2.0',
    id: 1,
    method: 'tools/call',
    params: {
      name: 'memory_search',
      arguments: { query: 'who is my ideal customer?', limit: 5 },
    },
  }),
});
const { result } = await res.json();
console.log(result.content[0].text);

Responses follow the JSON-RPC envelope — the text payload lives at result.content[0].text:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": { "content": [{ "type": "text", "text": "…" }] }
}

Example: save a fact

curl -X POST https://www.marketingsecrets.ai/api/mcp \
  -H "x-api-key: ms_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "memory_save",
      "arguments": {
        "content": "Ideal customer: bootstrapped agencies doing $500K-$2M/yr.",
        "category": "audience"
      }
    }
  }'

Error codes

Errors come back as JSON-RPC error objects. Check error.message for a human-readable explanation.

All but -32001 and -32002 are standard JSON-RPC 2.0 codes; those two are our own, in the implementation-defined server range.

-32002 is returned on tools/call only (HTTP 402) — initialize and tools/list keep working, so a client can still connect and see why. The error object's data carries action_url and action_label pointing at the page where the plan can be reactivated.

For developers building sub-apps

Sub-apps inside the MarketingSecrets ecosystem can read from and write to the shared Brain instead of building their own memory layer. A Brand Voice sub-app that learns the user's Attractive Character should write it to the Brain so every other tool — CoS chat, content calendar, cold-email agent — has it automatically.

See the Developer Guide for the full pattern.

Next

• Connect an AI You Already Use — setup for Claude Desktop, Cursor, ChatGPT
• MCP usage examples — real prompts and tool calls
• Developer Guide — build sub-apps on top of the Brain