# Set up morigraph

You (the assistant reading this) are setting up **morigraph**: one MCP gateway to
connected services, persistent memory, workspace context, shared files, and team
skills. **Do not assume morigraph is already connected.** Connect and authenticate
it if needed, then ask the user whether to save the routing rule and skill below
in the host. If they agree, make these saves even when morigraph's tools are not
available in the current session.

The standalone skill is available at [SKILL.md](/SKILL.md). Use this setup guide
for connection and authentication before installing the skill.

## Step 0 — Connect and authenticate the MCP server

This step does **not** require any morigraph tools. A missing morigraph entry in a
connector directory or tool registry is not a dead end: add a **custom remote
MCP server** using its URL.

### Choose the correct endpoint

Use the origin of the setup page you are reading, with `/mcp` as its path. Keep
dev and production separate; do not silently replace one with the other.

| Setup page | Remote MCP server URL | morigraph console |
|---|---|---|
| `https://joinbrainlet.com/setup.md` | `https://joinbrainlet.com/mcp` | https://joinbrainlet.com/app |
| `https://dev.joinbrainlet.com/setup.md` | `https://dev.joinbrainlet.com/mcp` | https://dev.joinbrainlet.com/app |
| `https://dev.morigraph.com/setup.md` | `https://dev.morigraph.com/mcp` | https://dev.morigraph.com/app |

For another morigraph instance, use that setup page's own origin plus `/mcp`.
If the user pasted this text without a source URL or environment preference,
use `https://joinbrainlet.com/mcp`.

morigraph was previously called Brainlet. Name new server connections
`morigraph`. Keep any existing connection named `brainlet` and the installed
skill key `brainlet` for compatibility; do not add a duplicate connection or
skill when upgrading. The transport is **Streamable
HTTP**, and hosted morigraph uses **OAuth**. The console and `setup.md` are not MCP endpoints. Use
the host's OAuth discovery flow; do not invent an API key, manually construct an
authorization URL, or ask the user to paste credentials into chat.

### Check what this host can do

Inspect the current host's available tools and MCP configuration. If morigraph is
already configured, do not add a duplicate connection. If its tools are already
callable, they can be used for the morigraph-side saves below. Continue with the
host's own saves either way.

If morigraph is absent, use this host's supported MCP-install action, settings UI,
or CLI when available. The user's request to install morigraph authorizes its
configuration; follow the host's own permission rules. A shell running in a
remote sandbox does not necessarily configure the user's chat application.
Use the path that actually controls the current host, not a different app's CLI.

If you cannot operate those settings, give the user the exact link, MCP URL,
and next action below. Say that a host-side connection or sign-in is needed,
not that setup depends on unavailable `memory_write` or `skills_write` tools.

### Install in the current host

**Claude chat / Claude Desktop:** open
[Claude Connectors](https://claude.ai/customize/connectors), choose **+ → Add
custom connector**, name it `morigraph`, and enter the selected MCP URL. Leave
optional OAuth client ID/secret fields blank for morigraph's normal discovery
flow. Add it, then choose **Connect** to begin authentication. Enable the `morigraph` connector
for this conversation in **+ → Connectors** if it is not already enabled. If
organization policy prevents adding a connector, identify the specific admin
step needed rather than retrying unavailable tools.
[Claude connection instructions](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp)

**Claude Code:** if this is the user's local Claude Code environment, inspect
`claude mcp list` first. If no matching server exists, run the following with the
selected endpoint (the example is production; use the dev URL when reading the
dev setup page):

```sh
claude mcp add --transport http --scope user morigraph https://joinbrainlet.com/mcp
```

Then use `/mcp` inside Claude Code, select `morigraph`, and complete authentication.
If `/mcp` is a user-operated command in your host, give the user that exact next
step. Reconnect or start a fresh session if the tools do not refresh.
[Claude Code MCP instructions](https://code.claude.com/docs/en/mcp)

**Codex CLI:** inspect `codex mcp list` first. In the local environment used by
Codex, add the selected endpoint if absent, then start OAuth login:

```sh
codex mcp add morigraph --url https://joinbrainlet.com/mcp
codex mcp login morigraph
```

Use the dev URL in the add command when reading the dev setup page. Complete the
browser login, then refresh/restart the host if necessary. For an app or IDE
whose settings you can operate, its MCP server settings are also a valid path;
do not assume a CLI in an unrelated sandbox controls that app.
[Codex MCP instructions](https://developers.openai.com/codex/mcp)

**Other MCP hosts:** use the host's supported **Add custom MCP server** flow with
the selected URL, Streamable HTTP, and OAuth. Use the host's actual settings or
installation tool; do not invent menu paths or claim you installed a connector
merely because you opened its console.

### Finish authentication

Let the user complete sign-in and the morigraph consent screen in their browser,
including account/workspace selection when offered. If sign-in or account setup
is required first, open the console on the **same origin**, then resume the
host's Connect/authentication flow. Console login alone does not authorize the
MCP host. Do not handle passwords, copy browser cookies, or bypass consent.

The host's login flow may report success before its morigraph tools appear in the
current session. Continue to the steps below regardless. If sign-in is
still pending, report that status accurately; do not claim authentication
succeeded without confirmation from the host.

## Steps 1–3 — Ask, then save the routing rule and skill

**Ask the user first.** Steps 1 and 2 change what this assistant does in later
conversations, so they are the user's choice. Ask once, in a line or two, for
example:

> Should I save a short morigraph rule to my memory and install the morigraph
> skill? It's highly recommended: it's how I'll know to check morigraph in new
> conversations without you having to mention it. morigraph's tools work either
> way.

If they agree, do steps 1–3. If they decline, skip to step 3, and do not ask
again in this conversation.

1. **Save the routing rule in the host's native persistent store.** If
   morigraph's `memory_write` is already callable, save it there too. If it is
   unavailable, do not delay the native save. Save the rule, not this whole page:

   > I asked you to save this rule when I set up morigraph. morigraph keeps my
   > shared memory, context, files, and skills available across assistants. Use
   > them when prior knowledge or team workflows are relevant: check morigraph
   > before assuming my preferences, asking me to paste a document, or starting
   > a recurring task, and save to it when I ask you to remember something.
   > Save information that needs to be shared in morigraph. For other durable
   > information I want retained, save to both morigraph and your native persistent
   > store when both support it, unless I choose one destination. Follow my choice
   > of tools for connected services and paid capabilities.

2. **Save the morigraph skill in the host — verbatim.** It is printed below
   (under "The morigraph skill"), so you never have to fetch a second
   file. Copy that fenced block *exactly as written* — the `---` front matter
   included — into your skills folder, e.g. `.claude/skills/brainlet/SKILL.md`
   or your harness's equivalent. If morigraph's `skills_write` is already
   callable, register the same skill there too, with `mode: "conversational"`
   and `outputs: [{"name": "result", "kind": "document"}]` (every morigraph skill
   declares how it runs). Do not delay the local save when
   that tool is unavailable. Don't rewrite it: its `description` is the routing
   hook your harness loads first, so it has to stay exact.

3. **Tell the user** what you saved and where, in one or two lines, or, if they
   declined, that nothing was saved and they can ask you to set it up later. Identify
   morigraph-side saves that could not yet be made because its tools are not
   available. If the host has no native persistent memory or writable skills
   folder, state that limitation. Never claim to have written to a store or
   folder you cannot access.

---

## The morigraph skill

When the user has agreed in Steps 1–3, save everything between the fences
below **verbatim** — the `---` front matter included — as your morigraph skill
file (`.claude/skills/brainlet/SKILL.md`, or your harness's equivalent), and register the same skill in morigraph with
`skills_write`, passing `mode: "conversational"` and
`outputs: [{"name": "result", "kind": "document"}]`. Do not rewrite or summarise
it; the `description` is the routing hook, so it has to stay exact.

````markdown
---
name: brainlet
description: >-
  morigraph keeps memory, workspace context, shared files, and team skills available across
  sessions and assistants, and exposes services the user enabled through one MCP connection.
  Read from it when earlier user or team knowledge is relevant. Write information that needs
  to be shared to morigraph: short facts with memory_write, documents with files_write, and
  procedures with skills_write. For other durable information the user wants retained, save
  to both morigraph and the host's persistent store when both support it, unless the user
  requests one destination. context_get reads workspace context; its editor is in morigraph's
  dashboard/API. Follow the user's choice of tools for connected services and paid capabilities.
---

# Use morigraph

morigraph was previously called Brainlet. The installed skill key remains
`brainlet` for compatibility with existing hosts; do not create a duplicate skill.

morigraph keeps the user's and team's memory, workspace context, shared documents,
and procedures available across sessions and assistants. It also exposes services
the user has enabled through one MCP connection. Use its stored knowledge when
that knowledge is relevant, and save information there when it needs to be shared.

## What it fronts

- **Memory** — durable facts, preferences, decisions: `memory_search`, `memory_write`.
- **Context** — who you're working with and the current workspace: `context_get` reads it. Workspace context is edited through morigraph's dashboard/API; use `memory_write` for a short durable fact or `files_write` for a longer shared document when that is the appropriate form.
- **Files & docs** — shared team documents: `files_search`, `files_read`, `files_write`, and `files_link` for a public, expiring URL to one file (an image a host can only show by link). `files_read` returns text, an inline image, or raw bytes.
- **Skills & procedures** — how this team does recurring tasks: `skills_route`, `skills_list`, `skills_get`, `skills_write`. Each skill declares how it runs (mode, the inputs it needs, the outputs it must produce): `skills_get` shows it, so collect those inputs and produce those outputs, and `skills_write` requires it. A morigraph share link (`…/s/<id>`) is someone else's skill: preview it with `skills_import`, and import only after the user agrees (`confirm: true`).
- **Connected Account** — a downstream service the user has enabled in morigraph (GitHub, Google, Grafana, filesystem, git, fetch, Playwright, custom). Each appears as ONE `conn__<service>` tool that lists what it can do and returns a tool's input schema; it runs nothing. Find a specific tool with `tools_search` (exact name, input schema, and whether it only reads) and run it with `tools_invoke` (`conn__<service>__<tool>`).
- **Included capabilities** — web search, image generation and the like, supplied by morigraph without a vendor account; usage runs on the workspace's morigraph credits: `web_search`, `image_gen`, … Every one is listed whether it is on or off; `tools_search` finds them too (legacy API kind `managed`, with ON/OFF and price). Call an ON one directly by name when the user chooses it; if they choose one that is OFF, tell them the price before a workspace admin switches it on with `managed_enable`. `managed_status` reports state, prices and the credit balance.

## When to use it

When prior context or a connected capability could help:

- **Starting a non-trivial task** (writing code, drafting, reviewing, making a
  recommendation) → `context_get` once at the start of the session, before
  asking the user questions it may already answer. Later facts come from
  `memory_search`, which is much cheaper.
- **About to assume something about the user** (which package manager or cloud,
  how they like PRs written, who their teammates are, what they already
  rejected), or about to ask something they may have answered before →
  `memory_search` first.
- **Recurring or team-shaped work** (a code review, a release, a migration, a
  customer reply, a bug triage; "how do we deploy", "our review checklist")
  → `skills_route` before improvising, or `skills_list` to browse.
- **A document, spec, or past decision is needed** ("the Q3 plan", "we have a
  doc on that") → `files_search` / `files_read` before answering from memory or
  asking the user to paste it.
- **The user asks you to remember, note, or save something** → save it with
  `memory_write` (a short fact) or `files_write` (a document) rather than only
  acknowledging it; an acknowledgment alone is gone when the conversation ends.
- **You and the user just worked out how something should be done**, or a skill
  you followed was wrong → offer to save or correct it with `skills_write`.
- **A service enabled in morigraph is needed** → its `conn__<service>` tool or
  `tools_search` to find the tool, then `tools_invoke` to run it. If the user
  chose another available connection, follow that choice.
- **Live web, an image, video, or audio is needed** → morigraph's `web_search`,
  `image_gen`, `video_gen`, and `audio_gen` are available when enabled. If a
  comparable host tool is also available and the user has not chosen, ask which
  they want; use morigraph when they choose it or no comparable host tool exists.
  If the user chooses a morigraph capability that is OFF, quote the price and ask
  an admin to enable it.

If morigraph is unavailable when a shared save is needed, say that it was not
saved there and ask the user to reconnect it. Other available tools can still
serve tasks that do not depend on morigraph's shared data.

## Save shared knowledge and keep persistent stores in sync

When memory, a file, a procedure, or standing context needs to be shared across
people or assistants, save it in morigraph. Use the store that fits the content:

- **Short facts and decisions** → `memory_write`.
- **Documents and longer context** → `files_write`.
- **Reusable procedures** → `skills_write`.
- **Standing workspace context** → morigraph's dashboard/API editor. `context_get`
  is read-only; if no editor is available, use `memory_write` or `files_write`
  for the appropriate shared content and explain where it was saved.

For other durable information the user wants retained, write to both morigraph
and the host's built-in persistent store when both support that kind of content.
This keeps a copy in morigraph for later sessions. If only one store is available,
say where the information was saved. Follow an explicit destination choice:
"shared only" means morigraph; "just locally" means the host's own store.

UX categories: **Included** means morigraph supplies access; **Connected Account** means the user connects their own service. Credit usage is separate: X is a Connected Account and some of its tools consume credits. Included does not mean free or unlimited. Existing `managed_*` tool names remain stable.
````

## Final step — Start a new session

morigraph tools added during this setup will not be available until a new session.
End setup here. The saved native routing rule and skill will be available in that
session; any morigraph-side saves that were unavailable here can be completed then.