AICortex MCP server

In 30 seconds: AICortex is one container on your own hardware that every AI you use connects to.

• It remembers who you are, how you work and what you're building — and hands that to Claude, ChatGPT or a local model at the start of every chat, on desktop and phone.
• It reaches your stuff — services, devices, mail, calendars, files — with the secrets in an encrypted vault the model never sees.
• It keeps your schedule: tell your AI "tomorrow at 8: summarise yesterday's notes". AICortex stores the job and at 8 wakes your Claude (or asks ChatGPT, an API key or a local Ollama) to do it.

AICortex is a self-hosted MCP server that turns your NAS into a personal LLM connector: a persistent "brain" your assistant loads at the start of every session. Any MCP-capable LLM — Claude, ChatGPT, or a fully local model — gains a durable identity and real reach into your own services and devices, while running inside your network. Non-MCP tools (n8n, LangChain, your own scripts) reach the same brain through a native REST API with scoped per-user keys — and humans get a built-in admin WebUI at /ui for the vault, skills, users and audit log.

The model stays in its provider's cloud (or runs locally). Your memory, skills and secrets stay on your NAS. The assistant talks to AICortex over an HTTPS connector; the server uses your local credentials internally and never hands them to the model. New capabilities are added as data — a skill, a service config, a secret — with no redeploy.

Highlights

🧠 A brain that travels with you

• One short cortex_start call — who you are, how you work, and the current project's notes, open tasks and last session (a few hundred characters; cortex_catalog has the full list)
• Self-learning, typed memory with a review queue, so it grows without polluting itself
• A skill router — search your skills, load only what's needed, author new ones at runtime
• Playbooks — multi-stage work where a person approves each stage's artifact (e.g. Anthropic's AI-native SDLC: intent.md → spec.md → plan.md …), bundled as a template — see docs/playbooks.md
• The same brain across models, desktop and mobile — one account, one state

🔌 Real reach — every integration is just data

• Email (SMTP send + IMAP read), calendars (CalDAV), HTTP services, MQTT & FTP/FTPS devices, WebDAV cloud, SSH/SFTP
• IPP printing & eSCL scanning (straight into Paperless-ngx) on LAN multifunction devices
• Event-driven: inbound webhooks (POST /hooks/<name>, secret/HMAC-verified) turn external events into inbox items; outbound webhooks notify
• An MCP gateway to use other MCP servers' tools — register any integration with one call, no code, no redeploy

🌐 Beyond MCP — drive it over plain HTTP

• A native REST API: every tool as POST /api/v1/tools/<name> with an auto-generated OpenAPI 3.1 spec — plug AICortex into n8n, LangChain, an OpenAI-compatible client or a shell script, no MCP client required
• Per-user API keys: scoped (default-deny), hashed at rest, rate-limited, optional expiry — and a key runs the same per-user areas as an OIDC session, never admin by default

🖥 Built-in admin WebUI — no terminal needed

• Every signed-in person manages their own notes, scheduled jobs and playbook runs (and approves playbook stages) at /ui; admins also get the vault (secret names only — values are write-only), skills, users & roles, services & devices editing and the audit log — language-switchable DE/EN
• Same SSO as the connector (OIDC + PKCE against your IdP, e.g. Pocket ID), CSRF-guarded, fully self-contained (strict CSP, no CDNs, no build step) — served by the same container, no extra service
• Every page takes the same policy path as the MCP tools, so the browser never gets more than the person's AI
• See it in screenshots

👥 Team, autonomy & continuity

• A presence-aware multi-agent board: live presence, capability-routed task pull, context-preserving handoff
• Cross-LLM session handoff — resume exactly where another model or device left off
• Cron-as-data scheduling with per-user act-as: a scheduled job runs confined to its owner's area, via a short-lived per-job token — never a standing god-token
• Runners carry the jobs out — AICortex wakes your Claude (a Claude Code cloud task on your plan) with the due job, or asks your ChatGPT plan, an API key or a local Ollama; each person sets up their own in the WebUI and gives each job its runner, no extra container (how)

🔒 Secure & multi-tenant

• Your own OIDC login and roles (admin / user / viewer) — one switch, AUTH_ENFORCE; only the operators you name are admin, everyone else signs in as user
• Per-user isolation and capability areas: private memory + vault per person, plus default-deny service/skill allow-lists an admin assigns — so not everyone may use every tool
• An encrypted secret vault whose tokens only go to the hosts they're bound to, an SSRF egress guard that pins every hop to a checked address, and capability checks that fail closed — end-to-end on your hardware, including a local model (Ollama)
• OAuth with a redirect allow-list and consent page, rate limits on sign-in, token and webhook endpoints, HSTS, and an image that is scanned before it ships

How it works

LLM app — any MCP client (desktop / mobile)  ·  one or many agents
        │  custom connector / MCP server (HTTPS, from the model's cloud)
        ▼
Reverse proxy (Zoraxy / Caddy / nginx / Traefik …)
        │
        ▼
AICortex  (this container, on your NAS)
        │  uses local files & secrets
        ▼
Memory · Skills · HTTP services · MQTT & FTP devices · WebDAV cloud · Workspace files
   · SSH/SFTP · SMTP + IMAP email · IPP printing · eSCL scanning · MCP gateway · Inbox/Tasks
   · Sessions · Cron · Secret vault   (every outbound call passes the SSRF egress guard)

How AICortex differs

The "LLM brain" space has some great projects — AICortex deliberately sits in a different spot:

• GBrain is a memory engine — markdown-first, Postgres/PGLite-backed, with a self-wiring knowledge graph and hybrid/vector search. Deep retrieval, one concern.
• CortexPrism is a full agent operating system — its own runtime, ~30 LLM providers, a plugin marketplace, sandboxed code execution and multi-user teams. Batteries included, heavyweight.
• AICortex is a single, lightweight MCP connector: one container that gives any client a persistent brain — memory and skills, devices, sessions, secrets and scheduling — where new integrations are added as data, no redeploy. And unlike most brain projects it isn't MCP-only: the same tools are exposed over a native REST API with an auto-generated OpenAPI spec, so non-MCP clients (n8n, LangChain, a script) plug in too. No database, no graph, no marketplace; you bring your own client.

Rule of thumb: want a dedicated memory/graph engine → GBrain; want a batteries-included agent OS → CortexPrism; want a minimal self-hosted connector that plugs your existing LLM app into your own stuff → AICortex.

Try it in 5 minutes

Just want to look around? Run it on your own computer — no NAS, domain or login needed, only Docker:

echo "STORAGE_ENCRYPTION_KEY=$(openssl rand -base64 32 | tr '+/' '-_')" > aicortex.env
docker run -d --name aicortex -p 127.0.0.1:8787:8787 --env-file aicortex.env \
  -e ALLOW_INSECURE=1 -v aicortex-data:/data ghcr.io/ikarusmk/aicortex:latest

1. Open http://localhost:8787/ui — the WebUI, already signed in as admin.
2. Connect an AI that runs on the same computer. Claude Code: claude mcp add --transport http aicortex http://localhost:8787/mcp, then ask it to call cortex_start. Other local clients: docs/clients.md. The Claude and ChatGPT apps connect from their provider's cloud, so they need the real setup.
3. Tell it something about you, or "tomorrow at 8: summarise yesterday's notes" — it shows up under Notes and Scheduled jobs. A job runs once you add a runner with an API key (OpenRouter's free models work); waking Claude needs your own login, so that, too, is the real setup.

⚠️ No login in this mode. ALLOW_INSECURE=1 switches authentication off: whoever reaches the port is admin. Keep the port on 127.0.0.1 as above, keep real secrets out, and never run it like this on a server. For everyday use, follow the Quick start with your own login.

Done looking? docker rm -f aicortex && docker volume rm aicortex-data && rm aicortex.env removes it with all its data.

Requirements

• A NAS or server running Docker (Compose v2).
• A reverse proxy serving the container over public HTTPS (cloud-hosted LLM clients connect from their provider's cloud, so the endpoint must be reachable from the internet; a purely local client can reach it on the LAN).
• A domain/subdomain pointing at your proxy.
• An MCP-capable client that supports custom connectors / MCP servers (Claude, ChatGPT, or any MCP client).

Quick start

🤖 Installing with an AI coding agent? Point it at INSTALL_FOR_AGENTS.md — it walks the agent through the whole install and verification, handing the human-only steps (DNS, proxy, OIDC) back to you.

git clone git@github.com:IkarusMK/AICortex.git
cd AICortex
cp .env.example .env        # adjust PUID / PGID / HOST_PORT / TZ
docker compose up -d --build

The MCP endpoint is served at http://<host>:8787/mcp.

Prebuilt image (no local build): a multi-arch image is published to GHCR by CI. In docker-compose.yml, comment out build: ., uncomment image: ghcr.io/ikarusmk/aicortex:latest, then docker compose pull && docker compose up -d.

Updating from 1.x: pull the new image and restart with the same data/ folder and .env — there is no migration step. Connected apps stay signed in; memory, skills, vault, services, tasks, sessions and API keys carry over. What changes is listed in CHANGELOG.md.

🔐 Updating to 2.6.0 (security release)? Pull and restart as usual — your data stays. But read Upgrading to 2.6.0 first: one setting may need a change, everyone signs in once more, and each app asks for consent once.

Expose it & add the connector:

1. Point a subdomain (e.g. agent.example.com) at your reverse proxy.
2. Proxy that host to http://<nas-ip>:8787 over HTTPS — the upstream is plain HTTP, so do not enable "TLS to upstream". If your proxy geo-blocks, allow your LLM provider's egress region. The published port binds to 127.0.0.1 by default (only this host's proxy reaches it, not the LAN); a host-network proxy uses http://127.0.0.1:8787, a bridge-network proxy needs BIND_ADDR=0.0.0.0 (or a shared Docker network).
3. In your MCP client: add a custom connector / MCP server → URL https://agent.example.com/mcp. Agents and CLIs that can only send a header (Claude Code, Codex, Hermes, OpenClaw, LM Studio, …) use a per-agent key instead — setup for every client: docs/clients.md.
4. Test: ask the assistant to call cortex_start. The briefing starts with AICortex v<version>; on a fresh install it is short because the memory is still empty. (ping works too, but it is not among the eleven tools clients see up front.)

Authentication & authorization

AICortex separates authentication (who may connect) from authorization (what they may do). Set up the login once, then pick your mode with a single line in .env.

1. Authenticate with your own OIDC provider

Exposing the connector publicly requires OAuth. AICortex uses your own identity provider as the login backend — Pocket ID, Authentik, Keycloak, Auth0, anything with standard OIDC discovery. FastMCP's OIDC proxy handles the MCP-side OAuth 2.1 flow (Dynamic Client Registration + PKCE); your provider does the actual login.

Variable	Example
OIDC_CONFIG_URL	https://id.example.com/.well-known/openid-configuration
OIDC_CLIENT_ID / OIDC_CLIENT_SECRET	from a client you register in your provider
BASE_URL	https://agent.example.com (this server's public URL)
JWT_SIGNING_KEY	openssl rand -hex 32

Register the OAuth client in your provider with redirect URI <BASE_URL>/auth/callback, then (re-)add the connector in your client to be sent through the login.

🟣 Using Pocket ID? Follow the click-by-click Pocket ID setup guide — creating the OIDC client, the exact .env, and optional groups → roles.

ℹ️ Don't put reverse-proxy SSO / forward-auth in front of /mcp — an MCP connector is a machine client and can't follow an interactive login redirect. Authentication belongs at the MCP layer, which is exactly what this does. When the OIDC variables are unset, /mcp accepts bearer tokens only (per-agent keys and RUNNER_TOKEN); ALLOW_INSECURE=1 turns all auth off for local testing.

2. Pick your mode — one line in .env

	🏠 Homelab	🏢 Enterprise
For	one trusted person (you)	several people on one brain
Tool access	everyone gets every tool	roles: admin / user / viewer
Data	one shared brain	per-user memory + private vault
The line	AUTH_ENFORCE=0	AUTH_ENFORCE=1 (default)

🏠 Homelab — keep it simple

AUTH_ENFORCE=0

Every authenticated caller gets every tool — one shared brain, zero friction. Authentication (OIDC) still guards the front door; you've just turned off the internal role gate.

🏢 Enterprise — several people, one brain

AUTH_ENFORCE=1                          # default — the single switch (see below)
OIDC_SCOPE=openid profile email groups  # request the groups claim
AUTH_ROLE_CLAIM=groups                  # map Pocket ID groups → roles

AUTH_ENFORCE=1 is the one switch — "enforce means enforce". It turns on roles (admin / user / viewer), per-user isolation, and per-user capability areas together. Roles are driven by your IdP groups (mapped in data/auth/policy.json, or managed live with the tenancy_* admin tools). Each non-admin is confined to their own memory scope and private vault namespace — two people never read or overwrite each other's data — and reaches only the services & skills an admin assigns (default-deny); an admin provisions per-user secrets (secret_set owner=…) and areas (tenancy_set services=… skills=…). Admins keep full access.

Both modes run the same image. Who is admin: only the operators you name (OPERATORS=<your IdP sub>, or the first person who signs in after a fresh start — see below); everyone else who signs in is user. With sign-in configured, a caller whose identity can't be resolved, or a policy check that fails, is refused (fail closed). Full guides: docs/authorization.md · docs/per-user-areas.md.

Upgrading to 2.6.0 — what you need to do

2.6.0 closes the findings of a full security review, among them a way into the WebUI without signing in (present since 1.12.0). If your WebUI is reachable from the internet, update now. Nothing in data/ has to be migrated by hand.

Checklist

1. Check one setting first. If your .env or compose file sets FORWARDED_ALLOW_IPS=*, change it to your reverse proxy's source address. For a proxy on the same host: FORWARDED_ALLOW_IPS=127.0.0.1,172.16.0.0/12. With * a client can fake its IP address and get around the new login rate limits.
2. Update: docker compose pull && docker compose up -d --force-recreate.
3. Read the startup log once (docker compose logs aicortex). You should see:
   • auth: kept N existing admin(s) as operators — the people who were admin before stay admin (or operators from OPERATORS: … if you set that).
   • OAuth store: migrated N entries … — your connected apps stay signed in.
   • vault: bound N secret(s) of existing integrations to their hosts — your services keep working.
   • No WARNING about FORWARDED_ALLOW_IPS.
   • If you see WARNING: nobody is operator (admin) yet, sign in to the WebUI within 30 minutes — the first person to sign in becomes the operator. Or set OPERATORS=<your sub> and restart (see Who is admin).
4. Sign in to the WebUI again (https://<your-host>/ui). Old WebUI cookies are no longer valid. Under Users, you should be marked operator.
5. Reconnect your apps when they ask. Claude, ChatGPT and others show an AICortex consent page once per app ("… wants to access AICortex"). Allow it. If that page ever pops up out of the blue from a link, deny it — that is exactly the attack it exists to stop.
6. Recommended: in your identity provider, allow only your own group to use the AICortex client (Pocket ID: OIDC client → Allowed User Groups).
7. Was the hole used? If your WebUI was public before the update, look through WebUI → Logs (the audit log) for entries without a person (empty identity), especially memory_write, memory_delete and cron, and check your scheduled jobs.

How it works now

Who is admin

• Operators are admin when they sign in to the WebUI or connect an app. Name them with OPERATORS=<sub>[,<sub>…] (your IdP's sub, shown on the WebUI's Users page), or keep the ones the upgrade recorded in data/auth/policy.json → "operators".
• Everyone else who signs in is user: their own notes and vault area, no registration or secret tools. Give someone more in WebUI → Users.
• Fresh install without OPERATORS: the first person to sign in within OPERATOR_BOOTSTRAP_MINUTES (default 30) after a start becomes the operator. Sign in right after setting up. Missed it? Restart and sign in again, or set OPERATORS.
• The last operator can't be removed or demoted, so you can't lock yourself out.
• Agent keys and scheduled jobs never become admin through this; they use the role set for them explicitly, else user.
• Want the old behaviour (everyone your IdP lets in is admin)? OIDC_DEFAULT_ROLE=admin — only if your IdP admits nobody but you.

Connecting apps

• Built-in callbacks: Claude (claude.ai / claude.com), ChatGPT, and loopback addresses on any port (Claude Code, desktop and CLI clients). Other apps answer "invalid redirect uri"; allow them with an https pattern, e.g. MCP_REDIRECT_URIS=https://app.example.com/oauth/*. Custom schemes such as vscode:// can't be matched.
• Each app shows the consent page once. Allow it for apps you connected yourself.
• Never set MCP_REDIRECT_URIS=*: then anyone can register an app that sends your login to their own server.

Secrets and where they may go

• Every vault secret is bound to the hosts it may be sent to. A request to any other host is refused, so a manipulated assistant can't send your tokens elsewhere.
• Existing integrations were bound automatically at the upgrade.
• New integration, set up by an assistant: store the secret together with its host — secret_set("MY_TOKEN", "<value>", hosts="api.example.com") — then add the service. Without the host, the assistant gets a refusal that says exactly this.
• New integration in the WebUI: just save it; saving binds the secret.
• Moving a service to a new host or sending a secret with webhook_send: add the host in WebUI → Vault → allowed hosts for that secret.
• Settings of the server itself (RATE_LIMIT*, HSTS, MCP_*, FORWARDED_*, OPERATOR*, UI_*, API_*, …) are never read from the environment as a secret. A token you kept in such an environment variable must move into the vault.

Behind a reverse proxy

• FORWARDED_ALLOW_IPS names who may tell AICortex the real client IP. The default in docker-compose.yml is loopback plus private networks. Never *.

• Rate limits per client IP (all configurable, 0 switches one off, RATE_LIMIT=0 all of them):

  Setting	Default	Covers
  RATE_LIMIT_AUTH	30/min	/authorize, /token, /consent, /revoke, /auth/callback
  RATE_LIMIT_LOGIN	30/min	WebUI sign-in
  RATE_LIMIT_REGISTER	10/hour	app registration (/register)
  RATE_LIMIT_HOOKS	60/min	inbound webhooks
  RATE_LIMIT_UI	300/min	WebUI API
  RATE_LIMIT_AUTH_FAILURES	20/min	rejected credentials on /mcp and /api/v1 → 429 for RATE_LIMIT_FAILURE_COOLDOWN (300 s)

• HSTS is sent automatically when BASE_URL starts with https:// (this host only; HSTS=<value> changes it, HSTS=off switches it off).

Webhook senders

• Existing senders keep working unchanged.
• A delivery that is repeated byte for byte within 10 minutes is answered with {"ok": true, "duplicate": true} and not delivered again (WEBHOOK_REPLAY_TTL).
• Optional replay protection: send X-Webhook-Timestamp: <unix seconds>. It must be within ±5 minutes, and HMAC hooks then sign "<timestamp>." + body.

REST API

• Errors no longer contain the exception text; they carry an error_id that you find again in the server log and the audit log.