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.

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