Security
How Aki MCP Server keeps access on your terms
Because the server can face the open internet, security is built in by construction, not added later. Here is exactly what protects you, and the trade-offs you are responsible for.
A word you do not know? Words you will meet
A hard whitelist, not a blocklist
The shell tool only runs commands you explicitly approve. A blocklist is leaky because its default is allow; a whitelist fails safe.
- Fail-safe: an unfamiliar or new command is blocked automatically.
- Minimal surface: only the exact commands you approved can run.
- Granular to the subcommand: git is scoped to
status/log/diff/show. - A guardrail, not a wall: the allowlist keeps a careless or overeager AI on the commands you approved, but it does not stop prompt injection on its own. The file tools can write
~/.aki/mcpsv/setting.jsoninside the default folders and widen the list, so keep the passphrase and token private and review who has access. - Paths inside a command are not fenced:
run_cmdstarts only inside your allowed folders, but a path written in the command itself is not checked against them; arguments that name credential files are refused. Commands run with your user’s permissions. - Inspection-first: flag-rich binaries that could escape read-only are deliberately left out, and git write forms (
branch -D,tag -d,remote set-url,--output=) are refused by default.
Design stance: convenience first, guardrail second. The allowlist guards against weak or overeager models. It is not a lock against you, the owner.
Authentication and authorization
- Every
/mcpcall needs a valid OAuth 2.1 Bearer token. There is no token-in-URL shortcut. - Every web AI that signs in with OAuth enters the passphrase and self-registers via DCR (RFC 7591), so there is no Client ID or Secret to paste; ChatGPT and Grok register as public clients, Notion as a confidential one. The pre-issued Client ID/Secret that
akimcpprints at start stays as an optional fallback for a client that wants a static pair. Gemini’s sign-in has not been checked in a live session yet. - Only redirect URIs of known clients are accepted (
claude.ai,chatgpt.com,grok.com, Google’s OAuth redirect proxy for Gemini, Notion’s fixed callback hosts undernotion.soandnotion.com, and ClickUp’s exact callbackhttps://search.clickup-prod.com/connect/mcp, matched on the exact hostname over https so lookalike domains fail), plus any https address you add in the panel’s Other AI (sign-in) tab. Each address is read the way the browser will follow it:%2e%2eand similar tricks resolve before the check, and an address with#, a user name or a password is refused. Every sign-in re-checks its address, so removing one stops new sign-ins through it, and the confirmation page names where the sign-in returns. A client still must pass a passphrase consent screen and PKCE before it gets a token. - One shared access token (valid for a year) serves every client, so the panel can show and roll it in one place.
- The sign-in files (
tokens.json, the retired-token list andpassphrase.txt) are written whole or not at all, so a crash or a full disk cannot leave one empty, and an emptypassphrase.txtis replaced by a new passphrase instead of letting a blank one in. - Besides it, the panel mints temporary tokens, one per web chat: 4 hours each, and +30 min beside a live one adds half an hour as often as you click it, while a Last used cell shows when, from which address and which app. Each is revoked by the chat itself, by Revoke in the panel, by Roll & sign out all clients, or by a restart; an expired or revoked one stays dead. They never change the shared token.
Automatic lockout and a clear view
The gatekeeper rate limits failed attempts, and the panel’s “Security & connection limits” section shows who holds access and who used it.
- 5 strikes, 15 minutes out: 5 rejected credentials in 60 seconds (wrong passphrase, wrong client secret, invalid Bearer on
/mcp) block the caller for 15 minutes with a429andRetry-After. - Registration flood guard: 100
POST /registercalls in 10 minutes also block the caller, and the client list stops growing at 500. - Each caller is counted by the address its ingress writes: Cloudflare Tunnel by
CF-Connecting-IP, Tailscale Funnel by the lastX-Forwarded-Forentry, your own edge (PUBLIC_ORIGIN) by either. A header the ingress does not write is ignored, so a client cannot choose its own key (3.0.1 and later). - A first call without credentials is not counted: an MCP client opens with one request without a bearer, to read the
401sign-in challenge. Since 3.1.0 that request is neither counted nor written to the security log, so a burst of reconnects cannot block a client. A wrong bearer still counts. - Real clients are safe: a valid Bearer token is never counted or refused, and protocol errors or unknown paths are never counted.
- You set the numbers: every limit is editable in the panel’s “Security & connection limits” section, which lists blocked callers with a Release button.
- See everything: Clients (first seen, last approval, last token grant, address and agent), Active now, and the newest 200 lines of
security.log. Click a column header to sort any panel table; Clients and Active now also have a text filter, a row count and Refresh, and Clients a status filter. - Masked secrets: the passphrase and access token show as dots with an eye button, so a screenshot carries neither.
If a secret leaks
The panel turns the clean-up into a few clicks. Pick the row that matches what was exposed.
- Passphrase seen:
Roll passphrase, thenRoll & sign out all clients. - Access token seen:
Roll & sign out all clients. - Unknown client in the list: both rolls, then reconnect the AIs you trust.
- A connector you no longer use:
Revoke & rollin Clients. It removes the client and rolls the shared token, so Bearer setups such as Buda and the Claude Code, Codex and Cursor snippets need the new token.
Credentials stay out of tool results
The files that hold akimcp’s own secrets are closed to the tools, and a secret that still reaches a result, from those files or from a project file such as .env, is masked before it goes to the AI provider.
- Credential files are off limits: the file tools neither read nor write
tokens.json,passphrase.txt,oauth-client.json,oauth-dcr-clients.jsonorcloudflared-cred.json.run_cmdandtask_startrefuse a command that names one, andsearch_contentleaves them out of its results. - Redaction on every result: each token-shaped value from those files, the passphrase and the panel token in
instance.jsoncome back as[redacted], also in error messages and before a long output is cut. That covers a straygrep -rover the data folder or a copy that landed in a task log. - Secrets in project files, by shape: every result also hides the value of a
NAME=valueline whose name has a part such asTOKEN,SECRET,KEY,PASSWORD,AUTHorCOOKIE, and anywhere in the text a Telegram bot token, ansk-, GitHub, Slack, Postman, Google or AWS key, aBearervalue, the password in a URL and a PEM private key. A$referencestays, so a script that reads a secret stays editable, andwrite_fileandedit_filerefuse to write[redacted]into a file that holds a hidden value, so an edit cannot overwrite the real one. - It stops mistakes, not a determined model: a secret under a neutral name (
CHAT_ID=) or in another form (password:in YAML) still comes back as written, an encoded copy (compressed or base64) is not recognized, and a model that widens the allowlist to a full shell can read anything you can.setting.jsonstays readable and writable on purpose, so an AI can adjust folders and the allowlist when you ask.
What each layer protects
One gatekeeper, bearer on loopback too
The gatekeeper on 127.0.0.1:9999 is the single entry for both local and (via optional ingress) remote clients; every tool runs in-process behind it, and a Bearer token is required even on loopback.
Panel stays local
The control panel binds to 127.0.0.1:9998, needs a per-launch token, and is never exposed through the public edge.
SSRF-protected fetch
The LAN fetcher blocks cloud metadata, link-local IPs, and non-HTTP schemes, with size and time caps.
Secrets stay 0600
Passphrase, client secret, and tokens live in ~/.aki/mcpsv/ at mode 0600, outside the repo, never in git.
What the AI can and cannot do by default
Can, by default
Run the inspection-first shell set, read and search files in allowed folders, and make every action a visible tool call. A few pre-approved dev helpers (npm run, open, sips, ffmpeg) can write.
Cannot, by default
Run anything off the allowlist, run git write forms, write into trusted script folders through the file tools, reach the local panel, or make arbitrary outbound network calls.
Honest trade-offs you must know
- The default file root is your entire home folder (
$HOME) plus~/.akiand~/.claude. Narrow it in the panel on a sensitive machine. ~/.claudeis granted at the folder level, so session tokens and chat history inside it are also in reach. Remove it by editing the folders list directly.- Any write command you add to the allowlist (for example
git commit) is your own responsibility and widens the surface. - With one shared token, Remove only signs a client out but is not an instant revoke. Revoke & roll removes it and rolls the token to cut access at once.
- The rate limiter lives in memory, so a restart clears the blocked list. Client names are self-declared, so trust the address and time columns more than the label.
- Behind Tailscale Funnel the lockout trusts the last
X-Forwarded-Forentry. That Funnel writes the caller’s real address there was read from Tailscale’s source, not seen on a live Funnel request; Cloudflare Tunnel’s header was seen live. - Gemini is experimental: it signs in again in 3.1 (not yet checked live), but tool use was unreliable in earlier tests.
Revoke access anytime from the panel’s “Security & connection limits” section: Revoke & roll the client (a registration that never got a token has only Delete). If a secret may have leaked, use Roll & sign out all clients.