Skip to main content
Glama
june-mcp

june-mcp

Official

june-mcp

Give your agent a memory. june-mcp is the official MCP server for Junê — it connects any MCP host (Claude Desktop, Claude Code, and friends) to a June knowledge graph, so your agent can ask, search, and remember against a shared, cited, tenant-isolated memory.

All retrieval, graph assembly and answering happen on the June endpoint you point it at; this package connects your agent to it.

Claude Desktop / Claude Code  ──stdio──▶  june-mcp  ──HTTPS──▶  your June endpoint
                                                                 (graph · retrieval · answers)

Install

pip install june-mcp          # just the connector   (or: pipx install june-mcp)
pip install june-ai           # umbrella: june-mcp + june-bench (the benchmark suite)
pip install "june-bench[mcp]" # the bench, with the connector as an extra

Related MCP server: knowledgeplane

Point it at a June endpoint

june-mcp speaks to any June service. Three ways to have one:

  1. Junê desktop app (local-first). Run the Junê app and connect to its local engine — your files, graph, and keys stay on your machine.

  2. Your own June service. Pro/Team customers running the june-local engine package point JUNE_BASE_URL at their own server.

  3. Hosted (Team). Point at your hosted June workspace endpoint with the API key from your console.

Configure

The server is fail-closed: it refuses to start unless it knows where to connect and as whom, and tells you everything that's missing in one message (not one error at a time).

env

required

meaning

JUNE_BASE_URL

✅

Your June endpoint, e.g. http://localhost:8000

JUNE_CANVAS

✅

The canvas (workspace) to bind this connection to — a name (work) or a canvas id. Names resolve to the id at startup; ambiguous names fail closed

JUNE_CANVAS_CREATE

optional

1 creates the named canvas on first run if it doesn't exist yet (refused in read-only mode)

JUNE_API_KEY

✅

Your June API key (JUNE_ALLOW_ANON=1 explicitly opts out for keyless local setups)

JUNE_LLM_KEY

optional

Bring-your-own LLM key for cited answers — forwarded per-request as a header, never logged, never stored on the service

JUNE_READONLY

optional

1 hides + refuses all write tools (memory becomes read-only)

JUNE_TOOL_PROFILE

optional

compact (default), full, or lean. compact folds 17 related tools into seven family tools that take an op — 20 tools listed instead of 37, 11,359 prompt tokens instead of 13,236 on a Pro read-write connection. Every call is dispatched to the same code as before, so gates, canvas rules, receipts and two-phase confirms are unchanged. Measured on four hosts before it became the default: Claude Code 1.000 task success (baseline 0.987), GPT-5.4 direct 0.983 (0.957), Codex 0.922 (0.763), zero unsafe erases on every arm. full lists the 37 members under their own names — the same code, one name each. lean exposes only the six verbs a coding agent uses (june_answer / june_context / june_search / june_remember / june_learn / june_usage) with a one-paragraph handshake, ~2.5k tokens — for sessions that only need to ask and remember

JUNE_FILES_ROOT

optional

Opt-in directory agents may upload files from via june_ingest_file — unset ⇒ that tool doesn't exist

JUNE_TIMEOUT_READ / JUNE_TIMEOUT_RETRIEVAL / JUNE_TIMEOUT_ANSWER

optional

Time budget per class of verb (defaults 15 s / 90 s / 120 s): fast reads; june_context, which scores every candidate; answers, which carry a model call

JUNE_TOOL_CONCURRENCY

optional

Max tool calls executing at once on this connection (default 8). Hosts pipeline requests over one stream; this is the explicit ceiling — excess calls queue, never stampede

JUNE_DOCS_CANVAS

optional

Canvas holding the agent docs (standing instructions/skills — see Agent memory below). Default agent_docs; created on the first june_doc_save

JUNE_DOCS_REFRESH

optional

0 disables the periodic standing_docs digest (default on — it's the anti-forgetting safety net)

JUNE_DOCS_REFRESH_CALLS / JUNE_DOCS_REFRESH_MINUTES

optional

Digest cadence: due every N tool calls (default 12) or M minutes (default 10), whichever comes first

JUNE_DOCS_DIGEST_CHARS

optional

Serialized digest size cap (default 2000)

JUNE_EXPORT_ROOT

optional

Opt-in repo directory the agent may export June pages/docs into as files (see Repo sync below) — unset ⇒ the three repo-sync tools don't exist

JUNE_EXPORT_GIT

optional

1 commits exactly the files each export wrote (pathspec-limited, never pushes)

JUNE_EXPORT_DIR

optional

Agent-docs subtree inside the root (default docs/agent)

JUNE_LOG_LEVEL

optional

Logging is stderr-only by design — stdout is the MCP wire

Check it before your agent does

JUNE_BASE_URL=http://localhost:8000 JUNE_API_KEY=... JUNE_CANVAS=work june-mcp --doctor

The doctor verifies, in order: config → service reachable → canvas resolution (your canvas name → its id, e.g. name "work" → 9147bee6-…) → search seam healthy → tool manifest, and prints PASS/FAIL per check with a mapped hint (e.g. a missing name lists the canvases that DO exist and points at JUNE_CANVAS_CREATE=1). The doctor exits 0 only when every check passes (1 otherwise); the server itself exits 2 on a config error instead of starting half-wired. Run the doctor first; it catches every common misconfiguration before your agent ever sees the server.

Wire it into Claude

Claude Desktop — merge into claude_desktop_config.json (Settings → Developer):

{
  "mcpServers": {
    "june": {
      "command": "june-mcp",
      "env": {
        "JUNE_BASE_URL": "http://localhost:8000",
        "JUNE_API_KEY": "your-key",
        "JUNE_CANVAS": "work",
        "JUNE_LLM_KEY": "your-llm-provider-key"
      }
    }
  }
}

Claude Code:

claude mcp add june -e JUNE_BASE_URL=http://localhost:8000 \
  -e JUNE_API_KEY=your-key -e JUNE_CANVAS=work \
  -e JUNE_LLM_KEY=your-llm-provider-key -- june-mcp

Fully restart the host (Cmd+Q on macOS), then check the server shows 20 tools — the compact surface, the default since 0.4.2. JUNE_TOOL_PROFILE=full lists the same capabilities as 37 individually named tools instead (38 when you opt into june_ingest_file via JUNE_FILES_ROOT).

The tools

The default surface is compact: 20 tools, seven of which group related operations behind an op argument. JUNE_TOOL_PROFILE=full lists the 37 members under their own names instead — same capabilities, same gates, same behaviour.

family tool

ops

folds

june_graph

neighborhood, subgraph, backlinks

june_neighborhood, june_subgraph, june_backlinks

june_maintain

enrich, resolve

june_enrich, june_resolve

june_page_read

list, get, removed, grammar

june_page_list, june_page_get, june_page_removed (+ the block grammar on demand)

june_page_edit

create, append, update, insert, move, rename, meta, restore

june_page_create, june_page_append, june_page_update, june_page_insert, june_page_move, june_page_rename, june_page_meta, june_page_restore

june_canvas_read

list, current, use

june_canvas_list, june_canvas_current, june_canvas_use

june_canvas_erase

clear, delete

june_canvas_clear, june_canvas_delete

june_docs_read

refresh, list, get

june_docs_refresh, june_doc_list, june_doc_get

Everything else keeps its own name: june_answer, june_search, june_enumerate, june_context, june_usage, june_remember, june_ingest, june_page_write, june_page_delete, june_canvas_create, june_doc_save, june_doc_delete, june_learn. A verb that can remove something is never folded in with one that cannot — so june_page_write and june_page_delete stay separate from june_page_edit, and each family carries one honest destructiveHint.

Old names keep working in your saved agent docs: the compact handshake carries the old-name → new-name map, and a call to a folded name is refused with the exact replacement (june_page_get is not a tool on this surface (compact): call june_page_read with op='get').

What each operation does:

tool

what your agent gets

june_answer

A grounded, cited answer from the graph — abstains rather than guesses

june_search

Ranked evidence for a query (supports multi-hop)

june_context

An assembled context pack under a token budget

june_neighborhood

The graph around one node

june_subgraph

A bounded subgraph export

june_backlinks

What links to one node (its incoming edges)

june_remember

Write a fact/note into the graph (becomes retrievable + citable immediately). Long texts run as an engine job: a result of {state: running, job_id} is collected with june_remember(job_id=…) — never re-send the text. Re-sending identical text cannot create duplicates

june_ingest

Structured node/edge ingestion

june_enumerate

Nodes matching a predicate for "list ALL X" questions (not top-k). Only exhaustive: true proves the list is complete; a short or empty result without it does not prove nothing else matches

june_ingest_file

Upload one local file (pdf/docx/xlsx/csv/html/md/images/audio) from the operator-approved folder — only exists when you set JUNE_FILES_ROOT

june_enrich

Pro: background re-extraction of the canvas with the richer engine (idempotent; job + poll; 403 on free)

june_resolve

Maintenance: merge duplicate entities via reversible same_as edges (runs server-side; strong_only=false unlocks the semantic tier on Pro)

june_docs_refresh / june_doc_list / june_doc_get

Read the agent's standing docs — full digest, registry listing, one doc's body

june_doc_save / june_doc_delete / june_learn

Write them — create/replace a doc or skill, two-phase delete, append one dated lesson

june_page_insert / june_page_move

Place new blocks after a named block, or reorder blocks by id — without resending the page (needs an engine with the positions page feature)

june_page_rename / june_page_meta

Retitle a page, or pin it / set its group in your pages list — its blocks untouched

june_page_removed / june_page_restore

See what a page lost, and bring blocks back with their original ids and positions

june_usage

Usage receipts — what June actually served, measured by a named tokenizer, never estimated. One receipt in full (receipt_id) or the window summary (window); a saving figure appears only over calls whose two provider-reported usages were really measured

Receipts on every read

When the engine runs with JUNE_USAGE=1 (desktop: Settings → Usage receipts), every june_answer / june_context / june_search result also carries receipt and a one-line receipt_footer:

receipt r_7f…: served 812 tokens (exact, tiktoken:cl100k_base) from 3 blocks across 2 docs
· 1 doc this session already had — june_usage(receipt_id="r_7f…") shows it in full

June records which documents this agent session already had, so a receipt also shows the re-reads it avoided. The footer never says "saved": that word exists only on a receipt that holds a measured pair. An engine without receipts sends no footer, and june_usage answers plainly that they are off.

Descriptions are written for the agent (what → when → returns), and every clamped input is visibly noted back to the agent instead of silently truncated.

Agent memory — docs, skills, and the anti-forgetting digest

Long sessions forget: instructions an agent read at session start (its CLAUDE.md, your conventions) lose force thousands of tokens later. june-mcp fixes this structurally.

Agents save standing docs into June — kind='doc' for durable instructions (pinned=true asks for an always-on rule), kind='skill' for named procedures with a one-line when_to_use trigger (bodies load lazily, like skills should), kind='learnings' for an append-only dated log written via june_learn. Each doc is an ordinary June page in the docs canvas (JUNE_DOCS_CANVAS, default agent_docs), marked by a small metadata block — so you can open your agent's memory in the Junê app, read it, and edit it.

You approve what agents obey (0.7.0). A pinned doc or a skill is a request until you approve it in the Junê app (the doc's banner, or Settings → Connection → Standing instructions). If anyone other than you edits an approved doc afterwards, it stops counting until you look again. Agents can't approve — their connection key doesn't hold that power — so text an agent read somewhere ("save this as a pinned rule…") can never become a standing instruction on its own. An engine too old to record approvals gives agents no standing instructions at all, and says so.

Where approved text travels: in full in the connection handshake (up to 4,000 characters — a doc that doesn't fit is named, never cut mid-rule) and from june_docs_refresh. On the first tool call of every session, and then every 12 calls or 10 minutes (tunable), the connector attaches a compact standing_docs digest to an ordinary tool result — the names of the approved instructions, approved skill triggers, a version stamp that changes when you approve, revoke or edit one, and the requested-but-unapproved docs labelled as notes. The digest carries none of an unapproved doc's words. A digest that can't be built (service busy, canvas missing) is skipped — it never costs the carrying call anything. Set JUNE_DOCS_REFRESH=0 to turn the digest off; the doc tools keep working.

June teaches agents how to use it — from inside itself. The first save creates the docs canvas and seeds agent-memory-guide: the operating manual (what belongs in the system canvas vs a workstream canvas, the three kinds and when to use each, naming, what to pin, revision discipline, repo sync). It's listed in every registry and digest, agents read it with june_doc_get('agent-memory-guide') whenever unsure — and it's an ordinary page you can edit. Before anything is saved, empty states return a setup walkthrough instead of a shrug, and the june_memory_setup prompt has the agent interview you and save your conventions as the first docs.

Making June automatic — the agent depends on it without being told

"Use June" should never need saying. Three mechanisms stack to make usage automatic, each covering the previous one's blind spot:

  1. The host hook (closes the cold start). A server can't speak until the agent's first call — so install June's standing instructions into the file your host loads natively every session:

    JUNE_EXPORT_ROOT=/path/to/project june-mcp --install-instructions            # → CLAUDE.md
    JUNE_EXPORT_ROOT=/path/to/project june-mcp --install-instructions AGENTS.md  # other agents

    It's written as a managed section (your own content is never touched; re-runs update it in place), and it puts the june-first posture — check June before claiming ignorance, remember facts unprompted, learn lessons as they happen — into the system prompt itself.

  2. Proactive tool descriptions (never decay). The core verbs' descriptions tell the model when to reach for them unasked — and descriptions are re-read on every single turn, in every MCP host, with no cooperation needed.

  3. The june-first posture in the handshake. June's own default posture is built into the connection's instructions (0.7.0; earlier releases seeded it as a pinned doc — an untouched seed is now hidden, an edited one is yours and needs your approval like any other).

What no MCP server can do — honestly — is force a host to act: an agent whose host hides SERVER_INSTRUCTIONS and has no instruction file and never makes one June call stays cold. Mechanism 1 exists precisely so that case never occurs in practice.

Repo sync — the repo stays current with what June knows

Opt in with JUNE_EXPORT_ROOT=<your repo> and three more tools appear:

tool

what it does

june_docs_export

Mirror every agent doc to docs/agent/<name>.md — the repo always holds the current standing instructions

june_page_export

Export any page to a managed file, or into a managed section spliced between markers inside an existing file (path=KNOWHOW.md section=june-learnings) — only the marked region is ever touched

june_page_import

The reverse: edit an exported file in your editor and import it back into its June page — agent docs keep their identity, and a stale file is refused rather than allowed to clobber newer knowledge

Safety rules, all enforced in code and pinned by tests: every path is fenced inside the root (lexical .. check and symlink resolution); a file not written by june-mcp is never overwritten; nothing is ever deleted; and with JUNE_EXPORT_GIT=1 each export commits exactly the files it wrote — pathspec-limited, so your staged work is never swept in, and push never happens. Exported files carry frontmatter and are byte-deterministic, so an unchanged doc re-exports to an identical file and git stays quiet.

The manifest (.june-export.json) makes currency checkable — two CLI modes for CI:

june-mcp --export         # sync agent docs + every managed page/section, commit if enabled
june-mcp --export-check   # write NOTHING; exit 1 if the repo has drifted from June

--export-check in CI turns "are the docs up to date?" from a hope into a failing build.

Free vs Pro — the june-pro tag

june-mcp is one package for everyone; there is no separate "pro build". Pro is a property of the endpoint, not the connector: connect to a Pro-activated June (a Pro license in the app, a Pro key on a hosted workspace) and the same tools carry Pro-grade results: every june_remember and june_ingest_file write runs the richer entity/edge engines automatically (the result reports which engine ran), june_resolve upgrades to semantic matching, and june_enrich backfills memories that were written on the free floor before you upgraded. The terminal shows which world you're in: --doctor prints an edition line and the server's startup banner tags the connection —

june-mcp: connected http://localhost:8000 canvas name "work" → 11d2… [june-pro]

The tag is read from the service's own /v1/whoami (the same entitlement state that gates Pro routes server-side), so it can't disagree with what you actually get — and it's display-only: entitlements are enforced on the service no matter what any client prints. Older services without /v1/whoami simply show no tag.

Security model

  • Your default canvas is fixed. Each connection starts on the canvas you set in JUNE_CANVAS, and no agent call can change it. A call acts in another canvas only when it names that canvas (canvas=), and every result says which canvas it landed in.

  • Destructive operations ask twice. Clearing or deleting a canvas, and deleting a doc, need a confirmation step; the default canvas cannot be deleted from a connection.

  • Isolation is enforced by the service. What a key can read and write is decided on the June endpoint, never by this connector.

  • JUNE_READONLY=1 hides and refuses every write tool.

  • Your BYO LLM key is sent with each answer request and is never stored or logged by the service.

Errors

Every upstream failure maps to a typed, redacted error payload (built from exception type + HTTP status only — never from response bodies), so the server survives anything the endpoint throws and your agent sees a clean, actionable message.

License

From 0.8.0, june-mcp is distributed as compiled wheels under the june-mcp End User Licence Agreement (shipped in the package as EULA.txt): free to use with Junê; no redistribution, modification or reverse engineering. Versions up to and including 0.7.0 were published under the MIT licence, and their terms are unchanged.

Available Tools

10 tools
june_answerA

Answer a question from June's shared knowledge graph — grounded in stored evidence, with citations, and it abstains rather than guessing when the graph doesn't know. Use when you want a finished answer to a factual question about remembered knowledge (people, projects, documents, decisions); use june_context instead when you want raw material to reason over yourself, and june_search when you only need ranked matching items. May take longer than other tools (it runs one LLM synthesis). Returns {answer, citations, used_edge_ids, degraded, mode}; an empty answer or 'abstain' in degraded means the graph has no grounded answer.

Inputs: query (required), limit, seeds, multihop, +2 more.

june_contextA

One call → a ready-to-use context pack: ranked evidence folded to canonical entities (aliases merged), trimmed to a token budget. Use when you want June's knowledge as raw material inside YOUR reasoning or a long draft; use june_answer when you want June to produce the answer itself. Returns {items[], budget, …} sized to token_budget.

Inputs: query (required), limit, seeds, max_items, +1 more.

june_enrichA

Pro: re-extract THIS canvas's existing artifacts with the richer engine, as a background job (idempotent — a second run writes 0 new). Use after a Pro upgrade to backfill memories that were written on the free floor, or after many june_remember writes. Call with no args to start (returns job_id; 409 if one is already running; 403 on free endpoints), then call again with {job: <job_id>} to check progress. Returns {job_id, state, total, processed, nodes, edges, errors}.

Inputs: job.

june_enumerateA

Exhaustive structured retrieval: return EVERY node matching a predicate (terms / regex / node_types / subtype) — not a top-k slice. Use for aggregation questions like 'list ALL customers/incidents/…' where june_search's ranked window could miss members; then reason over the complete list. Returns all matches up to cap (default 500).

Inputs: cap, regex, terms, subtype, +1 more.

june_ingestA

Advanced write: push explicit graph structure (node rows + edge proposals) exactly as given. Use ONLY when you already have structured nodes/edges with ids and kinds — for ordinary 'remember this' information, june_remember is the right verb (it extracts structure for you). Returns write counts.

Inputs: nodes, proposals, idempotency_key.

june_neighborhoodA

The 1-hop edges around one node — who/what connects directly to it. Use after june_search gave you a node_id and you want its immediate relations; use june_subgraph for multi-hop expansion. Requires node_id + node_type from a prior result. Returns {edges[], …}.

Inputs: node_id (required), node_type (required), limit, direction.

june_rememberA

Save new information into the shared graph by writing text: June extracts entities and relations server-side and links them to what it already knows (on Pro endpoints the richer entity/edge engines run automatically; the result reports which engine ran). Use when the user states a fact, decision, update or note worth persisting for later ('remember that…', meeting notes, a status change). Plain text or markdown, up to ~64k chars. Returns write counts — cite them, don't echo the text back. Prefer this over june_ingest unless you must write explicit graph structure.

Inputs: text (required), format, source_app.

june_resolveA

Maintenance: run cross-format entity resolution over the canvas — merges duplicate entities via reversible same_as edges (runs server-side, server-bounded scan). Default strong_only=true is conservative (deterministic signals only); pass strong_only=false to also use the fuzzy tier — which upgrades to SEMANTIC matching on Pro endpoints. Use once after a batch of june_remember/june_ingest writes, not per question; reads are already resolution-aware. Returns {same_as_written, groups, candidates}.

Inputs: strong_only, min_confidence.

june_subgraphA

Depth-N neighbourhood around a node (multi-hop expansion, bounded). Use to map a cluster of related entities around a known node; use june_neighborhood for just the direct edges. Requires node_id + node_type from a prior result. Returns {nodes[], edges[], …}; depth ≤ 3.

Inputs: node_id (required), node_type (required), depth, max_edges.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 10 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: answer, context, search, enumerate, neighborhood, and subgraph cover different retrieval modes; remember and ingest cover writing; enrich and resolve cover maintenance. No two tools overlap in function.

    Naming Consistency4/5

    All tools follow a june_<word> pattern using snake_case, which is consistent. However, some tool names are nouns (context, neighborhood, subgraph) rather than verbs, creating a slight inconsistency in grammatical form.

    Tool Count5/5

    10 tools is well-scoped for a knowledge graph server, covering reading, writing, and maintenance operations without being overly numerous or sparse.

    Completeness4/5

    The tool set covers CRUD operations reasonably well, with read, create, and update functionalities. However, there is no explicit delete tool, which is a minor gap for a complete lifecycle.

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      MCP server that gives AI agents and teams persistent, shared memory using a knowledge graph with vector embeddings, automatic consolidation of related facts, and hybrid search.
      3
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      A universal MCP server providing persistent, structured memory through a knowledge graph with graph storage, semantic vector search, and multi-hop traversal for AI agents and IDEs.
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A local-first compiled knowledge graph MCP server that provides structured memory for AI agents with full-text search, vector embeddings, and timeline tracking.
      215 npm
      8
      MIT