Basemouse Core

What basemouse/basemouse-core MCP server does

BaseMouse stores documents and notes for workspaces and agents, then exposes those records through MCP. The service is designed to provide structured context rather than returning isolated search matches: context packs can include citations, provenance, document versions, checksums, relevance information, truncation details, agent instructions, and document relationships.

The basemouse/basemouse-core MCP server also supports writes through upsert_document. Agents can persist decisions or session context under a stable ID, with idempotent behavior when content is unchanged. The underlying REST API preserves append-only revisions, supports document history, and uses tombstones for deletion.

How it works

Connect an MCP client to https://basemouse.com/mcp using stateless Streamable HTTP and JSON-RPC. The available tools are search, get_context_pack, and upsert_document. Search and context-pack retrieval support lexical or hybrid retrieval, along with type and tag filters.

Hybrid retrieval combines term overlap, one-hop graph expansion through document links, and a local hashed-feature vector signal. The vector calculation runs offline in Node and does not use an external vector database, paid embedding API, or network call. Results include per-signal retrieval details explaining why a document appeared. The vector component can be disabled with BASEMOUSE_VECTOR_RETRIEVAL=off while retaining lexical and graph retrieval.

Setup and configuration

Use the hosted MCP endpoint with an MCP client. Claude Code can be configured with an HTTP transport and an Authorization: Bearer bm_... header. The repository also includes a zero-dependency Node CLI that can print configuration for Claude Code, Cursor, Windsurf, Codex CLI, Gemini CLI, Grok CLI, AWS Kiro, and Google Antigravity. SSE-only clients can use the generated mcp-remote setup.

Unauthenticated MCP requests return HTTP 401 with a WWW-Authenticate header, but the public demo corpus remains available. Cursor Marketplace Connect can begin an OAuth flow; users can paste an existing BaseMouse key on the consent page or continue with the public demo. Config-file clients send the bearer header directly.

For self-hosting or local development, the repository provides a Node application, Dockerfile, Docker Compose examples, seed data, and local development commands. Without DATABASE_URL, it uses an in-memory seed store. With a managed Postgres connection, it provides durable storage for private workspaces; DATABASE_CA_CERT can supply a private certificate authority when required.

Tools and capabilities

• Search workspace documents with lexical or hybrid retrieval.
• Generate agent-ready context packs with citations and provenance.
• Upsert documents idempotently from an agent.
• Preserve document versions, checksums, and revision history.
• Follow outbound document links and resolved related records.
• Browse the public demo corpus without authentication.

Limitations and notes

The basemouse/basemouse-core MCP server is connected to a hosted service with paid plans, quotas, and authentication for private workspace operations. Anonymous access is limited to the public demo corpus. Hybrid vector retrieval is based on local hashed token features, not a semantic embedding model, so it should not be treated as equivalent to model-generated semantic search.

The repository includes additional REST endpoints, a web interface, Slack integration, import and workspace-sync scripts, and evaluation tooling. Those components are part of the broader project but are not additional MCP tools listed for the endpoint. Database-backed persistence requires configuration of the database connection; otherwise local operation falls back to in-memory seed data.