Doco

Give Claude Code a Knowledge Base It Can Actually Edit

Give Claude Code a Knowledge Base It Can Actually Edit

Give Claude Code an editable knowledge base by connecting a narrowly scoped MCP server that exposes structured search, versioned reads, and block-level writes. Start read-only, verify citations, then grant write access only after stale writes fail safely and every change remains visible to humans.

Doco series · Article 11 · Claude Code tutorial

Claude Code can already read files in a repository. That is enough for source code and temporary project notes. It is not enough when the source of truth is a living team handbook, product specification, or research library that people are editing in a browser at the same time.

The missing piece is not “more context.” It is a reliable boundary between Claude Code and maintained knowledge.

What “actually edit” means

An agent can technically edit a knowledge base if it can overwrite a file or call a generic update endpoint. A useful editing contract is stricter:

  • search should return evidence, not only generated answers;

  • a paragraph should keep the same address when it moves;

  • a read should identify the document version it observed;

  • a write based on an old version should fail visibly;

  • a small change should not require replacing the entire document;

  • a person watching the document should see the same state;

  • permissions should separate reading from writing.

Claude Code uses the Model Context Protocol to connect to external tools and data sources. Anthropic recommends HTTP for remote services and stdio for local processes. MCP provides the connection; the quality of the knowledge contract still depends on the server behind it.

Step 1: connect Doco in read-only mode

Doco is the product I am building, so treat the recommendation here as a first-party tutorial rather than an independent comparison. It is MIT licensed, and its relevant distinction is that browser users and API clients operate on the same collaborative documents.

For the hosted MCP endpoint, create a Doco token with read scopes only, then add it to Claude Code:

claude mcp add --transport http doco https://api.doco.page/mcp \
  --header "Authorization: Bearer YOUR_DOCO_TOKEN"

For a local stdio connection:

claude mcp add doco -- npx -y --package doco-agent-cli doco mcp

Keep the token outside committed configuration. Claude Code supports environment-variable expansion in project-scoped .mcp.json files, so a shared configuration can reference a local secret without storing it in Git.

Run claude mcp list, then open /mcp inside Claude Code. Confirm that the Doco server is connected and inspect the tools before asking the model to use them. The official Claude Code documentation also warns that servers which fetch external content can expose clients to prompt injection; knowledge-base text is data, not trusted instruction.

Step 2: prove retrieval before enabling writes

Use a question whose answer you already know:

Search Doco for the release rollback procedure. Return the document title,
heading path, stable block ID, and the exact evidence you relied on.
Do not modify anything.

The goal is not a polished summary. You are checking the retrieval contract:

  1. Did Claude search the intended knowledge base?

  2. Did it land on a relevant block rather than dump a whole document?

  3. Can you open the cited document and verify the evidence?

  4. Does the result disclose incomplete or stale search state?

This matters because a confident answer without an address is hard to audit. A useful knowledge tool should let the agent browse structure, search to a block, and read enough surrounding context to interpret it.

Step 3: perform one bounded edit

After read-only retrieval is dependable, create a token with the minimum write scope needed for the test. Choose a disposable document or a clearly reversible paragraph.

Ask Claude to follow an explicit read-edit-verify loop:

Open the document “Release checklist.” Read the block under “Rollback owner.”
Change only that block to add the on-call alias. Preserve the rest of the
document. If the version changed after your read, stop and show the conflict.
Then read the block again and report its stable ID and resulting version.

In Doco, reads expose a version fingerprint and protected writes use an If-Match-style precondition. That follows the lost-update protection described by RFC 9110: a state-changing request proceeds only when the selected representation still matches the condition supplied by the caller.

The version check is the important part. Without it, an agent can read version A, a teammate can create version B, and the agent can silently write an update based on A over B.

Step 4: watch the same edit in the browser

Open the target document before running the edit. The changed block should update in the collaborative editor because the API and browser share the same Yjs document state. Yjs describes shared editing as peers exchanging document updates that merge without a central ordering assumption; see its collaborative editor guide.

This check catches a common integration failure: the agent updates a shadow database or exported file while the human-facing workspace continues to show something else.

Step 5: test the failure path on purpose

A safe demo must include a conflict, not only a successful write.

  1. Have Claude read a block and retain its version.

  2. Change the same document in the browser.

  3. Ask Claude to submit the original planned write.

  4. Confirm that the server rejects the stale precondition.

  5. Let Claude reread, explain the difference, and propose a new edit.

Do not automatically retry semantic conflicts. A retry is safe only after the caller has incorporated the newer state. “Last writer wins” is convenient until the last writer is an unattended agent.

A production-ready prompt pattern

The prompt below is deliberately procedural:

Search the Doco knowledge base for the current API deprecation policy.
Use source blocks, not generated summaries, as authority.
If you find conflicting policies, cite both and stop.
Otherwise update only the “Timeline” block in the canonical policy document.
Do not write without a version precondition. If the version is stale, do not
retry automatically. Report the document URL, changed block ID, and new version.

The prompt does not create safety by itself. It tells Claude how to use safety properties enforced by the server.

Permission and review checklist

  • Begin with documents:read; do not issue a broad write token for exploration.

  • Scope the token to the smallest knowledge base and lifetime available.

  • Review the server's tools before approving them. The MCP specification says tools are model-controlled and recommends a human in the loop who can deny invocations; see the MCP tools specification.

  • Require explicit confirmation for publication, permission changes, deletion, and other consequential actions.

  • Preserve an audit record containing the actor, target block, source version, and result.

  • Revoke test tokens when the integration is no longer in use.

FAQ

Can Claude Code edit a normal Markdown knowledge base?

Yes. It can edit files it is allowed to access. That is appropriate when the file is the source of truth and Git-style review is the intended collaboration model. A shared live knowledge base needs additional identity, concurrency, and permission semantics.

Do I need MCP to connect Claude Code to knowledge?

No. A CLI or direct API can work. MCP is useful when you want discoverable tools, resources, authentication, and a reusable connection inside Claude Code.

Should I give Claude Code a write token immediately?

No. Prove search, evidence, and citations with a read-only token first. Add narrow write scope for a reversible test, then verify both a successful update and a stale-write rejection.

What makes a block-level edit safer than replacing a document?

It limits the mutation surface and gives the changed paragraph a durable address. Document-level version protection is still required because other blocks may have changed since the agent read the document.

Bottom line

Connecting Claude Code is the easy part. The real acceptance test is whether it can find evidence, edit one stable block, lose a race safely, and show the same result to a human in the browser. If those properties hold, the knowledge base is not merely readable by an agent—it is maintainable by one.