In Practice

Screenshots

Real, verified captures from client-side integrations.

1 / 8

Aki MCP Server preview

Open the live control panel demo

Works with

One server, local IDEs + web AIs

Local-first: Postman, Cursor, Claude Code, AGY & Codex connect directly over 127.0.0.1 (0ms, offline); Claude, ChatGPT, Grok, Notion & Gemini connect over an optional ingress.

Local · direct over 127.0.0.1, 0ms, offline

PostmanCursorClaude CodeAGY (Antigravity)Codex

Web · needs an optional ingress

Claude webChatGPTGrokNotionGemini· experimental

Motivation & Purpose

Why Aki MCP Server exists

Routes around expensive per-token API pricing and desktop-app device lock-in.

Cheap web/Pro quota instead of per-token API pricing

Claude Pro / ChatGPT Plus is far cheaper monthly than paying per token via the API for equivalent usage on real project work: reading a full codebase, tailing logs continuously. Aki MCP Server brings that web-quota power straight to your local source code.

Multi-account flexibility, no device lock-in

The Claude Desktop app ties usage to a device ID and forces a login/logout dance to switch accounts. With Aki MCP Server, just switch browser profiles: run several Claude Pro accounts, all pointed at the same local machine.

Control your machine away from your desk

On the move or on another device: open Claude Web, ChatGPT Mobile, or Grok to check a build’s progress, read server logs, clean up temp files, or safely run <code class="text-emerald-400">git pull</code> on your machine at home.

Scheduled headless runs (Grok + Local MCP)

Pair Grok’s Scheduled Prompts with Aki MCP Server to turn your machine into a headless AI node. At the scheduled time, Grok calls back to check on the system, sweep logs, drive a real browser tab, or pull the latest code, with no window open on your side.

What You Can Do

Real workflows, start to finish

Concrete, end-to-end tasks you can hand to a web AI — each step is a visible, permitted tool call.

Fix a bug from your phone

You are away from your desk and a bug report lands.

1Open Claude or ChatGPT on your phone and describe the bug.
2It searches the repo, reads the files, and checks git status and the diff.
3It edits the file inside the folder you allowed, then runs your typecheck or tests.
4It shows the diff and sends a desktop notification when the fix is done.

QA a web app in a real browser

Verify a change end-to-end without opening your IDE.

1It checks your dev server and the port it runs on.
2It opens a shared Chrome profile clone, or attaches to the Chrome already running it.
3It navigates, interacts with the page, and captures screenshots.
4It reports issues with clear reproduction steps.

Debug an API in Postman

Iterate on a request and its tests hands-free.

1It inspects the request currently open in Postman.
2It sends the request and reads the response and test results.
3It adjusts the request or the tests as needed.
4It re-runs and confirms the fix.

Security, Not an Afterthought

Aki MCP Server vs Desktop Commander

Why a hard whitelist is non-negotiable once an MCP port faces the internet.

Aki MCP Server vs Desktop Commander
Criteria	Aki MCP Server	Desktop Commander
Connection environment	Claude Web, ChatGPT Web/Mobile, Grok, Notion, Gemini over the internet (HTTPS), plus Postman, Cursor, Claude Code, AGY, Codex locally	Local Claude Desktop app only
Shell protection	Hard whitelist: only approved commands run; blocks ; & \| `	Blocklist: everything allowed except a forbidden list (bypassable via flags or new commands)
Prompt-injection defense	Strong guardrail: anything off the list is rejected outright, so an injected instruction has nothing unlisted to escalate to. It guards against weak or overeager models, not against you	High risk if the AI is tricked into running a command not yet in the blocklist
Authentication & authorization	OAuth 2.1 + passphrase consent + RFC 7591 DCR for ChatGPT, Grok & Notion	No OAuth, runs directly through the local process
Admin panel	The control panel (`127.0.0.1:9998`), random token-gated: visual allowlist config, every client and active caller, a security log	Edit a static JSON config file by hand
File & directory search	`aki__find_path` scans 164k files in 0.2s, auto-skips node_modules/.git	Regular search commands or the default filesystem tool, prone to timeouts
Beyond files & shell	Also drives a real browser (CDP), git, SQLite, background tasks, OS notify/clipboard — 38 tools total	File and shell operations only

Architecture & Security

Layered security by construction

Your data is isolated and guarded at every hop.

Layer 1: Local-first engine (ingress optional)

Gatekeeper on 127.0.0.1:9999 + OAuth 2.1

The Gatekeeper binds 127.0.0.1:9999 unconditionally the moment you start the server, so local clients (Postman, Cursor, Claude Code, AGY, Codex) connect straight over loopback with zero WAN round-trip and keep working fully offline. A public ingress (Tailscale Funnel / Cloudflare Tunnel) is an optional satellite, used only by cloud/mobile web AIs.

Bearer-token auth is enforced even on loopback — no token, no tools.
Web AIs still gate through OAuth 2.1: Claude needs only the URL and passphrase; ChatGPT, Grok & Notion self-register via DCR (POST /register); only Gemini needs a Client ID and Secret pasted.
When no ingress is attached, the OAuth discovery routes answer 503 while /mcp keeps serving local clients.
Repeated wrong credentials are blocked at the gatekeeper: 5 rejected in 60 seconds earns a 15 minute 429. A valid Bearer token is never blocked.

Loopback · ingress optional

Layer 2: Routing & bridge

Streamable Bridge & Tools Server

The bridge accepts Streamable HTTP from the AI web client and hands it straight to a single in-process MCP server over the SDK’s in-memory transport, with no child process and no network hop.

The tools server is in-process, so it listens on no port at all.
Multi-client multiplexing via ID remapping.
The internal admin API is never exposed to the internet.

in-process

Layer 3: Admin & storage

Isolated userdata & panel

Tokens, passphrase, allowlist, and config all live outside the source tree at ~/.aki/mcpsv/, with the credential files (tokens, OAuth client, passphrase) locked to 0600 permissions.

The control panel (:9998) is protected by a random token generated at each launch, and shows every client and security event.
Path containment enforced via roots.js.
A fresh git clone stays clean: secrets never enter the repo.

Token Protected

Tool System

38 built-in local tools (`aki__*`)

38 tools: browser automation, DevTools/CDP, git, SQLite, background tasks, and OS-native notifications, on top of the original file/shell/search set. Tools of an app you haven’t installed aren’t served. Designed for speed, context economy, and strict security.

Browser Automation

`aki__chrome_*`

Opens a Chrome, Brave or Edge profile clone shared with the optional AIObox app (in ~/.aki/cdp/profiles/), or attaches to the Chrome already running it, then opens tabs and drives typing and clicking. It never clones a profile itself.

CDP

`aki__devtools_*`

Lists page targets, evaluates JS in any tab, and captures a screenshot over Chrome DevTools Protocol, on the active Chrome session by default. Every call ends within 50 s, so a page that never answers returns a timeout error with a next step instead of a silent hang.

Git (read-only)

`aki__git`

One read-only tool: op is status, diff, log or tags. Output is compact and bounded, and a huge diff is cut by whole file with the omitted files named first, so it doesn’t blow the context window.

SQLite Inspector

`aki__sqlite_*`

Zero-dependency, read-only inspection of any local SQLite database via Node’s native node:sqlite — schema and query, with DDL/DML rejected outright.

Background Tasks

`aki__task_start / aki__task_manage`

Runs a detached command with allowlist gating and direct-to-disk log streaming, then lets the AI check on it, tail the log, or kill the whole process group later — without blocking the chat.

OS Native

`aki__notify_user, aki__clipboard_*`

Fires a native desktop notification with a chime when a long task finishes, and reads/writes the system clipboard, so the AI can hand you a result without you watching the terminal.

Postman Control

`aki__postman_*`

Daemon status, in-app JS eval, chat renaming, and full-width panel toggle for the CDP-driven Postman desktop control daemon.

SSRF-Protected Fetch

`aki__local_fetch`

Lets remote AI clients (Claude Web, ChatGPT) test your local dev servers and LAN APIs. Only http and https are allowed, cloud-metadata and link-local addresses are blocked (IPv6 forms included), every redirect is re-checked, and a response is read up to 512 KB. It checks the host you give it, not what a DNS name resolves to.

Dev Ports

`aki__port_status, aki__kill_port`

Checks what’s listening on a port and kills it, with self-protection guards so it can’t accidentally kill the MCP server’s own ports.

Rule Context

`aki__akidevrule_context`

One read-only call loads the rules in force (global plus the project’s CLAUDE.md or AGENTS.md guidance) with provenance and a receipt. Every tool that changes something then needs that receipt, and a tool that touches a project first hands over that project’s rules, so a chat that skipped the rules is refused instead of writing blind.

Tool Providers

`providers (panel section 8)`

Tools of an app that isn’t installed (agy, Kiro CLI, Postman, Chrome, AIObox) are simply not served. Panel section 8 switches any optional provider on or off; agy and Kiro CLI start off because each hands a whole task to another paid agent. Your client sees the change on its next tool list, usually a new chat.

Credential Guard

`credential redaction`

The file tools refuse AkiMCP’s own credential files (tokens, passphrase, OAuth clients), run_cmd and task_start refuse a command that names one, and every tool result is redacted: a token or passphrase from those files reads [redacted] instead of landing in your chat.

Call Log

`call log (panel section 9)`

Every aki__ tool call is logged to a local file: time, client, tool, success or error code and duration, never the text, script or URL you passed. Panel section 9 sets the detail level, how many days to keep and the size cap, so you can see which AI did what.

Local Apps

`GET /api/access-token`

A local app can fetch the shared access token from the control panel instead of reading tokens.json. The endpoint is loopback only, needs the panel token, and sends no CORS header.

stdio

`akimcp --stdio`

npx -y @akinet/akimcp --stdio serves the same tools over stdin/stdout for any client that spawns MCP servers, with no gateway, tunnel or token. The package also carries a server.json record (io.github.lacvietanh/akimcp) that describes it for the MCP Registry.

File System

`filesystem`

Lets the AI safely read, create, and edit files inside the folders you allow in panel section 5. By default that is your whole home folder; narrow it there and the next tool call follows.

Blazing Fast

`aki__find_path`

Scans the whole tree in one call (0.2s across 164k files), returns both files and directories, auto-skips node_modules and .git.

Content Search

`aki__search_content`

Searches file contents with case-insensitive extended regex (grep -iE), fast.

Whitelisted Shell

`aki__run_cmd`

Runs shell commands from the approved whitelist, with a cwd to target the right project. Output is shaped for the model: ANSI and repeated lines removed, long output trimmed to start and end (full text saved to disk), and a failing command returns [exit code N] with stdout and stderr.

AGY Plan Arm

`aki__agy_run`

Delegates a question to a second, large-context AI assistant (Google’s Antigravity CLI) for broad, read-only research across the whole codebase. Off by default; switch it on in panel section 8.

Kiro Arm

`aki__kiro_read`

Delegates a question to a second, independent AI reviewer (the Kiro CLI, locked to a Claude Sonnet model) to cross-check project structure and logic. Off by default; switch it on in panel section 8.

Optional · AIObox

`akiaiobox, akiaiobox_write`

Only if you also run AIObox, a desktop app that keeps many AI chats and accounts open side by side: these two tools reach its windows. Without AIObox installed they are not served.

38 tools · one MCP server

Autonomous

Runs while you’re away

Pair scheduled prompts with local execution.

Cloud-triggered, local execution

Pair Grok’s scheduled prompts with your local server: kick off a build, clean temp files, pull the latest code, or check a running job — on a schedule, with nobody at the keyboard.

Scheduled prompts fire against your machine
Read logs and report back from anywhere
Desktop notification when the job is done

Security

Access on your terms

Tight defaults, nothing exposed you didn’t choose.

Whitelist, not blocklist

Only the commands you explicitly allow can run, and git write forms such as branch -D and tag -d are refused by default. A leaky blocklist is never the default.

OAuth 2.1 gated

Every /mcp call needs a valid Bearer token — no token-in-URL shortcuts.

Zero-trust loopback

Bearer auth is enforced even on 127.0.0.1: without it, any malicious site you browse could POST to the local port and gain code execution. The secret token plus CORS block that.

Panel stays local

The control panel binds to 127.0.0.1 and is never published through the public edge.

SSRF-protected fetch

The LAN fetcher blocks cloud metadata, link-local IPs (IPv6 forms included) and non-HTTP schemes, re-checks every redirect, and caps size at 512 KB and time at 15 s.

Lockout and a clear view

Five rejected credentials in 60 seconds earn a 15 minute block. Panel section 7 lists every client, who is active now and a security log, with Remove and roll buttons.

Before You Start

Requirements & what to expect

What you need to run it, which AI clients are dependable today, and the honest trade-offs.

What you need

Node.js 22 or newer, on macOS, Windows, or Linux.
Windows only: Git for Windows with its default options. The shell and search tools start the Unix binaries that ship in its usr\bin.
An AI client that supports custom MCP connectors: Claude web, ChatGPT (with Developer mode), Grok, Notion, or Postman (Gemini is experimental).
Only for remote web AIs (Claude, ChatGPT, Grok, Notion, Gemini): a way to expose the server over HTTPS — Tailscale Funnel (default, free), Cloudflare Tunnel, or your own HTTPS origin. Local IDEs (Postman, Cursor, Claude Code, AGY, Codex) need none of this; they connect over 127.0.0.1.
For remote use, your machine stays powered on with the server running — closing the terminal stops it.

Good to know

Tools of an app that isn’t installed are not served, and agy and Kiro CLI start off: switch providers on or off in panel section 8.
Gemini is experimental: the OAuth connection works, but tool use is unreliable today. Claude and Grok are the most dependable clients.
A few pre-approved dev/OS helpers in the default shell allowlist can write to disk — review the panel’s allowlist on sensitive machines.
One shared access token serves every client, so Remove signs a client out but the token keeps working until you Roll token in the panel.
The control panel is local-only (127.0.0.1) and is never published through the public edge.
Every file write, browser action, clipboard read, or background task is a separate tool call, visible in the chat as it happens.

AI client compatibility: authentication method and current reliability
AI client	Setup	Status today
Claude web	URL + passphrase, no Client ID or Secret	Dependable
ChatGPT	Developer mode, then automatic (DCR)	Dependable
Grok	Automatic (DCR self-register)	Dependable
Notion	Automatic (DCR), custom MCP servers enabled in the workspace	New in 3.0
Postman AI Agent	Loopback JSON copied from the panel	Dependable
Gemini	Client ID + Secret printed by akimcp at start, paid tier only	Experimental

Get Started

Install & run

No desktop app, no device lock-in: one npm command, or clone and run from source.

RecommendedmacOS, Windows, Linux

Global CLI, one command

Published on npm: install the akimcp command once, or run it on demand with no install at all.

# Install once, run anywhere

npm install -g @akinet/akimcp

akimcp

# Or run instantly, no install

npx @akinet/akimcp

Same server underneath: a local-first engine on 127.0.0.1:9999 (works offline), OAuth 2.1 for web AIs, optional Tailscale Funnel auto-config, the control panel, and all 38 aki__* tools.

Requires Node.js 22macOS, Windows, Linux

Clone, install, run

Clone the repo from GitHub and run the standard startup command.

# Clone

git clone https://github.com/lacvietanh/aki-mcp-sv.git

cd aki-mcp-sv

# Install & run

npm install

npm start

npm start starts the local-first Gatekeeper on 127.0.0.1:9999 right away, generates a passphrase, opens the control panel, and — if you want remote web AIs — auto-configures Tailscale Funnel.

Is this safe to run?

Nothing is installed system-wide, no background service or daemon is created, and no sudo/administrator privileges are required. Settings and tokens live at ~/.aki/mcpsv/. Most of the default shell whitelist is read-only (ls, cat, git status/diff/log, …); a few dev/OS helpers (npm run, open, sips, ffmpeg) are pre-approved and can write — review the panel’s allowlist before trusting the defaults on a sensitive machine. Every filesystem write, browser action, clipboard read, or background task is a separate tool call, visible in the chat as it happens. Browser control never clones a profile: it opens only the profile clones in ~/.aki/cdp/profiles/ that the optional AIObox app creates, or attaches to a Chrome already running one, and stopping it ends only a Chrome it launched. Closing the terminal stops the server itself; a background task you started keeps running by design until you stop it with aki__task_manage.

Optional ingress for remote web AIs (swappable edge)

1. Tailscale Funnel (default)

Zero-config, turns on port 9999 automatically when you run npm start. Free on every Tailscale plan.

2. Cloudflare Tunnel

Run with --tunnel <cred.json> --origin <url> to route through your own Cloudflare Tunnel. The panel and README recommend it over Funnel for a steadier connection; the difference has not been measured.

3. Custom Public Origin

Run with PUBLIC_ORIGIN=https://your-domain to point at your own HTTPS reverse proxy.

AI Integrations

Connect local IDEs (Cursor, Claude Code, AGY, Codex, Postman) & web AIs (Claude, ChatGPT, Grok, Notion, Gemini)

Local tools connect directly over 127.0.0.1 loopback (no tunnel, offline); web AIs connect over an optional public ingress. Step-by-step details for each.

Local IDEs · direct over 127.0.0.1 · 0ms · offline · no ingress

Postman

Postman Agent — HTTP MCP

1In the Postman tab of the control panel, click the filled JSON to copy it. It targets the local loopback endpoint and carries a real access token, not the passphrase. The shape is shown below.
2In Postman, add a new MCP server: Settings → Connected Accounts, or in the Agent chat the gear next to the model name → Configure MCP servers → MCP Servers tab → {} Edit config.
3Paste the JSON. Postman runs on this machine, so it connects over 127.0.0.1 with zero latency and needs no tunnel.
4Postman keeps no instruction between chats. After Launch, the Prompt instruction box of the Aki MCP for Postman overlay has Send now, or tick Auto-inject into each new chat (off by default).

{
  "mcpServers": {
    "aki-mcp-sv": {
      "url": "http://127.0.0.1:9999/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_LOCAL_ACCESS_TOKEN"
      }
    }
  }
}

Cursor

Local · direct over 127.0.0.1, 0ms, offline

1Open ~/.cursor/mcp.json (or Cursor → Settings → MCP Servers).
2Add: {"mcpServers":{"aki-mcp":{"url":"http://127.0.0.1:9999/mcp","headers":{"Authorization":"Bearer YOUR_LOCAL_ACCESS_TOKEN"}}}}. Grab the token from the control panel at http://127.0.0.1:9998.
3Reload Cursor. No tunnel, no internet — works fully offline. Use the literal 127.0.0.1, not localhost.

Claude Code CLI

Local · one-line install

1Run this one-liner in a terminal: claude mcp add --transport http aki-mcp http://127.0.0.1:9999/mcp --header "Authorization: Bearer YOUR_LOCAL_ACCESS_TOKEN".
2Copy the token from the control panel at http://127.0.0.1:9998. Connects over loopback, no tunnel, works offline.

AGY (Antigravity) CLI / IDE

Local · one click in the panel, stdio, no token

1Open the control panel at http://127.0.0.1:9998, go to the AGY tab, and click Apply to AGY CLI.
2It registers akimcp as a stdio command in ~/.gemini/config/mcp_config.json and pre-allows mcp(akimcp/*) in ~/.gemini/antigravity-cli/settings.json, so the CLI stops asking per tool. It merges into your existing config and is safe to re-run.
3IDE: the Antigravity IDE reads the same mcp_config.json, so it is connected too (it keeps its own per-tool approval prompt). No token to paste, works offline.

Codex CLI

Local · streamable HTTP in config.toml

1Append to ~/.codex/config.toml (don’t overwrite the file): [mcp_servers.aki-mcp], url = "http://127.0.0.1:9999/mcp", http_headers = { "Authorization" = "Bearer YOUR_LOCAL_ACCESS_TOKEN" }.
2Codex reaches the engine over streamable HTTP; the bearer token is inlined so there’s no shell env var to export. Restart Codex after saving. Works offline, no tunnel.

Web AIs · need an optional public ingress

Claude.ai Web Connector

URL + passphrase, no Client ID or Secret

1Go to claude.ai → Settings → Connectors → Add custom connector.
2Enter a Name (the panel suggests AkiMCP) and the Remote MCP server URL: https://your-machine.ts.net/mcp (printed when the server starts).
3Click Connect. A local confirmation page opens: enter the Passphrase shown in the control panel (or ~/.aki/mcpsv/passphrase.txt) to approve. Claude discovers OAuth by itself, so there is no Client ID or Client Secret to paste.

ChatGPT Web & Mobile

Developer mode required, self-registers

1Needs ChatGPT Plus/Pro (or Business/Enterprise/Edu). Turn on Developer mode first: Settings → Security and login. OpenAI requires it to create custom MCP apps.
2Create a custom connector (app): enter a Name and Description, then set Connection → Server URL to the MCP URL from the panel: https://your-machine.ts.net/mcp.
3Tick I understand and want to continue, then Create.
4On connect, enter the Passphrase shown in the panel to finish. ChatGPT self-registers via DCR (PKCE, no secret), so there is nothing else to paste.

Grok

Self-registers, name must match exactly

1Open Grok’s connector settings and add a new custom MCP connector. Set its Name to match the MCP Name shown in the control panel exactly, since the paste-in setup instructions key off that name.
2Paste the same MCP URL. No Client ID is needed: Grok self-registers via DCR (RFC 7591) exactly like ChatGPT.
3Click Connect and enter the Passphrase on the local confirmation page to approve.

Notion

Self-registers, no Client ID or Secret

1Enable custom MCP servers in your Notion workspace settings (a workspace admin may have to).
2Open Notion connections (notion.so/my-connections) and add a Custom MCP server with the MCP URL from the panel: https://your-machine.ts.net/mcp.
3Enter the Passphrase when AKIMCP opens its confirmation page. Connect with the passphrase, never with the access token pasted as a bearer: that copy stops working at every Roll token.
4Add the connection inside an agent, then republish the agent so the published agent can use it.

Gemini

Experimental, paid tiers only, not recommended

1Needs a paid Gemini tier (Pro / Business / Enterprise). The free tier may not expose custom apps.
2Open custom connected apps (Gemini → paid subscriptions → Custom apps) and set the custom app link / Server URL to the MCP URL.
3Under Advanced Settings, paste the OAuth Client ID and Client Secret that akimcp prints at start. It is a confidential client; the Claude connector no longer needs them.
4Ignore Gemini’s Copy redirect URI button (the redirect is already allowlisted), then enter the Passphrase on Continue.

Caveat: the OAuth handshake succeeds and Gemini accepts the instructions, but in repeated testing it did not reliably discover or drive the MCP tools. The connection is healthy, but tool use is unreliable. Claude and Grok are the dependable clients today.

Support

Donate me a coffee

Aki MCP Server is free and open source. If it saved you time, a coffee keeps it going.