mcpock
A small Mac menu bar app that checks every MCP server your AI agents use, and
tells you which ones are broken, slow, waiting for a sign-in, or set up
differently from one agent to the next.
MCP (Model Context Protocol) servers are the small programs that give agents
like Claude Code, Cursor or Codex their extra tools. mcpock finds them in your
agents' config files, starts each one the way the agent would, and checks that
it answers.
Why
When you use more than one agent, the same MCP server ends up in five config
files, each written a little differently. One day a tool quietly stops working
in one agent and not the others, and you only notice when a task fails halfway.
The agent rarely says why.
mcpock gives you one place to look. It never changes your configs: it reads
them, checks every server, and shows you what needs attention and why, so you
(or your agent) can fix it.
What's new in 1.12
- Grok Bot: listed under its own name as soon as it is installed, on the
Agents tab and in Settings > Agents, even with no servers yet. Its servers
live in your xAI account and run in xAI's cloud, so mcpock lists them and
never starts them. Since 1.12.2 its rows show a mark drawn after its own app icon.
- Antigravity: its servers are read from
~/.gemini/config/mcp_config.json.
- Lost in a session: a server that dropped inside a Claude Code session that
is still open says so ("Lost in 1 open Claude Code session: run /mcp there").
- Your own shortcut: pick the keys that open the panel in Settings > General.
- Checks every 15 minutes instead of every minute, and reads only the config
files that changed. Refresh still checks everything at once.
- Usage note: a one-time note says the call counts come from your agents'
chat history on this Mac, with Turn Off right there. In 1.12.1 it sits under
the list instead of covering it.
Full notes: 1.12.0, 1.12.1, 1.12.2.
What it does
-
Finds your servers automatically. It knows the config files of the common
agents and also scans the usual config folders for anything written in a
standard MCP format. The same server in several agents shows as one row.
-
Checks each one. It starts a local server (or calls a remote one), does
the MCP handshake, asks for its tool list, then closes it. Every 15 minutes
by default (1 minute to 4 hours, or only when you click Refresh). Each round
reads the config files it already knows again, so changed servers show up; a
config file in a new place is found at launch or when you click Refresh. A server that is already fine
keeps its tool list between rounds; Refresh and Check again ask for it anew.
-
Shows health as a shape, not only a colour:
| Shape | Means |
|---|
| Filled dot (green) | Fine: it started and listed its tools |
| Ring (amber) | Slow (no answer in 20 s, tried twice; 10 s for a remote server) or needs sign-in (HTTP 401/403) |
| Ring (grey) | Still checking |
| Diamond (red) | Broken: could not start, quit on start, or refused the handshake |
| Dash (grey) | Paused by you, or runs inside its own app and can't be checked from outside, or Needs Wake open: it belongs to a Mac app that is closed (not broken; it is checked again as soon as the app opens) |
-
Spots servers set up differently. When one agent launches a different
command or address than the others (often an old path), the row says so, and
Compare shows each agent's version side by side. The same runtime in
another folder (npx here, an agent's own ~/.agent/node/bin/npx there) is not a
difference. If the agents are
meant to differ, choose Mark as intended on the card (or Mark as
Intended in the right-click menu).
-
Problems first. The list starts with Needs you, then your pinned
servers, then everything else. One toggle in the footer shows only problems.
-
Agents tab. The panel opens here: one row per agent with a small health
bar that grows in after each check. Open an agent to see its servers (the
first 5, +N more for the rest; servers that need you always show) and
its config file. With the problems toggle on, agents with nothing wrong
stay listed below, faded.
-
Next to each server under an agent: how many times that
agent called it in the last 7 days, 30 days or all time (Settings >
General > Usage, or Off). Read from the agent's own history on your Mac:
Claude Code, Grok, Cursor and Hermes today. A dash means that agent keeps
no record mcpock can read yet. The panel says so once, with a Turn Off.
Install
- Download
mcpock.dmg from the Releases page.
- Open it and drag mcpock to Applications. The app is signed and notarized
by Apple, so it opens without warnings.
- Launch it. mcpock lives only in the menu bar (look for the server-rack icon);
there is no Dock icon and no window.
Needs macOS 26 or later on Apple Silicon.
First launch, good to know:
- mcpock starts checking as soon as it launches, before you open the panel.
On a Mac with many agents the first check takes a while (slow servers get
20 seconds); the footer counts it ("Checking 12 of 30").
- If one of your servers lives in Documents, Desktop or Downloads, macOS
asks whether mcpock may open that folder. Click Allow: mcpock has to start
the server from there to check it. If you clicked Don't Allow, turn it on in
System Settings > Privacy & Security > Files and Folders (or Full Disk Access).
- Turn on Open at Login in Settings > General if you want it always there.
Quick start
- Click the menu bar icon. The panel opens on the Agents tab: one row per
agent, the ones that need you first; open one to see its servers. The
Servers tab lists every server, problems first.
- Click a row that needs you. The card says why, in plain words.
- Click Copy errors (or Ask an agent) and paste it to your agent, or
fix the config yourself.
- Click Check again on the card (or press Cmd-R) to confirm. It reads the
config file again first, so a fix shows up right away.
- Right-click any server for Pause, Pin, Hide, Copy Details,
Copy Errors and Ask an Agent (a prompt that asks an agent to look into
the problem and advise you before it changes anything). Pause a server
that opens a login page or an app each time it starts.
Connect your agents
mcpock includes mcpock-mcp, a small MCP server your agents can call. It only
reads the status file mcpock writes after each check
(~/Library/Application Support/mcpock/status.json); it never starts a server
and never changes anything.
The easy way: Settings > Connect > Copy for Claude, then paste into
Claude Code. The prompt walks Claude through finding your agent configs,
backing each one up, adding mcpock where it's missing (in each file's own
format) and testing it.
By hand: Settings > Connect lists your agents and shows which ones
already have mcpock (Connected, Not connected, Not on this Mac), with a copy
button per agent for the right line. mcpock only reads these files; you or
your agent paste the line. For Claude Code:
claude mcp add --scope user mcpock -- /Applications/mcpock.app/Contents/Helpers/mcpock-mcp
For agents that use mcpServers JSON (Claude Desktop, Cursor, Windsurf, Cline
and most others):
{
"mcpServers": {
"mcpock": {
"command": "/Applications/mcpock.app/Contents/Helpers/mcpock-mcp",
"args": []
}
}
}
Then ask your agent to "check my mcpock". The tools it gets:
| Tool | Answers |
|---|
mcpock_status | Counts: how many servers are fine, broken, slow, need a sign-in or are set up differently, and when mcpock last checked |
mcpock_problems | Every server that needs attention, with the reason, the agents and the config files involved |
mcpock_server | Everything about one server, by name |
All three are read-only. Secrets are masked (see below). If mcpock isn't
running, hasn't checked yet, or its results are old, the answer says so.
Try it from Terminal:
printf '%s\n' \
'{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"check","version":"1"}}}' \
'{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
| /Applications/mcpock.app/Contents/Helpers/mcpock-mcp
Supported agents
mcpock reads these files directly. Anything else that writes one of the
standard formats (JSON mcpServers, servers or mcp; TOML
[mcp_servers.*]; YAML extensions: or mcp_servers:) in ~/.config,
~/Library/Application Support or a hidden folder in your home folder is found
by the scan, with no code change. A server from a file only the scan found shows
Paused until you choose Resume once (right-click the row): mcpock never
starts a command from a file no agent it knows reads without your OK.
| Agent | Config file | Format |
|---|
| Claude Code | ~/.claude.json (global and per-project servers), and .mcp.json files the scan finds, but only inside ~/.config, ~/Library/Application Support or a hidden folder in your home folder, not in ordinary project folders (only the servers you approved in Claude Code) | JSON |
| Claude Desktop | ~/Library/Application Support/Claude/claude_desktop_config.json | JSON |
| Cursor | ~/.cursor/mcp.json | JSON |
| Windsurf | ~/.codeium/windsurf/mcp_config.json | JSON |
| Antigravity | ~/.gemini/config/mcp_config.json | JSON |
| Cline | ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json | JSON |
| Continue | ~/.continue/config.json | JSON |
| VS Code | ~/Library/Application Support/Code/User/mcp.json (servers) | JSON |
| Codex | ~/.codex/config.toml | TOML |
| Grok | ~/.grok/config.toml | TOML |
| Grok Bot | ~/.grokbot/settings.json (mcpBoxServers, names only) | Settings |
| Goose | ~/.config/goose/config.yaml (extensions:) | YAML |
| Hermes | ~/.hermes/config.yaml (mcp_servers:) | YAML |
| Kimi Code | ~/.kimi-code/mcp.json | JSON |
| MiniMax | ~/.minimax/mcp.json | JSON |
| OpenCode | ~/.config/opencode/opencode.json (mcp) | JSON |
| aka | Asked from aka's local helper (127.0.0.1:6464) while aka runs | API |
| Tinycast |
Notes: servers turned off with enabled: false are skipped. ${VAR},
${env:VAR} and ${workspaceFolder} are filled in before a check, from
mcpock's own environment and the project folder; a server that needs one
mcpock can't fill (like ${input:...}) reads Not checked. Servers marked
"builtin": true (they run inside their own app) are shown
but never started. aka keeps its servers in its own database, so mcpock
asks aka's local helper for the list (only when aka itself is the program on
that port) and starts each server the way aka does;
because aka launches servers its own way, it never counts toward "set up
differently". If aka asks for access before listing its servers (a newer aka
wants a token mcpock does not have yet), aka shows as Needs access. Tinycast keeps its servers in its own settings and their
keys and sign-ins in its own Keychain items, which mcpock never reads: a
Tinycast server that needs one shows as managed by its app, the others are
checked like any other. Grok Bot keeps its servers in your xAI account
and runs them in xAI's cloud; its settings file holds only their names, so
mcpock lists them under Grok Bot and never starts them. Grok Bot is listed
once installed (its app or ~/.grokbot), with "No servers yet" while its list
is empty. A remote server
written as serverUrl (Antigravity, Windsurf) is read like url. Thirty-one agents have their real logo in the app (Grok Bot since 1.12.2); others show two
letters.
Privacy and safety
- Read-only. mcpock never edits, moves or rewrites any config file.
"Open Config…" asks first, with Cancel as the default.
- What it runs. To check a local server, mcpock starts the exact command
from your config, with its arguments and environment, in its project folder
when it has one: the same thing your agent runs. It does the handshake, asks
for the tool list, then stops the process and all its child processes.
Remote servers get the same few requests over HTTP. Paused servers are never
started.
- Secrets are masked. The status file for agents holds env and header
names, never their values. Anything that looks like an API key in
command lines, URLs, server replies and error texts is masked wherever
mcpock shows or stores it.
- Network stays narrow. The only connections are to the remote MCP
servers in your configs, to aka on your own Mac if you use it, and
to mcpock.com to check for app updates (Settings > About). No
accounts, no analytics, nothing else phones home.
mcpock calls a remote server the way your config says,
http:// too. A
server whose config sends keys over plain http:// to another machine
gets a warning on its card: anyone on that network can read those keys.
- Updates are signed, and you're asked before the first automatic check.
mcpock checks mcpock.com for a newer version (Sparkle, its one dependency —
see docs/THIRD-PARTY.md); every update is verified
against a key only the maintainer holds before it installs. Turn automatic checks off
any time in Settings > About; "Check for Updates…" there always works.
- Usage counts read, never keep, your chats. To count calls, mcpock reads
the agents' own history files and databases (read-only) and keeps only the
agent, the server name and the day, in
~/Library/Application Support/mcpock/usage.json, plus, for each history file, the time of the
newest call it counted (so a rewritten file is never counted twice).
Never a message, an argument or a result.
Settings > General > Usage > Off stops the reading.
- Session logs, read only. To spot a server lost in an open Claude Code
session, mcpock reads
~/.claude/sessions/*.json (which sessions run, and
in which folder) and those sessions' lines in Claude Code's own MCP logs
(~/Library/Caches/claude-cli-nodejs), looking only at connect and failure
lines. Nothing is kept or sent.
- Where it looks. Only known config paths and the usual config folders.
The scan never looks inside Documents, Desktop or Downloads, and it skips
symbolic links so it can't be led anywhere else.
For developers
Build and run
You need macOS 26+, Xcode 26+ and XcodeGen
(brew install xcodegen).
git clone https://github.com/aka-kika/mcpock.git
cd mcpock
xcodegen generate
xcodebuild -scheme mcpock -configuration Debug \
-derivedDataPath build \
-destination 'platform=macOS,arch=arm64' build
open build/Build/Products/Debug/mcpock.app
Debug builds sign with an Apple Development identity (team in project.yml),
which keeps macOS folder permissions across rebuilds. Without that certificate,
add CODE_SIGN_IDENTITY=- CODE_SIGNING_REQUIRED=NO to the xcodebuild line
(that is what CI does).
Test
./scripts/ci.sh # xcodegen generate + build + test, same as GitHub Actions
811 unit tests at v1.12.2. They cover the
probes against real child processes and a real local HTTP server, process
cleanup, every config format, discovery and the scan's safety rules, grouping,
"set up differently", secret masking, the status file and the helper's
answers, and the panel's wording and layout.
How it works
- Discovery:
AgentRegistry (known paths) plus ConfigScanner (a shallow,
size-capped scan of the usual config folders) plus AkaSource. A file counts
only when it has at least one server with a command or a url, which keeps
unrelated JSON out. TOML and YAML are read by small built-in parsers.
- Probing:
HealthMonitor probes every server in parallel off the main
thread. stdio servers get newline-delimited JSON-RPC (initialize,
tools/list) and are then stopped along with their child processes. HTTP
servers get the same over streamable HTTP (session id replayed) or legacy SSE.
Identical setups are probed once. A single timeout shows as slow, a second one
or a hard failure as broken, and failing servers back off to hourly checks.
- Grouping: instances with the same name (case and separators ignored)
become one row; the worst state wins, and a launch target that differs from
the majority becomes a "set up differently" note.
- UI: a
MenuBarExtra panel of fixed size, with the detail card and tools
window as child panels beside it that never take focus.
- Agents: after each change the app writes
status.json and status.md;
the bundled mcpock-mcp (stdio, read-only) answers from that file.
The full module map, the flow of one refresh, and the rules that must not
regress are in docs/ARCHITECTURE.md.
Project layout
mcpock/ The app
MCPockApp.swift Entry point: the menu bar item and panel
Models/ Server config, health, groups
Services/ Discovery, probes, process runner, texts, status file
Theme/ Colours, fonts, appearance
Views/ Panel, rows, detail card, Agents tab, Settings
Assets.xcassets/ App icon, agent logos, About links
mcpock-mcp/ The read-only MCP helper (main.swift)
Shared/ Code compiled into both app and helper
mcpockTests/ Unit tests
project.yml XcodeGen spec (source of truth for the Xcode project)
scripts/ci.sh Local CI: generate, build, test
scripts/release.sh Release build, Developer ID signing, notarized DMG
scripts/appcast.sh Sparkle's signed update feed (appcast.xml) from a folder of release DMGs
docs/ Architecture, release notes, third-party credits
Adding an agent
If it writes a standard format into a scanned folder, it already works. Add a
row to AgentRegistry.known for a clean name or a path outside the scan; add a
ConfigShape and a parser for a new format; add a logo as an
agent-<name>.imageset plus a logoNames entry. Details in
docs/ARCHITECTURE.md §7.
Release
scripts/release.sh builds Release, signs with a Developer ID identity and
hardened runtime, notarizes and staples the app and the DMG, and writes
dist/mcpock.dmg. One-time setup, storing an app-specific password in your
keychain:
xcrun notarytool store-credentials my-notary \
--apple-id "[email protected]" --team-id <TEAMID> \
--password "<app-specific password from appleid.apple.com>"
MCPOCK_NOTARY_PROFILE=my-notary MCPOCK_SIGN_IDENTITY=<identity hash> ./scripts/release.sh
You can put the two variables in scripts/release.env (git-ignored, see
scripts/release.env.example) instead. Without them the script stops with an
error. It also stops if docs/release-notes/<version>.md is missing, if the
tests (scripts/ci.sh) fail, or if Gatekeeper rejects the app.
Uninstalling
- In each agent's MCP config, remove the
mcpock entry you added in
Connect your agents (mcpock never edits your configs, so it did not add
one for you).
- In mcpock, open Settings > General and turn Open at Login off.
- Quit mcpock from its menu bar icon.
- Delete
mcpock.app from Applications.
- Optional, to remove what it left behind (open Finder, press Shift+Cmd+G, and
paste each path):
~/Library/Application Support/mcpock (the status and usage files)~/Library/Preferences/com.mcpock.app.plist (your settings)~/Library/Group Containers/P5RB3W3D58.com.mcpock (shared with the widgets)
FAQ and troubleshooting
macOS asks for permission to open a folder.
One of your servers runs from Documents, Desktop or Downloads, and mcpock has
to start it there. Allow it once; it sticks. mcpock's own scan never looks in
those folders.
A server shows broken. What now?
Click it. The card shows the real error: "command not found" (the program isn't
installed, or isn't on the PATH mcpock uses: it adds /opt/homebrew/bin,
/usr/local/bin and ~/.local/bin; use a full path in the config if needed),
"quit on start" with the server's own error text (often a missing API key), or
no answer in time (20 seconds for a local server, tried twice; 10 seconds for
a remote one). Copy the error, fix it in the agent's config, then
Check again.
It says "Needs sign-in".
The server answered with HTTP 401 or 403 although its config sends a token
header: the token is likely wrong or expired. Fix the header in the config.
mcpock never signs in for you, so this state doesn't turn red.
It says "Signed in by the agent".
The server answered with HTTP 401 or 403 and its config has no token header:
you signed in inside the agent (OAuth), and the agent keeps that sign-in to
itself. Nothing is wrong, mcpock just can't check this server. It shows a
calm dash and stays out of Needs you.
What does "set up differently" mean?
The same server name launches a different command, script or address in one
agent than in the others. Sometimes that's intended; often it is an old path.
Compare on the card shows each version (secret values hidden).
If it's intended (say each agent has its own key and its own small launcher
script), click Mark as intended in the card's yellow box, or right-click
the row and choose Mark as Intended. The row stops counting as a problem, but
mcpock keeps checking it and still shows real errors. mcpock remembers how the
agents were set up at that moment (a short fingerprint of each command or
address, never keys or env values), agent by agent. If an agent's setup
changes later, or a new agent sets it up another way, the note comes back on
its own for that agent; an agent you remove keeps the mark quiet. The card then shows a quiet "Marked as intended" line;
Undo there, or Unmark as Intended in the right-click menu, takes it
back.
A login page or an app opens every time mcpock checks.
Starting that server has a side effect. Right-click it and choose Pause:
mcpock won't start it again until you resume it.
The grey dash?
Either you paused the server, or it runs inside its own app (marked
"builtin": true) and can't be checked from outside. Neither
counts as a problem.
I added a server and it doesn't show.
Click Refresh in the footer: it looks for configs again and checks
everything. The timer reads the configs again every round too, so the new
server also shows up on its own at the next round.
My agent says mcpock isn't running or hasn't checked yet.
Make sure mcpock is running (start it from Applications if its icon isn't in
the menu bar). It starts checking at launch and writes the status file once the
first check is done, then ask again.
Hidden servers?
Still checked, just not listed. A hidden server that breaks comes back to the
panel until it works again. Change it in Settings > Servers.
Thanks
mcpock's interface was shaped by studying these open-source Mac apps, found and
kept with reshelf
(site), the author's app for collecting
repos. Thank you to their authors:
- RepoBar by @steipete: dashboard rows, detail on demand, pinned and hidden in Preferences.
- Skills Manager by @yibie: the "which agent uses what" view and showing set-up-differently states.
- mectrics by @farukkamcici: a quiet menu bar icon that only speaks up when something's wrong.
- cctop by @st0012: sorted by what needs you, keyboard first.
- AgentBar by @michalstrnadel: real agent marks instead of text.
- Hop by @antonyshakirov: tabs in a menu bar panel.
- TokenMon by @faulknerpearce: a section per agent with a small bar.
Credits
In-app updates run on Sparkle
(MIT), mcpock's one code dependency.
Agent logos come from LobeHub Icons
(MIT) and, for Zed, Warp, JetBrains and Raycast,
Simple Icons (CC0). They are
trademarks of their owners; mcpock is not affiliated with or endorsed by any of
them. Details and license texts: docs/THIRD-PARTY.md.
Contributing
Issues and pull requests are welcome. See CONTRIBUTING.md.
License
MIT. See LICENSE.
Made by Kika · akakika.com · X @akakikaaa · GitHub aka-kika
