Model Context Protocol Documentation: A Mac-First Read
Model Context Protocol documentation is the spec for how a coding agent talks to local tools: the client lists tools, the server implements them, and JSON-RPC messages move over a stdio or HTTP pipe. That sentence is the whole protocol. Everything else is a particular server.
Most people bounce off the official docs because they explain sockets without a Mac example. This page is the example: a local capture server that returns a named UI element.
Where is the official Model Context Protocol documentation?
Anthropic published the protocol and hosts the canonical docs and schema. GitHub holds the spec repo and example servers.
Start there for transports, capability negotiation, and tool calling. Do not start there if you only wanted "how do I add a server to Claude Code."
The Model Context Protocol explainer is the concept. What is an MCP server is the process. MCP server examples is a list. Claude Code MCP is the client that developers here actually run.
PinVari's agent-facing pages live at pinvari.com/mcp. That is product documentation for one server, not a fork of the spec.
Read the official Model Context Protocol documentation for the wire format. Read a product's MCP page for the tool names and the payload you will debug at 1 a.m.
What should Model Context Protocol documentation contain?
A useful MCP doc has five parts. If a README skips them, you will guess.
Install. The exact binary or command, with flags. Bare names error.
Lifecycle. Does the host app need to be running. What port. What happens on crash.
Tools. Name, arguments, return shape, error shape.
Auth and privacy. Local only, or a cloud hop. What leaves the machine.
A worked example. One tool call, one real payload.
PinVari's answers, as facts: the connector is ~/.pinvari/mcp/pinvari-mcp. The app talks on 127.0.0.1:3402 and must be installed and running. Nothing is uploaded by default. No API keys for capture. You bring the agent.
claude mcp add --scope user pinvari -- "$HOME/.pinvari/mcp/pinvari-mcp"Never claude mcp add pinvari by itself. One click inside PinVari → Connect wires Claude Code, Cursor, VS Code, or Codex without the CLI.
Which tools should the documentation list?
For this server, the documented tools are:
pinvari_next_instruction. pull the next resolved capture.
pinvari_get_capture. fetch a specific one.
pinvari_list_captures. see the queue.
pinvari_get_frame. the screenshot frame for a mark.
pinvari_request_capture. ask the human to point. The notch island lights up.
pinvari_mark_done. close the item.
pinvari_health. is the app reachable.
What pinvari_next_instruction returns is the part generic MCP docs will never tell you: circled region, resolved element (role, label, frame, confidence, circled-vs-dwelled provenance), spoken instruction split per mark, typed notes, cropped screenshot.
Around that, spatial context: focused-window text up to 40,000 characters including scrolled-off copy, an interactive-element map, optional whole-screen on-device OCR, browser URL from AXWebArea, selected text, pointer trail.
Vague speech can be flagged UNSPECIFIC. Ask, never guess.
If you are writing your own MCP server, copy this shape: one "give me work" tool, one "I finished" tool, one health check. Agents stall when the only tool is a blob of text.
Model Context Protocol documentation vs computer-use docs
Computer-use docs describe a model that looks at screenshots and emits clicks. MCP docs describe a pipe.
You can wrap computer use as an MCP tool. You can also wrap a named-element capture as an MCP tool. Those tools do not substitute for each other.
Hit-testing AXUIElementCopyElementAtPosition is a Mac fact, not a protocol fact. The spec does not know about chainExcludingSelf, AXManualAccessibility, or labeledDescendant. Product documentation has to say those names.
Electron's lazy AX tree, Chromium's AXDOMIdentifier and AXDOMClassList, dwell of about 0.2s, per-mark word buckets, multi-display marks, pause/resume (⌥⌘P). all of that belongs on pinvari.com/mcp or in a guide like this, not in the protocol schema.
Do not treat a blog post as the spec. If the schema and a vendor README disagree on a field name, the schema wins. If they disagree on a product tool, the product README wins.
A documentation-driven install on a Mac
- Skim the official spec far enough to know tools are JSON-RPC, not magic.
- Install Claude Code or Cursor. Confirm MCP is enabled.
- Install PinVari from the notarized Developer-ID DMG (macOS 14+, Apple Silicon or Intel).
- Connect with the one-click path or the full
claude mcp add --scope usercommand. - Hold ⌥⌘A, circle a control, speak. In the agent, call
pinvari_health, thenpinvari_next_instruction. - Read the payload. Check confidence. Mark done.
Hotkeys the docs should mention: ⌥⌘A mark, ⌥⌘V voice-only, ⌥⌘P pause/resume.
Captures collect in the notch island and the Command Center, grouped by app, with crash-safe recovery. The agent can request another point mid-task.
That is a complete reading of "local MCP server on a Mac." The official Model Context Protocol documentation will never be this concrete, and it should not be. It has to stay vendor-neutral.
How to read MCP docs without drowning
Read transports only if you are implementing a server. stdio versus HTTP matters to authors, not to someone adding one connector.
Read tool lists if you are a client user. Names and return fields are your debugger.
Read security if the server can see the screen or the filesystem. A 127.0.0.1 capture tool that never uploads by default is a smaller grant than a cloud browser operator.
Read versioning when something breaks after an app update. Capability flags exist so old clients do not call new tools blindly.
The MCP tools page is the catalog cut. Pair it with the official schema when you implement, not when you only connect.
Launch pricing for the capture app is $39 for the first 500 licenses, then $59, Polar, team seats, no subscription on the core app. The pricing block is the product number. The protocol is free.
How Model Context Protocol documentation handles errors
Good docs show the failure, not only the happy path. A capture server that is not running should return a health error you can quote.
If pinvari_health fails, start the app. Do not reinstall the connector first. Most "MCP is broken" threads are a closed process on 127.0.0.1:3402.
If the tool list is empty, the client never launched the command you saved. Re-run the full claude mcp add --scope user line and reopen the client.
If the payload is missing a label, you landed on an AX-blind surface. That is an OCR or retry case, not a protocol bug. Product docs should say so, because the spec will not.
Write those three failures at the top of any MCP README you publish. Readers come to documentation when something is already red.
Print or bookmark pinvari.com/mcp next to the official spec tab. One is the socket. One is the payload. You will need both the first time a tool call returns an empty label.
If you teach this to a teammate, start with pinvari_health in the client, then one real mark. Documentation lands when the payload is on screen, not when the official schema is still abstract and unread.
FAQ
Where do I find Model Context Protocol documentation?
The official spec and schema from Anthropic and the spec repo on GitHub. Product-specific tool docs live with each server. For PinVari, that is pinvari.com/mcp.
Is there Model Context Protocol documentation for Claude Code?
Claude Code's own docs cover adding servers. The protocol docs cover the wire. You need both: one to install, one to understand why a tool list appears in the client.
Do I need to read the full MCP spec to install a server?
No. You need the install command, the requirement that the host app is running, and a way to test health then a real tool. Read the spec when you build a server or debug a transport.
What is the difference between MCP documentation and an API reference?
MCP documentation describes a standard way to expose tools. An API reference describes one HTTP API. A local MCP server may never open a public URL. PinVari's connector is a local process talking to 127.0.0.1:3402.
Why does claude mcp add pinvari fail?
The command needs a path to the connector and a scope. Use --scope user and "$HOME/.pinvari/mcp/pinvari-mcp". The app must already be installed.
Can I use Model Context Protocol documentation to build my own screen tool?
Yes. The spec tells you how to register tools. It does not tell you how to hit-test the Mac Accessibility API. That part is platform documentation plus your own code, or a server that already does it.
Hand your agent the exact element
PinVari resolves what you point at into a named, executable instruction — on-device, no keys, your own agent. One click inside PinVari connects Claude Code, Cursor, VS Code or Codex — or paste one CLI line from pinvari.com/connect.
PinVari → Connect → your agent (one click)Get PinVari — $39 →
