# Exocortex Mcp > Remote MCP server for an exocortex vault — query your compiled knowledge and capture to its inbox from claude.ai, the Claude app, or any MCP client - **Type:** MCP server - **Install:** `agentstack add mcp-alexhagemeister-exocortex-mcp` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [AlexHagemeister](https://agentstack.voostack.com/s/alexhagemeister) - **Installs:** 0 - **Category:** [Security](https://agentstack.voostack.com/c/security) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [AlexHagemeister](https://github.com/AlexHagemeister) - **Source:** https://github.com/AlexHagemeister/exocortex-mcp ## Install ```sh agentstack add mcp-alexhagemeister-exocortex-mcp ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # exocortex-mcp [](https://github.com/AlexHagemeister/exocortex-mcp/actions/workflows/ci.yml) [](https://github.com/AlexHagemeister/exocortex-mcp/releases) [](LICENSE) [](https://ko-fi.com/V1N723QW1K) Remote MCP server for an [exocortex](https://github.com/AlexHagemeister/exocortex) vault — your compiled knowledge, reachable from claude.ai, the Claude mobile app, and any MCP client, wherever you are. **Companion component, not a requirement.** The vault works fully without this server. What it adds is the away-from-desk loop: query your wiki mid-conversation on your phone, and capture thoughts that land in your vault's normal ingest pipeline — the driving use case is talking to Claude while out, with your exocortex along for the ride. ## What it does Three tools, preserving the vault's single-pipeline rule in infrastructure: | Tool | Kind | What it does | |---|---|---| | `query_wiki` | read | Status-weighted search over `wiki/` — `verified` pages rank above `draft` (×1.5 vs ×1.0), matching the vault's "readers weight by status" invariant. | | `get_page` | read | Fetch any repo-relative file (or list a directory). | | `capture_to_inbox` | **the sole write** | Writes a frontmattered markdown source into `sources/inbox/` via a dedicated `inbox-drops` branch. | Nothing here can edit your wiki, your notes, or your sources — captures enter through the same gate as everything else, and your vault's maintainer files them on the next `process-inbox` run. ## How it fits ``` claude.ai / Claude app / Claude Code ──HTTP──▶ exocortex-mcp (your cloud host) │ clone + pull (read) │ push inbox-drops (write) ▼ your vault's private GitHub repo ▲ │ daily vault-snapshot │ (commit + pull --rebase + push) your local vault (the working copy) ``` - **The data source is your vault's git remote**, not the live working copy — the private repo you set up in the program's SETUP step 4. Staleness is bounded by your snapshot cadence; with the default daily snapshot that's accepted by design. - The server keeps a shallow working clone under `DATA_DIR/mirror`, pulling at most every `SYNC_INTERVAL_SECONDS`. ## The capture return path Captures go through a dedicated branch, never directly to `main`: 1. The server commits each capture to the **`inbox-drops`** branch (based on `main`, so `origin/main...inbox-drops` is exactly the pending captures) and pushes it. 2. On the machine that has the vault, [`scripts/consume-inbox-drops.sh`](scripts/consume-inbox-drops.sh) copies pending captures into the vault's `sources/inbox/` and force-resets the branch to `main`. Run it from your snapshot routine, or by hand. 3. From there the vault's normal ingest pipeline takes over. Why a branch: it keeps `main` single-writer from your own machine — no push races between the server and your snapshots — and remote surfaces stay on the inbox pipeline. A side store outside git was rejected to keep one data path and one credential. ## Auth claude.ai custom connectors currently support **OAuth 2.1** (heavyweight for a personal server) or **no auth**; there is no static-header option in the connector UI. This server ships a middle path: - A single shared secret, `EXOCORTEX_TOKEN` (`openssl rand -hex 32`), compared timing-safely. - Accepted as `Authorization: Bearer ` — for Claude Code (`claude mcp add --transport http exocortex /mcp --header "Authorization: Bearer "`) and the API's MCP connector. - Also accepted as a secret URL path segment — `https:///t//mcp` — which is what you paste into the claude.ai custom-connector dialog (**treat that URL as a credential**). This is personal-server auth: one user, one secret. If your deployment ever becomes multi-user, the upgrade path is a proper OAuth 2.1 authorization server per the MCP auth spec. ## Deploy your own (Railway, ~10 minutes) Any Node host works; Railway is what the reference deployment uses. 1. Create a **fine-grained GitHub PAT** scoped to your vault repo *only*, with **Contents: Read and write** (write is needed for `inbox-drops` pushes). 2. New Railway service from your clone of this repo. Nixpacks detects Node; it runs `npm run build` then `npm start`. 3. Set variables: - `MIRROR_REPO_URL=https://x-access-token:@github.com//.git` - `EXOCORTEX_TOKEN=` 4. Note the service's public domain, then add the connector in claude.ai: **Settings → Connectors → Add custom connector** with `https:///t//mcp`. The clone lives on the ephemeral filesystem and is re-cloned on each deploy — fine, since your git remote is the source of truth. ## Monitoring `GET /healthz` is shallow liveness. `GET /healthz/deep` is the monitoring endpoint: it exercises the mirror sync and inspects the `inbox-drops` backlog, returning 503 when sync fails or captures sit undrained for more than 36 hours (two missed nightly consumer runs). One probe therefore catches process-down, sync-broken (bad PAT, GitHub unreachable), and consumer-not-running. It exposes counts and ages only, never vault content. [`.github/workflows/healthcheck.yml`](.github/workflows/healthcheck.yml) probes it every 15 minutes; set the `HEALTHCHECK_URL` repository **secret** to your deployment's `/healthz/deep` URL and GitHub emails you on failure (a secret so your endpoint stays out of publicly readable run logs; the probe skips quietly when it's unset, so forks don't get failure spam). Caveats: cron runs can be delayed, and GitHub pauses scheduled workflows after ~60 days of repo inactivity (it emails first — one click keeps it alive). ## Local development ```sh cp .env.example .env # point MIRROR_REPO_URL at a local vault path, set a token npm install npm run dev ``` Smoke test: ```sh curl -s localhost:3000/healthz curl -s localhost:3000/mcp \ -H "Authorization: Bearer $EXOCORTEX_TOKEN" \ -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' ``` ## Design notes - Data source is the vault's git remote (clone + pull), not a live mount; snapshot-bounded staleness is accepted. - Three tools; `capture_to_inbox` is the only write, and it writes to the inbox, not the wiki. - One data path, one credential: everything rides the vault repo and one scoped PAT. ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [AlexHagemeister](https://github.com/AlexHagemeister) - **Source:** [AlexHagemeister/exocortex-mcp](https://github.com/AlexHagemeister/exocortex-mcp) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** yes - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** yes - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-alexhagemeister-exocortex-mcp - Seller: https://agentstack.voostack.com/s/alexhagemeister - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.