@awesomate/hosting-mcp
Version:
Awesomate MCP server — lets Claude manage your Awesomate WordPress hosting, plan, limits, n8n automations, and build Node/static apps + databases
295 lines (256 loc) • 19.3 kB
Markdown
---
name: awesomate-onebrain
description: Use the business's 1Brain (Business Blueprint's home for its systems) from Claude Code, its automations and its AI agents. Use when the user mentions 1Brain, Business Blueprint, "our systems", SOPs, policies, procedures, "what's our procedure for", "what are the procedures for the X role", "how do we do X here", "write this up as an SOP", "connect 1Brain", 1Brain Departments on the business map, the 1Brain node in n8n, an agent that answers from our procedures, training courses, quizzes, acknowledgements or read markers, onboarding a new starter, or a course for a role. Covers connecting 1Brain in the hub, looking procedures up with awesomate_onebrain, 1Brain on the business map, the other ways to use it and when to pick each, and the safety rules. Companion to awesomate-n8n (workflows and agents with the 1Brain node) and awesomate-hosting (the business map). Same connection, same PAT.
---
# 1Brain: the business's systems, from Claude Code
1Brain (from Business Blueprint) is where a business keeps its systems: its
policies, procedures (SOPs), training courses, quizzes and acknowledgements.
Most people asking about it are business owners and their teams, not
developers. Use plain words: "your procedures in 1Brain", "your systems",
never "MCP", "OAuth" or "JSON-RPC" unless they use them first.
**Routing rule:** what 1Brain holds comes from 1Brain itself, read live:
`awesomate_onebrain` in a chat, the 1Brain node in a workflow, or 1Brain's
own connector for the rarer writes (2d). Awesomate never keeps a copy. Never
answer "what's our procedure for X" from memory or general knowledge.
## How 1Brain is organised
| 1Brain word | What it is | Watch out for |
|---|---|---|
| Account (1Brain's code calls it organization) | One business's 1Brain | A person can belong to several. Always name the one you mean |
| Category (some accounts call it "Organization") | A business: a top-level group of 1Brain Departments | Two categories can share a name: pick by id. On the map, each business is one category |
| Department | A part of the business, such as Marketing or Finance | Say **"1Brain Department"** where it could be unclear: the business map calls its own top level departments too. Each 1Brain Department sits in one department of the map (`mapDepartmentNo`) |
| Folder | A small topical group of pages in a department | Titles are unique within a department |
| Page (System, SOP, policy) | One procedure or policy | Has a status: draft, published or for review |
## 0. First (every session)
1. `awesomate_whoami`: the account this folder is connected to. Wrong slug:
stop and fix the connection first.
2. `awesomate_get_context` and read `features.onebrain`:
- `available: false`: say its `message` in one line and stop. Never offer
1Brain work, never explain how to switch it on, never retry.
- No `features` block, or no `onebrain` entry (an older hub): carry on, never
read that as unavailable.
3. Work out which of the three ways below fits the ask before doing anything.
## 1. Connecting 1Brain (in the hub, per person)
Each person connects their **own** 1Brain login. Send them to the hub:
**Settings, Integrations, 1Brain** (`https://hub.awesomate.ai/settings?tab=integrations`),
then **Connect 1Brain**.
- They sign in on 1Brain's own page and tick the 1Brain accounts to allow.
Awesomate never sees their 1Brain password.
- The owner and team members with full access can connect. Each connection is
that person's: it sees exactly what they can see in 1Brain, no more.
- The hub then puts a credential named **"1Brain - <their name>"** in the
account's automations (n8n) for the 1Brain node, and keeps it current.
Nobody pastes a token. Connecting also switches on "Build and change
automations from Claude Code" (Settings, Privacy), because that is what lets
the hub place the credential.
- "Your automations don't have the 1Brain node yet": the connection worked,
but their n8n is on an older version. The credential arrives when the node
does. Nothing for them to do.
- To allow another 1Brain account later: **Connect again** and tick it.
- **Disconnect** forgets the sign-in and removes the credential (automations
using it stop reading 1Brain). 1Brain has no way for Awesomate to withdraw
its permission, so the hub links each 1Brain account's own MCP settings page
where they remove it.
You cannot connect 1Brain for them. `awesomate_onebrain` `status` says whether
the person this key belongs to is connected, which 1Brain accounts they
allowed and whether their credential is in their automations; nothing changes
the connection from Claude. Never ask for a 1Brain token or password in chat.
**Today 1Brain's connection point runs only on 1Brain's development server
(`dev.1brain.io`).** `1brain.io` and `staging.1brain.io` do not offer it yet.
Until they do, a connection reaches 1Brain's development server, not the
1Brain the team signs in to every day. Say so if their pages "are missing".
## 2. The ways to use 1Brain, and which to pick
| They want | Use |
|---|---|
| Claude to find a procedure, read a page, list a role's systems, place 1Brain Departments on the map, or save a draft procedure | **`awesomate_onebrain`** (2a) |
| A workflow step that reads or writes 1Brain: a scheduled report, a form or email turned into an SOP draft, a sync | **The 1Brain node** with the hub-made "1Brain - <person>" credential (2c) |
| An AI agent in their automations that answers from their procedures | **The 1Brain node as an agent tool** (`CUSTOM.oneBrainTool`: Page Search, then Page Get), on the credential of the person the agent answers to (2c) |
| A 1Brain course for a role or for everyone joining, and starting someone's onboarding | **`awesomate_onebrain`** onboarding actions (5) |
| Claude doing what `awesomate_onebrain` does not: writing quizzes, acknowledgements, tailoring, publishing | **1Brain's own Claude connector** (2d) |
| An AI agent that needs every 1Brain action, with no setup in the node | **MCP Client Tool** with n8n's own MCP OAuth2 credential (2e) |
| Something done as the business rather than as a person | **Not possible yet.** Every 1Brain connection is a person |
### 2a. Claude looking things up: `awesomate_onebrain`
It reads 1Brain live through the 1Brain login of the person this key belongs
to, so it sees exactly what they can see. Start with `status`: not connected
means sending them to Settings, Integrations, 1Brain, and nothing else.
`business.linked: null` means the map could not be read just now: try again,
never treat it as unlinked.
- **"What are the procedures for the front desk role?"** `awesomate_business_map`
`roles` for the role's slug, then `systems_for_role` {slug} (each system with its
link; a folder comes with its pages), then `fetch` {id} the pages that
answer the question. End with the link to every page used.
- **"How do we do X?"** `search` {query}, then `fetch` the top few: search
returns titles only and ranks loosely, so never answer from a title.
- **Nothing on the role yet?** Say so, then search, and offer to add what fits
with `link_role` {slug, ids} once they agree.
- **A new procedure:** write it from their own words, show it, then
`propose_draft` {departmentId, title, contents}. It is always a draft in
1Brain; a person publishes it there. If 1Brain asks for a business
description or which template to follow, ask them exactly that and call
again with their answer.
- **More than one 1Brain account and no category linked:** the tool asks for
`accountId`; `status` lists the accounts. Ask the user which.
### 2b. 1Brain on the business map
- **A category is a business.** The business is linked to one 1Brain
category; until it is, `departments` answers `not_linked`. `categories` lists
each 1Brain account the person can see with its categories; ask the owner
which one is this business (two can share a name, so pick by id), then link
it with `map` {accountId, categoryId}.
- **1Brain Departments sit in the map's departments.** `departments` lists each one with
its map department (`mapDepartmentNo`, 1 to 7) and sub-department (`subDepartmentNo`), suggested
from its name until someone saves the map. Place one with `map` {projectId, mapDepartmentNo,
subDepartmentNo?}; `mapDepartmentNo: null` takes
it off the map. From Claude, a change to the map is a suggestion the owner
accepts from Tasks: say it is waiting for them, never that it is done.
- **Each role keeps its 1Brain systems.** `link_role` adds pages or folders (up
to 10 at a time; a folder brings everything in it) and tags them
`job:<slug>` in 1Brain so people see it there too. The answer is per id:
when 1Brain refuses the tag (the person cannot edit that page), the system
stays on the role and the reason comes back: relay it. When 1Brain stops
partway (`stopped`: the rate limit, access switched off), what was added
stays added; ask again later with `retryIds` only, never the whole list. This list is knowledge, what someone in
the role must know. It grants nobody access to anything. `roles` reads every
role's list at once (no 1Brain connection needed); `department_systems`
{mapDepartmentNo} reads the 1Brain Departments in one map department with
their pages. `unlink_role` {slug, id, accountId?} takes one off a role, only
when the user asks; the `job:<slug>` tag stays in 1Brain (it has no way to
remove a tag), so say so.
- **Taking one off** is done on the map page in the hub. 1Brain cannot remove
tags over its connection yet, so the tag stays in 1Brain until someone
removes it there.
### 2c. Workflows and agents: the 1Brain node
The node is in the account's n8n as `CUSTOM.oneBrain` (and `CUSTOM.oneBrainTool`
for AI agents), on the hub-made credential. Load the **awesomate-n8n** skill and
read its [references/onebrain.md](../awesomate-n8n/references/onebrain.md) for
the operations, the parameters and tested patterns. The node is only on some
instances so far: check before designing around it (that reference says how).
### 2d. 1Brain's own Claude connector
For what `awesomate_onebrain` does not do (writing quizzes and acknowledgements,
sharing a course, tailoring, publishing), 1Brain has its own connector for Claude at
`https://dev.1brain.io/mcp` (the development server, see above). The person
adds it themselves:
- Claude Code: `claude mcp add --transport http onebrain https://dev.1brain.io/mcp`,
then run `/mcp` in Claude Code and sign in to 1Brain.
- Claude.ai: Settings, Connectors, Add custom connector, with that address.
It signs in as them and asks which 1Brain accounts to allow. Confirm which
account first (1Brain's own instructions ask this too) and pass it on every
call. Never pretend to use a 1Brain tool that is not in the session.
### 2e. The no-code agent route
n8n's own **MCP Client Tool** on an AI Agent, with an **MCP OAuth2** credential
whose server address is `https://dev.1brain.io/mcp`. The person signs in from
their n8n. It gives the agent every 1Brain tool with no setup, but each
reconnect registers a new 1Brain connection, and the agent can do anything the
person can, so give it strict instructions. n8n's own code supports this
route, but it has not been run end to end yet: say it is untested and test it
with them before anyone relies on it. Prefer 2c when the agent only needs to
read procedures.
## 3. Rules (every route)
1. **Drafts by default.** Anything written to 1Brain goes in as a draft (the
node defaults to Draft, although 1Brain itself defaults to Published).
Publishing is a separate, deliberate step the person asks for.
2. **Name the account every time.** A person can belong to several 1Brain
accounts. Ask which one if it is not obvious, then use it on every call.
3. **Write only when asked.** Reading is fine whenever it helps. Creating,
changing, publishing, sharing, tagging or tailoring pages happens only when
the person asks for it.
4. **Confirm before writing more than one page.** Say how many pages, which
department, and draft or published, and wait for a yes. Bulk tools (Create
Many, Publish Many, Tailor) also ask 1Brain's own confirm step: never tick
it for them.
5. **Never invent SOP content.** 1Brain never writes content: what goes in a
page comes from the owner's own words, documents or answers. Where a step is
missing, leave a clear gap and ask. Never fill it with a plausible guess.
6. **End every answer built from 1Brain with the page links** (each result's
`url`), so the person can check the source.
7. **Nothing found is an answer.** "I couldn't find a procedure for that in
your 1Brain" beats a made-up one. Offer to draft one from their words.
8. **60 requests a minute per person,** shared by every workflow and agent on
that person's connection. Prefer one list over many single reads; never
loop page by page over a whole account.
9. **Permissions are the person's own.** A connection sees and changes only
what that person can in 1Brain. Some actions (update, publish, share, add an
image to a page) only work on pages that person created.
10. **An agent can never see more than the person it answers to.** An agent
on its supervisor's credential is capped at that supervisor's access.
Never put an agent on a more senior person's credential to "give it more".
## 4. Writing an SOP or policy
1. Gather the owner's own material: their notes, a recording transcript, an
existing document, or answers to a few short questions.
2. Write the page as HTML in their voice (`awesomate_business` for the
business's name and voice). Mark anything you could not confirm.
3. Show it to them. Save it as a **draft** in the department they choose.
4. 1Brain may stop and ask for two things first: a **business description**
for the category (what the business does, who its customers are, where it
works; take it from the owner, never invent it) and **which template to
follow** (1Brain's SOP template or their own).
5. Publishing is a separate yes. Policies go to review rather than straight
to published.
## 5. Training and onboarding
Onboarding is about a person and the roles they are about to hold. Each role
on the business map can have a **1Brain course**, built from that role's 1Brain
systems; the business has one **starter course** for anyone joining (culture,
orientation, policies), built from one 1Brain Department or folder. Courses
live in 1Brain; the hub keeps their ids, never their content. Read
`features.onebrain_onboarding` in `awesomate_get_context` first: it can be off
while 1Brain is on.
- **`onboarding`**: each role's course (and whether its 1Brain systems changed
since it was built), the starter course, who checks training, and each
person's plan with quizzes passed and acknowledgements done. Owners only.
- **`build_course`** {slug} or {starter: true, projectId or folder}: builds a
**published** course in 1Brain on the 1Brain login of the person this key
belongs to, who must be a 1Brain owner or admin. Say so and confirm before
building. When the answer is `needsConfirm`, 1Brain found systems with no
quiz: tell the user which, and that those can only be checked by an
acknowledgement, or not at all. Build anyway (`confirmMissingQuizzes: true`)
only on their yes; otherwise offer to write quizzes with 1Brain's own
connector (2d). Rebuilding makes a new course; the old one stays in 1Brain.
- **`start_onboarding`** {email, starter?, roles?: [slug or {slug, intent}],
finishBy?} (`hats` is the old name for `roles`): gives the person a Task per course, linking their own onboarding
page. Nothing is written in 1Brain: the course must still be shared with
them there, and someone not yet in the business's 1Brain must be added there.
- **Readiness grants nothing.** Each morning the hub reads quizzes and
acknowledgements on one Owner's 1Brain (chosen in the hub, re-checked every
run). When a person has passed every quiz and done every acknowledgement on
a course, the hub gives their future manager a Task asking whether to hand
the role over; the map's own rules decide. Never change the map, or anyone's
access, because someone is ready, and never show one person's results to
anyone but the Owners and that person.
- **`set_reader`**: makes this key holder's own 1Brain the one that checks
training (they must be a 1Brain owner or admin there). Only when the owner
asks.
- **`check_onboarding`**: reads everyone's progress now (at most once every
5 minutes) instead of waiting for the morning run.
- **`link_member`** {planId, onebrainUserId | email}: when a plan says the
person is not found in 1Brain, match them to their 1Brain login (email is
the one they sign in to 1Brain with).
- **`close_plan`** / **`move_plan`** {planId, confirm: true}: stop a plan (the
person's Task goes too), or move one on an older course to the role's
current course (progress is read again from the new course). Each only on
the owner's yes.
- **`my_onboarding`**: the plans of the person this key belongs to: the
account owner, or a team member on their own key.
- Writing quizzes and acknowledgements, and sharing a course with a learner,
are 1Brain's own connector's work (2d), owners and admins only.
## 6. Known gaps (say so plainly)
- **Tags cannot be read.** 1Brain returns pages without their tags, and has no
way to list them. Tags can be added, not read back or removed.
- **Search cannot filter by tag** (or by department or folder). In a workflow,
use the node's Limit to Department or Limit to Folder instead.
- So the hub keeps each role's list of 1Brain systems itself
(`awesomate_onebrain` `systems_for_role`), and also writes the `job:<slug>`
tag. A tag someone added by hand in 1Brain is not on the role's list until it
is added with `link_role`.
- Tags cannot be removed over the connection, so taking a system off a role
leaves its tag in 1Brain.
- No deleting or moving pages, folders, departments or categories through any
route. That is done in 1Brain itself.
- Nothing can run as the business itself: every connection is a person.
## 7. When something goes wrong
| What they see | What it means | What to do |
|---|---|---|
| "1Brain access is switched off for you" | The 1Brain account's owner turned off Claude and automation access for them (or for the whole account) | Only that owner can turn it back on, in 1Brain's settings. Never reconnect to "fix" it |
| "Sign in again" / 401 | The connection has lapsed | Connect again in Settings, Integrations, 1Brain |
| A login page instead of data | The credential is not signed in | The same: connect again |
| "This 1Brain operation was retired" | An old (pre-Awesomate) 1Brain step | Open the node and pick a new operation (awesomate-n8n onebrain.md, old workflows) |
| "Your automations don't have the 1Brain node yet" | Their n8n is on an older version | Nothing to do; it arrives with the next update |
| Too many requests | The 60 a minute is used up across their workflows and agents | Wait a minute; spread the work out |
| Pages they expect are missing | Not shared with them in 1Brain, the wrong account, or the development-server note above | Check the account, then their access in 1Brain |