brainattic

brainattic MCP server

The knowledge base your AI reads and writes — under your rules.

Valuable knowledge gets scattered across private AI conversations, individual assistants and disconnected systems. brainattic gives people and AI agents a shared, persistent, governed knowledge base: one authoritative set of versioned documents, even when teammates use different AI clients. Human-defined permissions control access, rules guide how agents work, and revision history makes changes traceable and recoverable.

brainattic is not another AI chatbot, a chat-history archive, or a replacement for SharePoint, Git or your existing business systems. It holds the knowledge your team needs across them: decisions, procedures, customer context and project history. AI clients connect over the Model Context Protocol (MCP) to search, read and update it.

This repository documents the hosted brainattic MCP server: what it does, how to connect a client, and how to use it. It contains no server code. The service is hosted and operated by Finite Software Systems Ltd.

One knowledge base, every agent

Personal AI memory helps one person in one client. Shared knowledge lets the whole team build on a decision, correct it once and carry it into the next task without copying private chats or asking everyone to switch assistants.

Sales can work in ChatGPT, analysts in Claude, developers in VS Code with GitHub Copilot, and operations in Hermes. Each uses the same versioned knowledge, within their own permissions, while keeping their preferred tools and workflow.

Three distinct mechanisms keep that collaboration governed:

• Permissions enforce what each user and their connected agent may access or modify.
• Rules are human-authored instructions for how agents should work. They guide behaviour; they are not technically enforced access controls or a substitute for permissions.
• Revisions and auditability make changes traceable, support review, and let you recover earlier document versions.

We built brainattic at Finite Software Systems Ltd to close exactly that gap in our own work. See [One knowledge base, every agent](docs/team-workflow.md) for a change request followed from the customer call through analysis, implementation, testing and shipping, and for how a new team member gets up to speed in a single conversation.

What the server does

When you connect, your agent works inside your brainattic workspace with your own permissions. Each person signs in with their own account, so an agent can only reach what that person can.

The tools fall into these groups:

• Search and retrieval. Hybrid keyword and semantic search across documents, plus passage retrieval for grounded answers with citations.
• Documents. Create, read, list and update Markdown documents. Edits can be precise: open an edit session, apply changes in a batch, then commit or discard them.
• Revisions. Every saved change is a revision. List the history, read any past revision, and restore an earlier one.
• Rules. Human-written workspace, project and group instructions that agents should read before writing, to guide changes according to your team's conventions.
• Projects and groups. Organise documents, and archive or restore them.
• Attachments. Attach files and images to documents, and view them.
• Skills. Store reusable agent procedures as versioned skills with supporting files.
• Reminders. Set one-off or recurring reminders for workspace members.

Your client discovers the current tool list when it connects. Every tool carries MCP annotations (readOnlyHint, destructiveHint, openWorldHint), so clients can ask before running a tool that changes or deletes data.

Data security and hosting

Core customer data is stored and processed on infrastructure controlled by Finite Software Systems Ltd in Bulgaria, European Union. Finite Software Systems Ltd operates its own infrastructure, colocated in a Tier 3+ data centre in Sofia. The data-centre operator provides the physical facility and its access controls, with no logical access to customer data.

Customer workspaces have logical tenant isolation, role-based permissions and individual user authentication. Access is protected by TLS; MCP connections use OAuth-based authentication. Finite Software Systems Ltd uses segmented networks, firewalls, restricted administrative access, operational and security logging and monitoring, and regular backups on EU infrastructure under its control. Finite Software Systems Ltd strictly follows its documented ISO 9001 and ISO/IEC 27001 procedures.

brainattic does not independently forward customer documents to third-party AI models. Your chosen AI client can receive content you explicitly request through the connector, subject to your permissions and that client's own policies. EU hosting does not determine where your AI provider processes that content. Optional integrations, such as Slack reminders, can also involve transfers outside the EEA; the published policies describe these and other limited exceptions.

For the published security measures, data-handling details and contractual commitments, see Security, the Privacy Policy and the Data Processing Agreement.

On-premises deployment

Finite Software Systems Ltd is ready to offer on-premises brainattic deployment for organisations that need the knowledge base on their own infrastructure, with control over where it runs and how it is operated. Each deployment is planned customer by customer: we work with you to agree the requirements, scope, integrations and delivery timeline.

A pilot-first approach can validate feasibility and practical value before moving to your on-premises solution with Finite Software Systems Ltd. Talk to us about your needs and the right deployment path for your organisation.

AI clients and integrations must also meet your data-handling requirements; hosting the knowledge base on-premises alone does not control where those services process content.

Requirements

• A brainattic account and access to a workspace. Sign up if you don't have one.
• An MCP client that supports remote Streamable HTTP servers with OAuth.
• A browser for the one-time sign-in.

Setup

Every client uses the same URL: https://app.brainattic.ai/api/mcp. On first use the client opens a browser window. Sign in to brainattic and approve access. You never paste a key or a secret.

VS Code (GitHub Copilot)

Add the server to .vscode/mcp.json in your project, or to your user configuration with the MCP: Add Server command:

{

"servers": { "brainattic": { "type": "http", "url": "https://app.brainattic.ai/api/mcp" } } }

Start the server from the file or the MCP view, complete the sign-in, and the brainattic tools appear in Copilot's agent mode.

Claude (claude.ai and Claude Desktop)

Open Settings → Connectors → Add custom connector. Name it brainattic, paste the URL and connect. Claude walks you through the sign-in.

Claude Code

claude mcp add --transport http brainattic https://app.brainattic.ai/api/mcp

Then run /mcp inside Claude Code and choose brainattic to sign in.

ChatGPT

Open Settings → Connectors, add a custom connector with the URL above and complete the sign-in. Custom MCP connectors need a ChatGPT plan that supports them.

Cursor

Add to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project):

{

"mcpServers": { "brainattic": { "url": "https://app.brainattic.ai/api/mcp" } } }

Mistral Vibe

A workspace administrator opens Connectors, clicks + Add Connector → Custom MCP Connector, names it brainattic and pastes the URL. In a chat, enable brainattic under Tools.

Gemini CLI

gemini extensions install https://github.com/rutash/brainattic-gemini-cli

Then run /mcp auth brainattic inside Gemini CLI.

Any other MCP client

Point the client at https://app.brainattic.ai/api/mcp (Streamable HTTP). OAuth 2.1 is discovered from the server, as the MCP authorization specification describes. An unauthenticated request returns 401 with a bearer challenge that tells the client where to sign in.

Using it

brainattic works best as a conversation. Your agent proposes, you adjust and approve, and the agent carries it out. Everything it writes is saved as a revision you can inspect or roll back. The steps below are a good first session.

1. Start with the workspace rules

Rules are short, human-written conventions that your agent reads before it writes. Examples are the language to write in, date formats, naming, status words, and what must never be written down (secrets, credentials, personal data). Each workspace comes with a workspace rules document from day one, so your first question should be:

"What rules apply before writing in this workspace? Read them and explain them to me in plain words."

If the rules are filled in, the agent summarises them and explains how it will follow them. If they are still empty, it tells you so, which is your cue for step 2.

2. Adapt the rules to how you work

Shape the rules in conversation instead of writing them from scratch:

"Suggest workspace rules for us: language, date format, document naming, status vocabulary and

a never-write-down list. Base them on how I work. Draft them for my review and don't save anything yet."

Push back, add, remove and refine until the draft fits. Then say *"Save these as the workspace rules."* Workspace rules need an admin role. Editors can set rules for a project or a group, and an admin can also edit any rules in the web app under Admin → Rules. From the next write on, every connected agent reads the approved rules, not just the one you talked to.

3. Ask how brainattic fits together

Ask the agent to explain the model using examples from your own work:

"Explain how workspaces, projects, groups, documents, rules and skills relate in brainattic.

Use examples from my own work."

The short version:

4. Ask how to put brainattic to use, in the context of your work

Your agent already knows a lot about you: earlier conversations, the projects you've di