Docs · Koncept

Connect an agent

Koncept speaks MCP over streamable HTTP. There is nothing to install: the server is the deployment, and any MCP client can reach it.

1

Create a workspace

Sign in at app.usekoncept.com. There is no password: you get an emailed link, or sign in with Google or GitHub. A new workspace arrives with one small example model already in it.

2

Mint a key

Settings → API keys → Create. Give it a label you will recognise later, like Claude Code on laptop. The key is shown once and stored hashed, so copy it now.

3

Add the server

In Claude Code:

claude mcp add --transport http koncept \
  https://adamant-beagle-422.eu-west-1.convex.site/mcp \
  --header "Authorization: Bearer YOUR_KEY"

Any other MCP client works the same way: point it at that URL and send the key as a bearer token.

Or skip the key entirely

The deployment is also an OAuth 2.1 authorization server. Add it without a header and your client will open a browser, ask you which workspace to grant, and hold a token that acts as you. Revoke it any time from Settings → API keys → Connected agents.

claude mcp add --transport http koncept \
  https://adamant-beagle-422.eu-west-1.convex.site/mcp

Ask the server what it wants. The first tool worth calling is get_authoring_guide. It returns the conventions this product expects: when to create versus update, how to name an edge, and the quality checklist. An agent that reads it first produces models you do not have to rewrite.

Your first model

Ask for something you already understand, so you can judge the answer. A good first prompt names a domain and a size:

> Draw a concept model of our checkout domain.
> Eight concepts at most. Define each one. Put cardinality on every relation.

Then open it on the canvas and correct it. That correction is the point: the agent proposes a vocabulary, you decide what the words mean. Everything it writes lands in the same document you have open, so you watch it happen.

Two habits that make the difference. Ask the agent to call model_validate when it is done, which reports dangling edges, overlapping nodes, crossing lines and undefined concepts. And ask it to model_render, which hands it back a picture of its own work so it can see what you would see.

Models

A model is one diagram. There are two kinds, and the kind is fixed when it is created.

concept	The vocabulary a team shares. Labelled boxes, labelled relations, rules. This is the one you want unless you are drawing systems.
architecture	The same canvas with a shape vocabulary: rectangle, cylinder, hexagon, cloud, parallelogram, circle and diamond, for databases, external systems, actors and decisions. Shape is visual only; everything else behaves the same.

Concepts

A box is a concept. What makes it more than a box is what it carries.

label	The word itself. Order, Loyalty card.
definition	What it means, in prose, in one or two sentences. The single most valuable field in the product.
aka	The other names it goes by. Ticket for an order, Guest for a customer. This is where most misunderstandings actually live.
examples	Up to five concrete values, rendered in the margin beside the box. They keep an abstract picture anchored to something real.

Vocabulary is per model. There is no workspace-wide dictionary, on purpose: a shared entry that overrides a box means the box's own text rots the first time somebody edits one and not the other.

Relations

An edge says what connects two concepts. Label it with a verb that reads as a sentence: Customer places Order.

Cardinality

Each end can carry one of four values, drawn next to that end.

1	Exactly one.
0..1	None or one.
1..*	At least one.
0..*	Any number, including none.

No cardinality is not the same as one. An edge with nothing on its end means nobody has decided yet. Leaving it blank is a legitimate state, and filling it in with a guess destroys the information that it was open.

Rules

A rule is something the model must satisfy, and it is a first-class node, not an annotation. Drop one with the Rule tool, name it, state it in prose, and connect it to whatever it governs. Those connections draw dashed and arrowless, because a rule does not flow anywhere.

Cardinality says how many. A rule says what has to be true. Pay before we pour is not a number on an edge.

Zones and notes

A zone is a translucent background grouping with a title chip sitting on its border: a bounded context, a team's area, a phase. It always paints behind everything else, so it never gets in the way.

A text node is a free label on the canvas, for a heading or an aside that is not a concept.

Folders

Folders group models by topic in the navigator. They are organisation and nothing else: no permissions, no behaviour. Drag a model onto a folder to file it, or onto Unfiled to take it back out.

A folder is also the unit of publication. folder_export returns an entire folder as one document: every model rendered, plus a single merged glossary built from all of their concepts. That is how a set of related models becomes something you can hand to a wiki, a PDF or a repository.

An agent can file, but not create. Pointing a model at a folder that does not exist is an error naming the folders that do, never an auto-create. How your workspace is organised is your decision, not a side effect of a prompt.

Branches

A branch is how a shared model changes without a meeting. It is a full copy of the model at the moment you branch it, and it is a normal editable model: open it, draw on it, let an agent work on it.

1

Propose

Branches dropdown → New branch. Name the change, not the model: Add refund flow, not Orders v2. The name and the description are what a reviewer reads first.

2

Review

Anyone opens the branch and sees it on the canvas, because it is a model rather than a diff. Comments work on it like anywhere else.

3

Merge or abandon

Merge and the base takes the branch's current state; the branch is archived and marked merged. Abandon and it is archived with nothing carried over. Either way the history stays.

There is no draft, review or approved state anywhere in Koncept. Branches are the review mechanism, and a lifecycle on top of them would be a second answer to a question already answered.

Agents branch, but they do not merge on their own. The authoring guide tells them to merge only when you ask in so many words. Proposing is cheap; deciding is yours.

Comments

Threads anchor to the whole model, to one concept, or to one relation. A thread on a concept is the right place for the argument about what a word means, and it stays attached to that word.

Agents read and post in the same threads. With a persona on its key, an agent's reply is signed as itself rather than as the person who minted the key, which is the difference between a conversation and a puppet show.

Checkpoints

Marking a model good stamps a full snapshot of it, with who and when. Later you can restore to that stamp, and the restore is a real forward change you can undo, not a rewind that quietly resurrects deleted work.

A checkpoint gates nothing. It is a bookmark, not a state.

The tool surface

Twenty-eight tools, grouped by prefix. Everything below is role-enforced on the server: a key gets exactly the access the person who minted it has.

model_*	list, get, search, create, update, archive, render, validate
node_*	create, update, delete. A rule is a node, so these cover rules too.
edge_*	create, update, delete, including rewiring an edge without losing its identity
bulk_apply	an atomic batch, with references between items created in the same call
auto_layout	arrange a model. Never on an architecture view a person has arranged.
folder_*	list, and export a whole folder as one document
branch_*	create, list, merge, abandon
thread_*	list, get, resolve, and comment_post
my_role	what this key is allowed to do here
get_authoring_guide	the conventions, in the server's own words

model_render returns a real PNG by default, as an image block. An agent can look at the model it just drew, which catches the class of mistake no structural check will: two boxes that overlap, a line crossing a label, a diagram that is correct and unreadable.

Keys and personas

A key is scoped to one workspace and stored hashed. Revoking it takes effect immediately, and anything the agent already wrote stays, because it belongs to the workspace.

A key can carry a persona. Give one the name Claude reviewer and its comments are signed that way instead of with your name. It costs nothing and it makes a thread readable a month later.

An OAuth grant has no persona: it acts as the person who approved it, which is exactly right for a client you drive yourself.

Export and leaving

Settings → Danger zone → Export everything downloads the whole workspace as one JSON archive: every model, archived ones included, each wrapped in the same envelope a single model exports in. Any entry re-imports without a second tool.

It is the first card on that page rather than the last, because offering it after the delete button is offering it too late.

Production is snapshotted nightly and the restore path is the same one used to move the data there in the first place, so it is tested rather than assumed.

Everything, in one page.

Connect an agent

Create a workspace

Mint a key

Add the server

Or skip the key entirely

Your first model

Models

Concepts

Relations

Cardinality

Rules

Zones and notes

Folders

Branches

Propose

Review

Merge or abandon

Comments

Checkpoints

The tool surface

Keys and personas

Export and leaving