MCP Pin

What mcp-pin MCP server does

The mcp-pin MCP server addresses a gap in MCP client approval flows: a server can return different tool definitions after a user has approved it. It protects local stdio servers by recording the approved metadata and comparing future responses against that record.

Its local proxy covers each tool’s full metadata, prompts, and instructions to the model. If any of these change, the proxy stops the session and reports a diff instead of forwarding queued client traffic. It continues checking tool and prompt listings during the session, so a server cannot pass an initial check and then present different definitions later.

The project also maintains a public record of MCP server versions. A crawler collects tool definitions on a schedule, while an append-only, hash-linked log preserves history. The records are signed, downloadable, and independently verifiable. The public site provides history, diffs, badges, and RSS according to the README.

How it works

The proxy sits between an MCP client and a local server. On approval, it fingerprints the server metadata and stores the resulting pin locally. On each connection, it derives the values again and compares them with the stored pin. A mismatch blocks the connection and displays the difference. Client traffic waits for this check to finish, so requests are not sent to a server that has already failed verification.

The implementation supports the 2026-07-28 MCP protocol, which does not use an initialize handshake, as well as earlier protocol versions. The public crawler follows tools/list pagination. Records made by versions up to 0.1.0 may therefore represent only a lower bound for paginated servers.

Setup and configuration

Run the bundled demonstration with:

npx --yes mcp-pin@1.0.4 demo

The example uses a temporary directory, does not call a tool, makes no network requests, and removes its temporary data afterward. It shows one session pinning a tool and a later session being blocked after the tool description and schema change.

To protect configured local servers in one operation, run:

npx --yes mcp-pin@0.2.3 wrap

The command can find configurations for Claude Desktop, Claude Code, Cursor, VS Code, Gemini CLI, Windsurf, Cline, and Codex. It displays planned changes, saves backups under ~/.mcp-pin/backups, and inserts the proxy before local servers. Use mcp-pin unwrap to reverse the change, or mcp-pin wrap --config <file> for another configuration file. Shared project .mcp.json files require --project. Restart affected applications after wrapping.

Remote URL servers are not changed because the proxy supports stdio only. The npm package is the relevant distribution; the similarly named PyPI package is unrelated.

Tools and capabilities

The mcp-pin MCP server can be added to an MCP client using the normal server configuration. According to the README, an agent can use it to check a public server before installation and identify local servers awaiting review after a block. Claude Code also has a plugin with lookup tools, a pre-trust checking skill, and a session note for local servers that are not protected.

The project provides a local drift-blocking proxy, persistent pins, session-wide listing checks, a scheduled public crawler, signed hash-linked records, downloadable verification data, diffs, badges, and RSS. It uses deterministic hashing rather than asking a model to judge whether a change is dangerous.