june-mcp
Officialjune-mcp connects MCP hosts to a June knowledge graph for cited retrieval, memory writes, graph exploration, and maintenance.
Ask grounded, cited questions with
june_answer; it abstains rather than guesses.Search the graph with fused lexical, dense, and graph ranking via
june_search.Retrieve exhaustive lists with
june_enumerate(not just top-k).Build prompt-ready, token-budgeted context packs with
june_context.Explore entities via
june_neighborhoodand bounded multi-hopjune_subgraph.Persist knowledge:
june_rememberfor free text (server extracts structure) orjune_ingestfor explicit nodes/edges.Maintain and upgrade the graph: Pro re-extraction with
june_enrich, duplicate resolution withjune_resolve.Also supports agent standing docs/skills, canvas-bound isolation, read-only mode, BYO LLM keys, usage receipts, repo sync, doctor checks, and compact/full tool profiles.
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., "@june-mcp search for notes on the product launch meeting"
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.
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 extraRelated MCP server: knowledgeplane
Point it at a June endpoint
june-mcp speaks to any June service. Three ways to have one:
Junê desktop app (local-first). Run the Junê app and connect to its local engine — your files, graph, and keys stay on your machine.
Your own June service. Pro/Team customers running the
june-localengine package pointJUNE_BASE_URLat their own server.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 |
| ✅ | Your June endpoint, e.g. |
| ✅ | The canvas (workspace) to bind this connection to — a name ( |
| optional |
|
| ✅ | Your June API key ( |
| optional | Bring-your-own LLM key for cited answers — forwarded per-request as a header, never logged, never stored on the service |
| optional |
|
| optional |
|
| optional | Opt-in directory agents may upload files from via |
| optional | Time budget per class of verb (defaults 15 s / 90 s / 120 s): fast reads; |
| 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 |
| optional | Canvas holding the agent docs (standing instructions/skills — see Agent memory below). Default |
| optional |
|
| optional | Digest cadence: due every N tool calls (default 12) or M minutes (default 10), whichever comes first |
| optional | Serialized digest size cap (default 2000) |
| 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 |
| optional |
|
| optional | Agent-docs subtree inside the root (default |
| 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 --doctorThe 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-mcpFully 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 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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 |
| A grounded, cited answer from the graph — abstains rather than guesses |
| Ranked evidence for a query (supports multi-hop) |
| An assembled context pack under a token budget |
| The graph around one node |
| A bounded subgraph export |
| What links to one node (its incoming edges) |
| Write a fact/note into the graph (becomes retrievable + citable immediately). Long texts run as an engine job: a result of |
| Structured node/edge ingestion |
| Nodes matching a predicate for "list ALL X" questions (not top-k). Only |
| Upload one local file (pdf/docx/xlsx/csv/html/md/images/audio) from the operator-approved folder — only exists when you set |
| Pro: background re-extraction of the canvas with the richer engine (idempotent; job + poll; 403 on free) |
| Maintenance: merge duplicate entities via reversible |
| Read the agent's standing docs — full digest, registry listing, one doc's body |
| Write them — create/replace a doc or skill, two-phase delete, append one dated lesson |
| Place new blocks after a named block, or reorder blocks by id — without resending the page (needs an engine with the |
| Retitle a page, or pin it / set its group in your pages list — its blocks untouched |
| See what a page lost, and bring blocks back with their original ids and positions |
| Usage receipts — what June actually served, measured by a named tokenizer, never estimated. One receipt in full ( |
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 fullJune 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:
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 agentsIt'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.
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.
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 |
| Mirror every agent doc to |
| Export any page to a managed file, or into a managed section spliced between markers inside an existing file ( |
| 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=1hides 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 toolsjune_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_searchA
Fused retrieval over the knowledge graph: lexical + dense + graph signals in one ranked list. Use when you need matching items (nodes/snippets with scores and provenance) — e.g. to find entities or check what the graph holds on a topic; use june_answer for a finished cited answer, june_context for a prompt-ready pack. Returns {items[], degraded_lanes, …}.
Inputs: query (required), limit, seeds, 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
Scored across 10 tools
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.
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.
10 tools is well-scoped for a knowledge graph server, covering reading, writing, and maintenance operations without being overly numerous or sparse.
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
Persistent memory, knowledge graph, task management and more for AI agents via MCP.
Hosted MCP server for live public-data APIs and Skills for AI agents.
Agent-native MCP server over the public saagarpatel.dev corpus. Read-only, stateless.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceLocal MCP server for indexing personal knowledge into SQLite with hybrid search, chunk-level citations, memory tools, and agent orchestration.4MIT
- FlicenseNot gradedqualityDmaintenanceMCP 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-
- AlicenseNot gradedqualityCmaintenanceA 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.1MIT
- AlicenseNot gradedqualityDmaintenanceA local-first compiled knowledge graph MCP server that provides structured memory for AI agents with full-text search, vector embeddings, and timeline tracking.215 npm8MIT