Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@heed How did orders in Norway change in October 2026?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Heed is a library of facts that AI agents read before they answer questions about your data. People write down what the numbers don't show, the owner of each domain checks it, and agents get only what was accepted, each fact with its source.
Quick start · How it works · Docs · Connect Claude Code · Contributing
Company data shows what happened to a number. It rarely shows why. A market closed, a tool changed how it counts, a partner's data came in late. People know this. An agent can't see it, so it guesses, and a guess can sound sure of itself.
Orders in Norway fell to almost nothing after 4 August.
Without Heed, an agent may blame weaker marketing and suggest you check the campaign budget. With Heed, it reads a fact: a new customs rule stopped all online sales to Norway from 4 August 2026, with a link to the notice, the owner who accepted it, and a line on what not to conclude.
An illustration of the difference, not a transcript. The demo data belongs to an invented outdoor-gear retailer that sells in twelve real countries.
Related MCP server: Marcora MCP Server
Write. Anyone writes a short fact: what happened, where it applies, from when, and how we know.
Review. The owner of the domain checks it. Four checks run first, so a change doesn't make answers worse.
Share. Once accepted, agents get it at once, in a new edition. Every change is dated and kept.
Use. Your agent asks Heed over MCP and gets the facts that apply, with sources.
Learn. When no fact applies, the question counts as a gap, without recording who asked.
Heed holds facts, not numbers. Cube defines your metrics and returns the figures; a fact points to them.
You need Docker, or Node 26 with npm.
git clone https://github.com/Fredehagelund92/heed.git && cd heed
docker compose up # the service with demo data: http://localhost:8080
npm ci && npm run dev # or the app on mock data, no database: http://localhost:5173Both open on the demo library of an invented outdoor-gear retailer: people, domains and facts, with their
history. Sign in as any demo person. Nothing leaves your computer, and no AI service is called. Stop with
Ctrl+C; docker compose down --volumes also removes the data.
With the service running (docker compose up):
claude mcp add --transport http heed http://localhost:3000/mcpThen run /mcp in Claude Code, choose heed, and choose Authenticate. Your browser opens Heed's sign-in;
choose a demo person and Allow. Ask "How did orders in Norway change in October 2026?"
Set up an agent has the details, the five-minute tour walks through the product, and docs/demo.md is the Norway story as a script.
Heed reads metric and dimension names from a Cube model, as files, and never writes to it:
CUBE_MODEL_DIR=/path/to/your/cube/model docker compose upWith your own model Heed starts empty, with no demo data. Sign in as Demo Administrator and add your domains in Administration. See the Cube connector.
Five kinds of fact. Event, note, guide, example and issue. Each says where it applies (metric, market, dates), links its source with one copied sentence, and says what not to conclude.
Owners, not a free-for-all. Every fact belongs to one domain, and that domain's owner accepts it. A high-risk fact needs a second yes from an approver. Nothing reaches an agent on its own.
Checked before it ships. Four checks run on every proposal, including test questions that must still find the right fact. Review a proposal.
Editions. Agents read a fixed, dated set of accepted facts. Compare two editions, go back to an earlier one, or stop one fact, one domain or everything at once. Editions.
An MCP server. Ten tools are on by default, such as Get facts for a question, Search facts and Report something missing; an admin can turn on two more. Agents sign in as the person and see only what that person can read. MCP.
No AI picks the facts. Rules choose what applies from the question's metrics, markets and dates, so the same question gets the same facts until someone accepts a change. Try a question shows exactly that.
Gaps. Questions that found nothing are counted by topic, so people write the fact that's missing. Heed never records who asked.
Stays in step with Cube. When a definition a fact relies on changes or disappears, the fact is flagged for its owner to check.
An assistant, Health and a history log. Ask the assistant to draft a fact, read Health to see what needs an owner first, and keep a history of every change for the admin and the auditor.
Instead of | What breaks | What Heed does |
A wiki or shared document | Agents can't see it, or read a page nobody has checked in a year | Short, dated facts with a source and an owner, delivered over MCP |
Notes in | One copy per tool, no review, no history | One library for every agent, with review, checks and a history |
Search over your documents | Returns text that looks like the question, with no owner or date | Returns the facts that apply to the metric, market and dates, or says none |
Your semantic layer | Defines the number, not why it moved | Sits beside it: Cube gives the figure, Heed gives the context |
Heed is not a data tool: it holds no numbers and runs no queries. It is not a wiki: every fact is short, has a source, and its owner checks it. It doesn't watch people: it counts questions by topic, not by person.
Use it | Run and build it |
Run and operate the service: setup and settings | |
The help pages are also the app's own Docs, at /docs. Requirements says what Heed must
do, and Writing a connector how to read another source.
Heed is pre-1.0. Expect rough edges and breaking changes.
It runs on one computer, or on one container host. Sign-in is the demo sign-in: anyone can be an admin, so keep it off the internet. Company sign-in is not built yet.
Claude Code is the agent that connects today. Other agents that use MCP need Heed at an address on the internet; see Set up an agent.
The demo runs on scripted mock models and spends nothing. The assistant and test runs can use Anthropic, directly or through Vercel's AI Gateway, chosen by an admin.
Built with TypeScript on Node 26, Fastify, PostgreSQL 18, React 19 and the official MCP SDK.
Open an issue first for anything bigger than a small fix, then send a pull request. CONTRIBUTING.md
says how, and npm run check runs the type check, lint, format check and unit tests. Please follow the
code of conduct.
Please report a security problem privately, through GitHub's private vulnerability reporting, not in a public issue. SECURITY.md says how and what happens next.
Apache License 2.0. You keep the copyright in your contributions.
This server cannot be deployed
Shared, permission-aware company context for AI agents, with provenance, approvals and audit.
A knowledge base of verified, dated facts your LLM would otherwise get wrong.
The context layer for your company's AI: your team's decisions, meetings and plans, with sources.
Shared business knowledge, tools and skills for AI agents, with citations and approval controls.
