CONTRIBUTING.md.
What you need
An MCP client, and the URL of an Isomorphic server. That is all. You do not need a GitHub account, a Cloudflare account, or anything installed locally. This guide uses claude.ai because it renders the in-conversation app; other MCP hosts get the same tools, and the same app runs in a browser tab on a multi-tenant deployment (/b/<brain>/).
Every Isomorphic server exposes MCP at /mcp on its own origin:
The
/mcp path is required. The bare origin returns 404.
Connect it to Claude
In Claude, open Settings → Connectors → Add custom connector, and paste the endpoint URL. For the hosted service:/.well-known/oauth-authorization-server, finds the registration_endpoint, and creates
its own credentials.
Claude then sends you through sign-in. On a server running the default configuration
(AUTH_MODE=oauth), that is an email magic link: enter your
address, open the email, click the link, and you are returned to Claude with the connector
active.
Use a private window if sign-in redirects somewhere unexpected. Auth.js stores a
callback-url cookie that persists between attempts and can steer a later sign-in back to
a stale one.
Your first brain
A brain is a GitHub repository full of markdown that holds your knowledge. You do not create it on GitHub, and you never have to open GitHub to use it. On the hosted service, signing in for the first time gives you your own organization automatically, with no invitation needed. You will not have a brain yet, so the first tool call you make replies:You don’t have a brain yet. Create one with the Add a brain button, or ask me to create a brain (e.g. “create a brain called Personal”).Either works. Asking Claude to “create a brain called Personal” runs
create_brain, which
scaffolds a fresh repository, makes it your active brain, and opens it. From there:
- “Add a page about X” writes a page.
- “Show me my brain” opens the viewer, with a file tree, editor, and link graph, inside the conversation.
- “What do I know about X?” searches it.
create_org with github: true, which has you install the Isomorphic GitHub App there),
then to connect the repository (connect_brain), which adopts it rather than scaffolding a
new one. See ops/onboarding-a-customer-org.md and
ops/adding-brains.md.
Connecting to your own instance
Identical, with your own origin:AUTH_MODE=static, the single-shared-token mode
described in Self-hosting: there is no sign-in step. Your client
sends a fixed header instead.
static mode
suits clients that let you set headers directly (Claude Desktop’s config file, the MCP
Inspector) rather than the claude.ai connector flow. For a self-hosted instance that other
people sign into, use oauth and give everyone their own identity.
Other MCP hosts
The endpoint is ordinary MCP over Streamable HTTP with OAuth, so any compliant host works, and the server never calls a model itself: the host brings the model. What varies by host is the UI, not the tools.
Claude Code:
When it does not work
The bare domain does nothing.https://mcp.isomorphic.sh returns 404. The endpoint is
https://mcp.isomorphic.sh/mcp.
A 401 from /mcp is correct when you have not signed in. That response is what
prompts Claude to start the OAuth flow. It is a problem only if it persists after
sign-in.
A new or renamed tool does not appear. claude.ai caches a connector’s tool list and
re-fetches only on a manual reconnect: Settings → Connectors → update tools. It does
not re-fetch on a new chat, and the server cannot push the change. Tool behavior changes
need no reconnect, since the signature is unchanged.
Sign-in lands somewhere unexpected. The sticky authjs.callback-url cookie above.
Clear cookies for the origin, or use a private window.
The app UI does not render. Claude sometimes declines to mount the iframe even when
the protocol exchange is correct. Test the same server against another host (the MCP
Inspector, VS Code Copilot) to tell a host problem from a server problem.
Tools fail with a permissions error. Reads need viewer, writes need editor, and
those roles are per brain: being in the organization does not by itself open a brain, since a
new brain is private to whoever created it. Ask an admin of that brain to check your access
with brain_access and change it with share_brain. members shows your role in the
organization, which is a different question.
Where to go next
- Self-hosting to run your own server.
../brain-template/AGENTS.mdfor the page conventions agents follow when writing your brain.../SECURITY.mdto report a vulnerability.- Discussions for questions, or an issue for a reproducible bug.