AICortex MCP server
2026년 11월 12일 커밋MCP와 REST API를 통해 메모리, SKILL, 암호화된 비밀 정보, 예약된 작업을 관리하며 LLM을 위한 셀프 호스팅 방식의 지속 가능한 브레인을 제공합니다.
다른 이름 IkarusMK/AIcortex
- 스타
- 11
- Tools
- —
- 다운로드, 30일
- —
- 최신 버전
- 2.7.2
- 마지막 커밋
- 2026년 11월 12일
- 라이선스
- Apache-2.0
AICortex MCP란?
AICortex은(는) MCP server입니다. MCP와 REST API를 통해 메모리, SKILL, 암호화된 비밀 정보, 예약된 작업을 관리하며 LLM을 위한 셀프 호스팅 방식의 지속 가능한 브레인을 제공합니다.
프로젝트 README에서 생성된 요약
AICortex MCP server 정보
AICortex는 NAS와 같은 자체 하드웨어에서 실행되도록 설계된 대규모 언어 모델용 셀프 호스팅 지속 가능 브레인입니다. 민감한 데이터를 모델 제공업체로 전송하지 않고도 AI가 메모리, SKILL, 암호화된 비밀 정보를 관리할 수 있는 중앙 집중식 위치를 제공합니다. Model Context Protocol 또는 네이티브 REST API를 통해 연결하면 Claude, ChatGPT 또는 로컬 Ollama 인스턴스와 같은 모든 MCP 지원 클라이언트가 통합된 ID와 도구 세트에 접근할 수 있습니다.
사용자는 SMTP 및 IMAP을 통한 이메일, CalDAV를 통한 캘린더, MQTT 또는 FTP 장치와 같은 하드웨어를 포함한 다양한 서비스를 통합할 수 있습니다. 또한 시스템에 내장된 스케줄러를 통해 특정 시간에 노트 요약을 요청하는 등의 작업을 자동화할 수 있습니다. /ui 경로의 관리용 WebUI를 통해 암호화된 볼트, 사용자 역할 및 감사 로그를 관리할 수 있습니다. 컨테이너화된 설정을 사용하므로 코드를 다시 배포할 필요 없이 데이터를 추가하는 방식으로 새로운 기능을 확장할 수 있습니다.
활용 사례
- 1지속적인 세션 컨텍스트 유지매 채팅 시작 시 AI에게 사용자의 정보와 현재 프로젝트 상태에 대한 요약을 제공합니다.
- 2AI와 로컬 하드웨어 연결어시스턴트가 프린터나 스캐너와 같은 로컬 네트워크 장치와 상호작용할 수 있도록 합니다.
- 3비 MCP 워크플로우와 통합네이티브 REST API를 사용하여 AI의 메모리와 도구를 n8n 또는 LangChain과 같은 자동화 플랫폼에 연결합니다.
프로젝트의 README를 바탕으로 작성되었습니다. 모든 활용 사례는 해당 내용의 인용문과 대조하여 확인합니다.
AICortex MCP 설치 방법
형식 확인: 2026년 11월 10일Cursor에 추가Goose에 추가Claude Code에 AICortex MCP 설치
$ claude mcp add --env 'STORAGE_ENCRYPTION_KEY=<YOUR_STORAGE_ENCRYPTION_KEY>' --env 'JWT_SIGNING_KEY=<YOUR_JWT_SIGNING_KEY>' --env 'OIDC_CLIENT_SECRET=<YOUR_OIDC_CLIENT_SECRET>' aicortex -- docker run -i --rm ghcr.io/ikarusmk/aicortex:v2.7.2Cursor에 AICortex MCP 설치
~/.cursor/mcp.json
{
"mcpServers": {
"aicortex": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/ikarusmk/aicortex:v2.7.2"
],
"env": {
"STORAGE_ENCRYPTION_KEY": "<YOUR_STORAGE_ENCRYPTION_KEY>",
"JWT_SIGNING_KEY": "<YOUR_JWT_SIGNING_KEY>",
"OIDC_CLIENT_SECRET": "<YOUR_OIDC_CLIENT_SECRET>"
}
}
}
}VS Code에 AICortex MCP 설치
.vscode/mcp.json
{
"servers": {
"aicortex": {
"type": "stdio",
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/ikarusmk/aicortex:v2.7.2"
],
"env": {
"STORAGE_ENCRYPTION_KEY": "<YOUR_STORAGE_ENCRYPTION_KEY>",
"JWT_SIGNING_KEY": "<YOUR_JWT_SIGNING_KEY>",
"OIDC_CLIENT_SECRET": "<YOUR_OIDC_CLIENT_SECRET>"
}
}
}
}VS Code CLI에 AICortex MCP 설치
$ code --add-mcp '{"name":"aicortex","type":"stdio","command":"docker","args":["run","-i","--rm","ghcr.io/ikarusmk/aicortex:v2.7.2"],"env":{"STORAGE_ENCRYPTION_KEY":"<YOUR_STORAGE_ENCRYPTION_KEY>","JWT_SIGNING_KEY":"<YOUR_JWT_SIGNING_KEY>","OIDC_CLIENT_SECRET":"<YOUR_OIDC_CLIENT_SECRET>"}}'Claude Desktop에 AICortex MCP 설치
claude_desktop_config.json
{
"mcpServers": {
"aicortex": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/ikarusmk/aicortex:v2.7.2"
],
"env": {
"STORAGE_ENCRYPTION_KEY": "<YOUR_STORAGE_ENCRYPTION_KEY>",
"JWT_SIGNING_KEY": "<YOUR_JWT_SIGNING_KEY>",
"OIDC_CLIENT_SECRET": "<YOUR_OIDC_CLIENT_SECRET>"
}
}
}
}Codex에 AICortex MCP 설치
$ codex mcp add aicortex --env 'STORAGE_ENCRYPTION_KEY=<YOUR_STORAGE_ENCRYPTION_KEY>' --env 'JWT_SIGNING_KEY=<YOUR_JWT_SIGNING_KEY>' --env 'OIDC_CLIENT_SECRET=<YOUR_OIDC_CLIENT_SECRET>' -- docker run -i --rm ghcr.io/ikarusmk/aicortex:v2.7.2Codex config.toml에 AICortex MCP 설치
~/.codex/config.toml
[mcp_servers.aicortex] command = "docker" args = ["run", "-i", "--rm", "ghcr.io/ikarusmk/aicortex:v2.7.2"] [mcp_servers.aicortex.env] STORAGE_ENCRYPTION_KEY = "<YOUR_STORAGE_ENCRYPTION_KEY>" JWT_SIGNING_KEY = "<YOUR_JWT_SIGNING_KEY>" OIDC_CLIENT_SECRET = "<YOUR_OIDC_CLIENT_SECRET>"
Gemini CLI에 AICortex MCP 설치
$ gemini mcp add -s user -e 'STORAGE_ENCRYPTION_KEY=<YOUR_STORAGE_ENCRYPTION_KEY>' -e 'JWT_SIGNING_KEY=<YOUR_JWT_SIGNING_KEY>' -e 'OIDC_CLIENT_SECRET=<YOUR_OIDC_CLIENT_SECRET>' aicortex docker -- run -i --rm ghcr.io/ikarusmk/aicortex:v2.7.2Gemini settings.json에 AICortex MCP 설치
~/.gemini/settings.json
{
"mcpServers": {
"aicortex": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/ikarusmk/aicortex:v2.7.2"
],
"env": {
"STORAGE_ENCRYPTION_KEY": "<YOUR_STORAGE_ENCRYPTION_KEY>",
"JWT_SIGNING_KEY": "<YOUR_JWT_SIGNING_KEY>",
"OIDC_CLIENT_SECRET": "<YOUR_OIDC_CLIENT_SECRET>"
}
}
}
}구성
STORAGE_ENCRYPTION_KEY필수비밀Fernet key that encrypts the vault and the sign-in store (openssl rand -base64 32 | tr '+/' '-_')
JWT_SIGNING_KEY비밀Signs the server's own tokens (openssl rand -hex 32)
OIDC_CLIENT_SECRET비밀Client secret registered at your identity provider
AUTH_ENFORCEAUTH_ROLE_CLAIMBASE_URLPublic HTTPS URL of this server, e.g. https://agent.example.com
OIDC_CLIENT_IDClient ID registered at your identity provider
OIDC_CONFIG_URLDiscovery URL of your own identity provider (sign-in for cloud LLM apps)
OIDC_SCOPE
| 이름 | 설명 | 유형 |
|---|---|---|
| STORAGE_ENCRYPTION_KEY | Fernet key that encrypts the vault and the sign-in store (openssl rand -base64 32 | tr '+/' '-_') | 필수비밀 |
| JWT_SIGNING_KEY | Signs the server's own tokens (openssl rand -hex 32) | 비밀 |
| OIDC_CLIENT_SECRET | Client secret registered at your identity provider | 비밀 |
| AUTH_ENFORCE | — | |
| AUTH_ROLE_CLAIM | — | |
| BASE_URL | Public HTTPS URL of this server, e.g. https://agent.example.com | |
| OIDC_CLIENT_ID | Client ID registered at your identity provider | |
| OIDC_CONFIG_URL | Discovery URL of your own identity provider (sign-in for cloud LLM apps) | |
| OIDC_SCOPE | — |
자동 검사
2026년 11월 12일에 실행됨전체 보고서 →아직 인증되지 않았습니다. 서버는 80점 이상의 점수, 심각한 결함 없음, 그리고 검사에 충분한 데이터를 갖추어야 합니다. 검사 방식 · 점수를 높이기 위해 수정할 항목
- 소스 저장소 연결 및 접근 가능통과
- 오픈 소스 라이선스 (OSI)통과
- 최근 1년 내 커밋 또는 릴리스통과
- 패키지 이름이 인기 패키지와 유사하지 않음검사되지 않음
- 원격 엔드포인트가 HTTPS 사용검사되지 않음
- 파괴적인 도구에 라벨 표시됨검사되지 않음
- 모델에 대한 숨겨진 지침 없음통과
- 패키지 및 해당 종속성에 중요한 보안 권고 없음검사되지 않음
README
GitHub에서 보기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_startcall — who you are, how you work, and the current project's notes, open tasks and last session (a few hundred characters;cortex_cataloghas 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
- Open http://localhost:8787/ui — the WebUI, already signed in as admin.
- 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 callcortex_start. Other local clients: docs/clients.md. The Claude and ChatGPT apps connect from their provider's cloud, so they need the real setup. - 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=1switches authentication off: whoever reaches the port is admin. Keep the port on127.0.0.1as 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 outbuild: ., uncommentimage: ghcr.io/ikarusmk/aicortex:latest, thendocker 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:
- Point a subdomain (e.g.
agent.example.com) at your reverse proxy. - Proxy that host to
http://<nas-ip>:8787over 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 to127.0.0.1by default (only this host's proxy reaches it, not the LAN); a host-network proxy useshttp://127.0.0.1:8787, a bridge-network proxy needsBIND_ADDR=0.0.0.0(or a shared Docker network). - 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. - Test: ask the assistant to call
cortex_start. The briefing starts withAICortex v<version>; on a fresh install it is short because the memory is still empty. (pingworks 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,/mcpaccepts bearer tokens only (per-agent keys andRUNNER_TOKEN);ALLOW_INSECURE=1turns 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
- Check one setting first. If your
.envor compose file setsFORWARDED_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. - Update:
docker compose pull && docker compose up -d --force-recreate. - 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 (oroperators 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
WARNINGaboutFORWARDED_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 setOPERATORS=<your sub>and restart (see Who is admin).
- Sign in to the WebUI again (
https://<your-host>/ui). Old WebUI cookies are no longer valid. Under Users, you should be marked operator. - 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.
- Recommended: in your identity provider, allow only your own group to use the AICortex client (Pocket ID: OIDC client → Allowed User Groups).
- 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_deleteandcron, 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'ssub, shown on the WebUI's Users page), or keep the ones the upgrade recorded indata/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 withinOPERATOR_BOOTSTRAP_MINUTES(default 30) after a start becomes the operator. Sign in right after setting up. Missed it? Restart and sign in again, or setOPERATORS. - 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 asvscode://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_IPSnames who may tell AICortex the real client IP. The default indocker-compose.ymlis loopback plus private networks. Never*. -
Rate limits per client IP (all configurable,
0switches one off,RATE_LIMIT=0all of them):Setting Default Covers RATE_LIMIT_AUTH30/min /authorize,/token,/consent,/revoke,/auth/callbackRATE_LIMIT_LOGIN30/min WebUI sign-in RATE_LIMIT_REGISTER10/hour app registration ( /register)RATE_LIMIT_HOOKS60/min inbound webhooks RATE_LIMIT_UI300/min WebUI API RATE_LIMIT_AUTH_FAILURES20/min rejected credentials on /mcpand/api/v1→429forRATE_LIMIT_FAILURE_COOLDOWN(300 s) -
HSTS is sent automatically when
BASE_URLstarts withhttps://(this host only;HSTS=<value>changes it,HSTS=offswitches 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_idthat you find again in the server log and the audit log.
AICortex MCP 질문
AICortex MCP를 Claude Code에 추가하려면 어떻게 하나요?
터미널에서 claude mcp add --env 'STORAGE_ENCRYPTION_KEY=<YOUR_STORAGE_ENCRYPTION_KEY>' --env 'JWT_SIGNING_KEY=<YOUR_JWT_SIGNING_KEY>' --env 'OIDC_CLIENT_SECRET=<YOUR_OIDC_CLIENT_SECRET>' aicortex -- docker run -i --rm ghcr.io/ikarusmk/aicortex:v2.7.2를 실행합니다. 모든 프로젝트에서 사용할 수 있게 하려면 --scope user를 추가합니다.
AICortex MCP를 Cursor에 추가하려면 어떻게 하나요?
~/.cursor/mcp.json를 열고 mcpServers 아래에 서버를 추가합니다. 위 설치 섹션에 표시된 Cursor 구성을 사용합니다.
MCP를 지원하지 않는 도구에서도 AICortex를 사용할 수 있나요?
네, 자동 생성된 OpenAPI 3.1 사양을 제공하는 네이티브 REST API를 통해 n8n 또는 LangChain과 같은 비 MCP 도구와 연결할 수 있습니다.