Demo control panel sẽ mở trên máy bạn ở 127.0.0.1:9998 khi AkiMCP chạy. Cứ thử các công tắc: không có gì thật bị đổi.Về trang chủ
Local AI control plane

AkiMCP

v4.2.0

Secure access to local files and shell for web AIs and local tools, through one OAuth-gated endpoint.

Local panel127.0.0.1Tailscale FunnelPID 4242Started 2026-11-16 16:54:58 (up 2h 14m)

Running repo: /Users/demo/aki-mcp-sv · Config & keys: /Users/demo/.aki/mcpsv

Setup steps

  1. Ingress
  2. 1 Connectors
  3. 2 Install rules
  4. 3 Instructions
  5. 7 Security
0 · Remote ingress (Web & Mobile AI) — optionalingress active

AkiMCP is live at https://demo-host.ts.net through Tailscale Funnel. Expand this card only when you need to change ingress.

Cloudflare Tunnel is the recommended ingress (the "Owned public origin" tab): it holds a steadier connection, carries more bandwidth and answers from a far larger global network than Tailscale Funnel. Funnel needs no domain and npm start sets it up by itself, so it is what runs until you choose otherwise.

Complete these one-time prerequisites in order.

You're viewing this panel, so the first three below are already done; the two Tailscale checks are live.

  1. Install @akinet/akimcp (or clone repo).
  2. Started with akimcp (or npm start), running now.
  3. … Install Tailscale and sign in.
  4. … Enable Funnel for your tailnet, free on every plan. npm start enables it automatically; it only prints a link for you to approve once, when the tailnet hasn't allowed it yet.

Connector keeps dropping with "hostname doesn't resolve / isn't reachable"? The Funnel edge desynced, a Tailscale-side issue, not this server. Re-sync in a terminal (needs sudo, so it can't be a button here), then reconnect. Why: docs/research/claude-ai-oauth-connector.md round 9.

tailscale funnel --https=443 off && tailscale serve reset && tailscale funnel --bg 9999

Funnel works with no domain, but a Cloudflare tunnel is steadier and faster: when you have a domain (or someone gave you a tunnel file), switch in the "Owned public origin" tab.

Replaces Tailscale entirely; OAuth and the tool suite stay the same.

Have a Cloudflare tunnel credentials JSON?

No tunnel yet? README: Exposing to the internet.

Or: any HTTPS edge you already run

Set PUBLIC_ORIGIN in .env (copy from .env.example), or prefix the start command: PUBLIC_ORIGIN=https://your-host npm start

Pick a domain and subdomain, then request it via Messenger; setup is manual, not self-serve yet.

Worth it over the free Tailscale + Funnel tab if you want a short, memorable URL instead of Tailscale's auto-generated *.ts.net hostname.

1 · Connectors: local IDEs + web AIs

One AkiMCP endpoint, two paths: pick one with the switch below. Each Local tab says how that tool connects and carries a ready-to-paste config. Web AIs use the MCP URL below and are reachable now.

The name AI clients list this server as. The Server ID and Tool prefix below are made from it as you type; to set either one yourself, open Customize fields.

akimcp
aki__
aki__run_cmd

What each AI shows

mcp__akimcp__aki__run_cmd
mcp__akimcp__aki__run_cmd

Web AIs put the connector name you typed in front of each tool, for example AkiMCP__aki__run_cmd in ClickUp. Type AkiMCP as the connector name.

Serving now: AkiMCP · Server ID akimcp · tools aki__*

Customize fields

The name client configs store this server under. Lowercase letters and digits, starting with a letter.

Text in front of every tool name. Leave it empty to use bare names, for example run_cmd; an AI that also has another server with a tool of the same name may then call the wrong one.

https://demo-host.ts.net/mcp
••••••••••••
••••••••••••

One access token serves every client. Roll token replaces it: AIs connected with the passphrase refresh on their own (ClickUp may need one reconnect), but a token pasted as a fixed bearer (a local snippet below) stops working until it is pasted again. Connect Notion with the passphrase like the other web AIs, never with a pasted token. Roll & sign out all clients also revokes refresh, so every AI must reconnect with the passphrase; use it if the token may have leaked. Roll passphrase issues a new one: the old passphrase stops authorizing new connections, while already-connected AIs keep working; use it if the passphrase may have leaked. Temporary tokens (Web → Any HTTP chat) expire on their own or are revoked one by one; Roll & sign out all clients revokes them too.

↗ Open Add custom connector

  1. Enter Name = Display name above.
  2. Enter URL = MCP URL above, then connect.
  3. Enter the Passphrase when AkiMCP opens the confirmation page.

Claude now discovers OAuth automatically. No Client ID or Client Secret is needed.

A connector added here belongs to your Claude account: claude.ai, the Claude app and the mobile app all reach it from Anthropic's cloud, so it needs the ingress even on this computer. On the computer running AkiMCP, the Claude Code & app tab under Local connects without one.

  1. Open Connectors → New Connector → Custom.
  2. Set Name = Display name above, Server URL = MCP URL.
  3. On connect, enter the Passphrase.

Name must match exactly, the paste-in instruction keys off it. Grok self-registers via PKCE, nothing else to paste.

↗ Enable Developer mode · Settings → Security and login

↗ Create a connector

  1. Turn on Developer mode first. OpenAI requires it to create custom MCP apps.
  2. Pick an Icon (optional). Download icon or use any image.
  3. Enter a Name and Description (your choice).
  4. Set Connection → Server URL = MCP URL above.
  5. Tick I understand and want to continue, then Create.
  6. On connect, enter the Passphrase.

ChatGPT self-registers via DCR (PKCE, no secret). Nothing to paste. Write tools may be limited depending on OpenAI's current policy.

Paid tiers only. Tested 2026-08-09: the connection is healthy, but Gemini web doesn't reliably discover or invoke the MCP tools, use Claude or Grok instead. Not recommended.

  1. Open custom connected apps (Gemini → paid subscriptions → Custom apps) and add a custom connected app.
  2. Paste the MCP Server URL = MCP URL above.
  3. Click Next. Gemini links the account by itself.
  4. Enter the Passphrase when AkiMCP opens the authorization page.
  5. Click Approve.

Gemini registers itself, nothing to paste. The static Client ID / Secret that akimcp prints at start is an optional fallback for clients that want a fixed pair.

↗ Open Notion connections

  1. Enable custom MCP servers in the Notion workspace settings (a workspace admin may have to).
  2. Add a Custom MCP server with the MCP URL above.
  3. Enter the Passphrase when AkiMCP opens the confirmation page.
  4. Add the connection inside the agent, then republish the agent.

Notion self-registers, nothing to paste. Connected this way it refreshes on its own after Roll token.

  1. In Buda, open Agent Settings → your Agent → Integrations, then click Add MCP server.
  2. Set Name = Display name above.
  3. Set Connection type = Remote HTTP.
  4. Set HTTPS endpoint = https://demo-host.ts.net/mcp
  5. Under Authentication headers, click + Add header, then set the header name = Authorization
  6. Set the header value:
••••••••••••
  1. Click Save, then start a new chat to load the tools.

Buda sends the shared access token as a Bearer header. No passphrase or client registration. After Roll token, paste the new header value again.

  1. In ClickUp, open Settings → App Center → MCP Servers → Connect an MCP Server.
  2. Set Name = Display name above, URL = MCP URL.
  3. Set Authentication Method = OAuth. Leave Advanced configuration closed, then click Next.
  4. In the tab ClickUp opens, enter the Passphrase and approve. ClickUp continues on its own.

ClickUp registers itself, so there is no Client ID, Secret or token to paste. After Roll token, reconnect it once in ClickUp if it stops answering. ClickUp Brain then uses AkiMCP's tools when a request needs them, without a mention.

For web chats with no custom MCP connector that can still send HTTPS requests (WorkBuddy, CodeBuddy, Postman Agent, a chat with a code sandbox). Mint a temporary token that lasts 4 hours and paste the kickoff block into the chat. The list below shows when and from what each token was last used; +30 min extends a live one. When the task is done, tell the AI to revoke its token, or click Revoke below. Your shared token and every connected AI are untouched. Restarting AkiMCP also revokes every temporary token.

  1. In your AI, add a custom connector with the MCP URL above.
  2. If it cannot connect, its refused sign-in address shows below: click Add.
  3. Connect again and enter the Passphrase.

Adding a new AI needs this computer once.

Refused since AkiMCP started

Your sign-in addresses

Remove stops new sign-ins through that address. To cut off an AI already connected through it, use Revoke & roll on it in section 7 Clients, or Roll & sign out all clients.

Any app that takes an MCP JSON

This is the usual JSON for adding an MCP server: Postman and Cursor take it as is, and so does any other app whose MCP settings accept an mcpServers entry with a url and headers. Click the JSON to copy it, then paste it where the app adds an MCP server, keeping any servers already there. It reaches this computer over 127.0.0.1, with no tunnel. After Roll token, paste it again. An app that can only start a command (stdio), like the Claude app or AGY, uses its own tab.

{"mcpServers":{"akimcp":{"url":"http://127.0.0.1:9999/mcp","headers":{"Authorization":"Bearer ••••••••••••"}}}}

Your config may still have entries named aki-mcp; delete them.

From another computer (via the section 0 address)
{"mcpServers":{"akimcp":{"url":"https://demo-host.ts.net/mcp","headers":{"Authorization":"Bearer ••••••••••••"}}}}

The aki__ tools run on the machine running AkiMCP, not on the computer you paste this on. The token is stored in plain text on that computer. After Roll token it stops working there until the new snippet is pasted.

Control the Postman app

This launch attaches control that opening Postman from the Dock/Spotlight does not: it auto-clicks Approve / Continue / Run / Try again and toggles Thinking / Auto-run inside the Postman window. If Postman is already open, this attaches to it — it does not open a second instance.

…

Connect Postman to this MCP

Postman runs on this machine, so it connects straight to the local engine on 127.0.0.1, with no tunnel. Click the JSON to copy, then paste it in Postman Connected Accounts.

↗ Open Connected Accounts

{"mcpServers":{"akimcp":{"url":"http://127.0.0.1:9999/mcp","headers":{"Authorization":"Bearer ••••••••••••"}}}}

Your config may still have entries named aki-mcp; delete them.

Setup screenshot:

Postman MCP setup walkthrough

Connect Cursor — local

Apply merges akimcp into ~/.cursor/mcp.json with the current token (other servers untouched), then reload Cursor. After Roll token, click Apply again. Or paste the JSON by hand (Cursor → Settings → MCP Servers). Connects over 127.0.0.1, with no tunnel.

{"mcpServers":{"akimcp":{"url":"http://127.0.0.1:9999/mcp","headers":{"Authorization":"Bearer ••••••••••••"}}}}

Your config may still have entries named aki-mcp; delete them. Apply does this for you.

From another computer (via the section 0 address)
{"mcpServers":{"akimcp":{"url":"https://demo-host.ts.net/mcp","headers":{"Authorization":"Bearer ••••••••••••"}}}}

The aki__ tools run on the machine running AkiMCP, not on the computer you paste this on. The token is stored in plain text on that computer. After Roll token it stops working there until the new snippet is pasted.

Claude Code and the Claude app are set up separately: connecting one does not connect the other. Both run on the computer running AkiMCP, with no ingress: Claude Code connects over 127.0.0.1, and the Claude app starts the tools itself over stdio. For claude.ai, the mobile app or the Claude app on another computer, use the Claude tab under Web; for the claude command on another computer, use From another computer below.

Claude Code (terminal) — local

Apply registers akimcp in user scope with the current token, replacing any old entry so it works from every project. It also removes the entry an older setup left under its old name, including inside a single project, which would otherwise keep the old token there. After Roll token, click Apply again. Or run the two lines below by hand (the remove first lets a re-paste replace the old token — a bare add refuses when the entry already exists);

If one project still gets 401 from an entry an older setup left there, run claude mcp remove <name> -s local inside that project, for each of aki-mcp.

claude mcp remove akimcp -s user claude mcp add --transport http -s user akimcp http://127.0.0.1:9999/mcp --header "Authorization: Bearer ••••••••••••"

Your config may still have entries named aki-mcp; delete them. Apply does this for you.

From another computer (via the section 0 address)
claude mcp remove akimcp -s user claude mcp add --transport http -s user akimcp https://demo-host.ts.net/mcp --header "Authorization: Bearer ••••••••••••"

The aki__ tools run on the machine running AkiMCP, not on the computer you paste this on. The token is stored in plain text on that computer. After Roll token it stops working there until the new snippet is pasted.

Claude app (desktop) — local

  1. In the Claude app, open Settings → Developer → Edit Config. It opens claude_desktop_config.json.
  2. Merge the entry below under mcpServers, keeping any entries already there, and save.
  3. Quit the Claude app completely, then open it again.
{"mcpServers":{"akimcp":{"command":"node","args":["/Users/demo/aki-mcp-sv/scripts/stdio.js"]}}}

Your config may still have entries named aki-mcp; delete them. Apply does this for you.

The app starts AkiMCP's tools itself over stdio (scripts/stdio.js) with no token, so Roll token changes nothing here. If the app reports the server failed to start, replace node with the full path printed by which node (Windows: where node).

Connect Antigravity (AGY) — local

CLI (agy) and IDE: both read this file: merge the entry below under the existing mcpServers key in ~/.gemini/config/mcp_config.json, but don't overwrite the file. It registers a stdio command that spawns scripts/stdio.js (the local /mcp is Bearer-gated, so stdio is the transport that works without a token). The pre-allow below writes antigravity-cli/settings.json and covers the CLI only; the IDE asks for its own approval on the first tool call.

{"mcpServers":{"akimcp":{"command":"node","args":["/Users/demo/aki-mcp-sv/scripts/stdio.js"]}}}

Connect Codex CLI — local

Apply writes the [mcp_servers.akimcp] table into ~/.codex/config.toml with the current token, replacing it in place and dropping the table an older setup left under its old name (other tables untouched), then restart Codex. After Roll token, click Apply again. Codex reaches the local engine over 127.0.0.1 via streamable HTTP; the bearer token is inlined, no env var to export. No tunnel needed. To paste by hand, replace any existing [mcp_servers.akimcp] table — do not add a second one.

[mcp_servers.akimcp] url = "http://127.0.0.1:9999/mcp" http_headers = { "Authorization" = "Bearer ••••••••••••" }

Your config may still have entries named aki-mcp; delete them. Apply does this for you.

From another computer (via the section 0 address)
[mcp_servers.akimcp] url = "https://demo-host.ts.net/mcp" http_headers = { "Authorization" = "Bearer ••••••••••••" }

The aki__ tools run on the machine running AkiMCP, not on the computer you paste this on. The token is stored in plain text on that computer. After Roll token it stops working there until the new snippet is pasted.

2 · Install AkiDevRule (optional)

Pins how the AI writes, self-corrects, and names things into rule files loaded only when needed, so it stops re-guessing every session.

npx @akinet/akidevrule@latest

Runs on Mac/Linux/Windows — only needs Node.js 18+. Re-run the command above to update, or add --check to print installed-vs-latest without changing anything. From a local clone: node install.mjs (or launchers install.sh / install.ps1). No sudo; installs into every detected ~/.claude* profile plus ~/.aki, removable with rm -rf.

View repo ↗ Not installed

3 · Instructions: copy the prompt

Paste it once into the custom-instructions setting of each AI (links below). It is static: tool details and the rule context come from the server itself, so it never needs re-pasting.

4 · Tool providers

Each provider is a group of tools the AI sees. One that is not installed on this machine (Chrome, Postman, agy, kiro-cli) is hidden automatically; switch off one you do not use to keep the AI's tool list short. The agy and Kiro CLI tools start off, because each hands a whole task to another paid agent: switch them on here when you want them. Rule context, files, search and shell are always on.

A switch applies on this server at once. An AI client sees it the next time it lists tools, which for most clients means a new chat or reconnecting the connector. After installing or removing an app, press Detect again.

5 · Folders the connector may reach

These folders scope file tools and the shell's working directory. Allowed shell commands run with your user permissions and may access files outside this list.

The default root is your whole home folder: Desktop, Documents, Downloads, Photos, everything under it, not just projects.

Save takes effect immediately for every tool (shell, search, and file read/write/edit alike) — no restart needed.

6 · Allowed shell commands

This is a guardrail for weak or overeager models, not a lock against you. It lets them work without approval prompts while keeping them off destructive commands; convenience comes first, so widen it freely for your own needs. Commands run as your user, so they can read what you can. Chips allow any subcommand; click a chip to restrict it to specific subcommands. Adding write commands (rm, git commit…) widens access. A restricted git row lets branch, tag and remote run in their read forms only; press any to allow every git command.

What each limit covers: this list bounds the shell command tool only. Section 5 (folders) bounds the file, search and git tools and where shell commands may run. The AGY and Kiro tools run in a locked mode of their own. Details: docs/feat/tools.md.

Trusted script directories

Scripts under these folders run without a command row above, so installed Aki skills work out of the box. The file tools cannot write into them, so the AI can't plant a script and run it; keep them to folders only an installer writes.

7 · Security & connection limits

What this protects: the public address is reachable by anyone who learns it, and the only thing between them and your machine is the passphrase. A caller that keeps presenting wrong credentials is blocked for a while; a caller with a valid token is never counted or blocked, and neither are mistyped URLs (404) or malformed requests (400). Connecting many providers in a row is safe — only wrong credentials count.

When a block ends: automatically after the block time below (the counter restarts from zero), immediately when you press Release, or when this app restarts. Callers are told by their public address; if your tunnel does not forward it, all remote callers share one address named loopback, so one attacker could block remote access until you release it. Changes apply from the next request, no restart.

Blocked right now

Clients

Every AI app that asked to connect. Signed in means it can keep renewing access on its own. A connection that was never approved is cleared after 1 hour; one that is no longer signed in is cleared after 30 days without activity. A client that never got a token has only Delete. For the others, Revoke & roll removes the client and rolls the shared access token, so it loses access at once; every other client is affected too: signed-in connectors renew on their next request (ClickUp may need one reconnect), while Buda and the local Claude Code, Codex and Cursor snippets need the new token (click Apply again or re-paste). Remove only (Sign out only for the pre-issued client) keeps the shared token, so that app keeps working until you press Roll token in section 1.

Active now (since last restart)

Don't recognize a client or a caller? Roll the passphrase and use Roll & sign out all clients in section 1.

8 · AIObox

All your AI. Working together.

Every AI account you pay for works as one team: a chat that fills its account carries on in another, chats pass work to each other and keep going by themselves, and they call you only when they need you.

  • Every AI account signed in at once, each in its own Chrome profile, still signed in after a restart.
  • Connect AkiMCP to each account in one click, with no URL or passphrase to copy.
  • The usage left on every account of every provider, in one place.
  • Your own AI drives it through the AkiMCP you already run: it opens chats in other accounts and passes work between them.

Free during the closed beta, for AkiDev members: join through akidev.org, then download with the code posted in the AkiDev Telegram group.

9 · Logs

Call log

Every tool call that reaches AkiMCP through its /mcp URL is written to /Users/demo/.aki/mcpsv/tool-calls.jsonl as one JSON line: when, which tool and op, ok or not, how long, which client. Calls through the local stdio command (scripts/stdio.js) are not written. No prompt, expression or argument text is ever written.

Basic (the default) keeps a short error code; Detail adds the full error text, the chat it acted on (from) and a hash of eval expressions. Keep days is how long past day-files stay before being deleted; the MB cap rolls the current file over to a dated one when it grows.

Security log

Wrong passphrases, rejected tokens, blocks, approvals and new callers — newest first, the last 200 lines. Saved to ; at 1 MB it moves to security.log.1, so it never grows past about 2 MB.