Connect the MCP server

Blenau speaks the Model Context Protocol (MCP). Once connected, your agent can search, read and write your knowledge base — backed by your GitHub repos — without you writing any glue code.

The recommended way to connect is @blenau/mcp: a small local server that your client launches over stdio and that keeps your credentials in your OS keychain — never a token sitting in a config file or a URL.

Recommended: @blenau/mcp (stdio + keychain)

@blenau/mcp runs locally and talks to api.blenau.com for you. Credentials never touch your client config: for a person they live in the OS keychain (Windows Credential Manager / macOS Keychain / libsecret) via a browser login; for an agent they’re injected at launch from your secret manager. It also never reads ~/.aws, ~/.ssh, *.env, or other clients’ config.

Install

npm install -g @blenau/mcp   # or just use npx (below) — no install

For a person (browser login)

1. Register the server with your MCP client. This config holds no secrets.

   // ~/.claude.json  (or run: claude mcp add blenau -- npx -y @blenau/mcp)
   "mcpServers": {
     "blenau": { "type": "stdio", "command": "npx", "args": ["-y", "@blenau/mcp"] }
   }

   Cursor (~/.cursor/mcp.json) and Claude Desktop use the same shape.

2. Log in once (device flow against Prysm:ID):

   npx -y @blenau/mcp login

   Open the printed URL, approve, done. The refresh token is stored in your OS keychain; access tokens stay in memory and are rotated before they expire. npx -y @blenau/mcp whoami shows who you are; … logout revokes and clears it.

For an agent / CI / cron (service token)

For unattended use, run in service mode with a native Blenau token (blenau_tk_…). It’s used directly as the bearer, so there’s no keychain and no login step. Keep it in a secret manager and inject it at launch — never hard-code it:

# e.g. with Secrevo:
secrevo run --secret BLENAU_AGENT_TOKEN -- npx -y @blenau/mcp

When BLENAU_AGENT_TOKEN is set the server uses service mode automatically. Get a token from the Blenau dashboard → Settings.

Alternative: remote HTTP endpoint (token in the URL)

If your client can’t launch a local process (a hosted/remote-only MCP client, or a third-party relay), Blenau also exposes a remote Streamable HTTP endpoint:

https://api.blenau.com/mcp/http/?token=blenau_tk_xxxxxxxx

You can pass the token as the ?token= query param or as an Authorization: Bearer blenau_tk_… header. Note the trailing slash on /mcp/http/.

Security note: this places a bearer token in the URL / client config, where the keychain path above keeps it out of both. Treat the token like a password, and prefer @blenau/mcp wherever your client can run a local process.

Get a token from the dashboard → Settings → MCP token (blenau_tk_…).

Legacy SSE (deprecated). The older https://api.blenau.com/mcp/sse?token=… endpoint still works but is being sunset — it forces a plaintext token in config and drops the connection on idle/restart (session_expired / -32001). Switch to @blenau/mcp (best) or the Streamable HTTP endpoint above.

Working across multiple workspaces

If your identity spans several workspaces, reads can roam across them and writes stay pinned to one — see Working across workspaces. With a single workspace (the common case) there’s nothing to configure.

What your agent can do

Tool	Purpose
search_knowledge	Semantic search across the workspace. Start here.
list_workspaces	List the workspaces your credential can reach. See Working across workspaces.
list_repos	List connected repos and their path_prefix (routing).
get_document / get_document_structure / get_section	Read docs and section versions.
ingest_document	Create a new doc (commits to GitHub). Don’t use it to modify existing docs — see Editing.
edit_section / patch_section	Edit an existing section’s body (optimistic locking — read get_section first). See Editing.
rename_section / delete_section	Rename a heading or remove a section — first-class, commit-backed.
create_asset_upload	Attach an image/file to a doc — see Images & assets.
crystallize_session / smart_crystallize	Turn raw session notes into structured docs.
audit_links / suggest_crosslinks	Keep the cross-link graph healthy.

After connecting, reconnect / refresh the tool list so the client picks up the latest tools. (Note: Google Antigravity uses serverUrl instead of url for remote endpoints.)

How a good agent behaves

1. Search first, write later. Run search_knowledge before creating anything.
2. If a result is a strong match, edit the existing section instead of creating a duplicate. Fetch get_section right before writing to pass the current expected_version.
3. Never re-ingest to modify. ingest_document is for new docs only. Re-ingesting an existing doc resets its provenance and can duplicate sections. Use edit_section to change a section.
4. Rename with rename_section, not edit_section. The heading is the section’s identity; edit_section changes the body only and rejects a body that starts with a different heading. See Editing.
5. Remember writes are commits. Editing a repo-backed doc commits to your repo (see How sync works).
6. Route by prefix. Call list_repos to learn each repo’s path_prefix and prepend it to the document path.
7. Cite sources. Pass a sources list whenever you record something learned from external material — unsourced claims show up in audit_links.

Troubleshooting

• Tools missing after a deploy / idle period → reconnect the MCP session; the tool list refreshes on reconnect.
• session_expired / session_invalid / -32001 → only happens on the legacy SSE endpoint when the stream is recycled (edge idle timeout, server restart). Switch to @blenau/mcp (stdio, no session to expire) or the Streamable HTTP endpoint (/mcp/http/) — both make this failure mode disappear.