docs(mcp): point users at the official everos-mcp server

[gloryfromca]

Summary

EverMind now ships an official MCP server, everos-mcp, which works against a self-hosted EverOS through EVEROS_BASE_URL. This repo did not tell anyone: the README still pointed at the community evermemos-mcp project (Cloud-only), and nothing in the CLI hinted that MCP clients can connect.

• New docs/mcp.md: prerequisites, uvx everos-mcp setup for Claude Code / Codex / JSON-configured hosts, the seven tools and the endpoints they call, and the behaviour specific to a self-hosted server (no session delete yet, ~1 s index lag after saving, trajectory quality gate).
• docs/index.md lists the page; README and docs/use-cases.md swap the community card for the official package.
• everos init ends with a third step pointing at the guide; everos server start logs the uvx everos-mcp line with the right EVEROS_BASE_URL.

Refs #483 for the missing delete endpoint.

Area

• Architecture method
• Benchmark
• Use case
• Documentation
• Developer experience
• CI, build, or release

Verification

make lint            # ruff, import-linter, datetime discipline, openapi check — OK
make test            # 2618 passed, 4 skipped
make docs-check      # OK
make check-assets    # OK
make check-file-sizes
make check-commits RANGE=origin/main..HEAD
everos init --root <tmp>              # prints the new step 3
everos server start --root <tmp>      # logs "MCP clients: uvx everos-mcp with EVEROS_BASE_URL=http://127.0.0.1:8000 (docs/mcp.md)"

# Guide contents checked against a live run (2026-10-10, macOS):
# everos server start on a temp root + `uvx everos-mcp` over stdio via the
# mcp 1.x client -> all seven tools answered; forget_session reported the
# missing delete endpoint instead of failing; search/list found the memory
# ~0.5 s after add_memory(wait=true) returned.

make integration was not run: the change is documentation plus two informational CLI lines.

Checklist

• I kept the change scoped to the relevant area.
• I am opening this from a separate branch, not pushing directly to main.
• I updated docs, examples, or setup notes when behavior changed.
• I added or updated tests when the change affects behavior. (The two new CLI lines are informational; the existing everos init output test still passes and no new assertion was added.)
• I did not commit secrets, .env files, dependency folders, or generated output.
• Active relative links in Markdown files resolve.

Notes for Reviewers

• make check-cjk reports 10 pre-existing hits (README badge lines, use-case samples, a TUI demo string); none are in files this PR touches.
• The README card reuses the banner from the EverOS-MCP repository README.

🤖 Generated with Claude Code

[dani1005]

Thanks, this fills a real gap: the repo never mentioned the official MCP server, and the README still pointed at the Cloud-only community project. The guide itself reads well.

Three things I'd fix before merging, because they mislead users directly (details inline):

1. The startup hint builds EVEROS_BASE_URL from the bind host, so 0.0.0.0 and :: produce URLs clients can't use.
2. docs/mcp.md is referenced as a relative path from the CLI. The wheel only packages src/everos, so pip/uvx installs don't have the file.
3. The tool table names POST /api/v2/memory/delete, which doesn't exist on this server.

Smaller suggestions:

• The MCP hint is logged before uvicorn binds, so on "address already in use" the log first says "connect here" and then reports the failure. Emitting it after a successful bind (lifespan/startup) avoids that.
• Neither the new init step nor the server hint has a test. An assertion on the hint text, plus the URL it renders for a non-default host and port, would have caught (1).
• The MCP card is now duplicated word for word in README.md and docs/use-cases.md, differing only in the link path. The old cards had already drifted ("With" vs "with"), so it may be worth keeping one source.

[dani1005]

host_resolved is the bind address, not a client address:

• --host 0.0.0.0 logs EVEROS_BASE_URL=http://0.0.0.0:8000. That isn't a valid target on Windows or from another machine, which is the usual reason to bind 0.0.0.0.
• --host :: logs http://:::8000, which isn't a valid URL.

Suggest mapping wildcard binds (0.0.0.0, ::) to 127.0.0.1 (or a <host> placeholder) and bracketing IPv6 literals. Also (docs/mcp.md) should be the absolute GitHub URL, same as in init_cmd.py.

[dani1005]

After pip install everos / uvx everos there's no docs/ on disk: the wheel only packages src/everos (pyproject.toml, [tool.hatch.build.targets.wheel]). The path is also resolved against whatever directory the user is in. Please use https://github.com/EverMind-AI/EverOS/blob/main/docs/mcp.md.

[dani1005]

This server has no /api/v2/memory/delete route; the API mounts add/flush/search/get plus the ome, knowledge and cascade routers. Anyone using this column as an API reference gets a 404. Suggest "not available on self-hosted (#483)" here instead of naming an endpoint.

[dani1005]

Same claim as EverMind-AI/EverOS-MCP#3, which I've suggested changing: either wait=true waits for indexing, or one conservative latency statement is used everywhere (search_memory currently says "the last minute"). Worth keeping this line in sync with whatever lands there, or phrasing it generically ("shortly after saving; list_memories shows new entries sooner").

[dani1005]

Optional: this table and the self-hosted behaviour section mirror the everos-mcp README, but everos-mcp releases on its own schedule, so they'll go stale silently when a tool is added or renamed. Consider keeping only what's EverOS-specific (prerequisites, base URL, self-hosted gaps) and linking to the everos-mcp README for the tool list.

[gloryfromca]

Thanks — all three must-fix items are in the latest commit, plus most of the smaller ones:

1. Client URL: new mcp_base_url(host, port) maps wildcard binds (0.0.0.0, ::) to 127.0.0.1 and brackets IPv6 literals; the hint prints that instead of the bind address. Parametrized test covers the five cases from your comment.
2. Guide path: both hints now use https://github.com/EverMind-AI/EverOS/blob/main/docs/mcp.md (shared MCP_GUIDE_URL).
3. Nonexistent endpoint: the tool table is gone from docs/mcp.md; the page now lists the tool names, links the everos-mcp README for the tool list and protocol, and keeps only the self-hosted specifics. forget_session points at memory: add POST /api/v2/memory/delete so everos-mcp forget_session works on self-hosted servers #483 instead of naming a route.

Smaller ones:

• Latency wording: now "shortly after saving", no number, matching the direction in EverOS-MCP#3.
• Tests: added for the URL mapping, the logged hint (captured on the everos.cli.server logger), and the init step.
• Hint before bind: kept it before uvicorn.run, reworded as "once up, …". uvicorn's lifespan startup also runs before the sockets bind, so moving it there would not change the ordering on "address already in use"; the only post-bind hook is uvicorn's own "running on" log.
• README / use-cases duplication: left as is — every card in README mirrors docs/use-cases.md today, so a single source would be a separate change across all of them.

[dani1005]

Thanks, all addressed. Agreed on the hint placement and on leaving the card duplication for a separate change. I pushed one small doc fix (5c598ca): the tool paragraph said all seven tools are backed by this server's endpoints, but forget_session isn't yet, so it now points at the section below.

[dani1005]

LGTM.