MCP Action Server vs Docs Server: Install Both, For Different Jobs

No. The MCP spec has three primitives: Tools (model-controlled functions), Resources (URI-addressable read-only data), and Prompts (user-controlled templates). 'Action server' and 'docs server' are how the ecosystem actually sorts servers by what they do with those primitives. An action server overwhelmingly uses Tools that mutate something. A docs server overwhelmingly uses Resources plus a small number of Tools that wrap reads (search, fetch, list versions). It is a taxonomy by intent, not by spec. The MCP architecture page (modelcontextprotocol.io/docs/learn/architecture) lays out the primitives; the action-vs-docs split is the lived practice on top of them.

Yes, and several try. The GitHub MCP server ships search_repositories and get_pull_request (docs-ish) alongside create_issue and merge_pull_request (action). The Postgres MCP servers expose schema and table info (docs) plus query and execute (action, when execute is wired). But the design pressure is real: docs-style reads tend to want readOnlyHint: true and zero confirmation, while writes need permission UX. Most production stacks split them so the read-only server can be auto-allowed and the action server can prompt the user. The macos-use server picked the other extreme: it is pure action with no docs surface at all, because the surface it cares about (a live UI tree) is too volatile to expose as a Resource.

Open Sources/MCPServer/main.swift in the macos-use repo. Line 1482 is the aggregate tools array: nine entries, all mutate state except refresh_traversal. Line 1524 registers a ListResources handler that returns ListResources.Result(resources: []). Empty array. The server publishes zero Resources. Line 1531 does the same for ListPrompts. The whole server is Tools. That structural shape, 'all Tools and no Resources,' is what a pure action server looks like. The opposite shape is a Context7-style server that publishes a Resource per indexed library plus a couple of search tools.

Resources are URI-addressable and cacheable. A client can list them, store them, and re-fetch by URI. They are designed for the read pattern. Resources also surface in client UI as something the user can browse, which makes the agent's reference material discoverable. Tools cannot do this; a Tool call is not a URI you can dereference later. For library docs (npm package X version Y, AWS service Z), Resources are the right primitive. For 'click this button,' a Tool is the right primitive because there is no stable URI for 'the click I did at 3:14pm on a window that no longer exists.'

Both, in practice. A coding agent needs to know things (current library APIs, internal docs, recent commits) and do things (write code, run scripts, drive a Mac app, click through a browser flow). Context7 or OpenAI Docs MCP for docs. Filesystem MCP for code edits. GitHub MCP for repo writes. macos-use for native GUI work outside the browser. Playwright MCP for browser flows. Pick one server per category. The agent's tool list ends up at 30 to 60 tools. The MCP clients (Claude Code, Cursor, etc.) handle the dispatch.

Yes. Resources are advertised as read-only by spec convention. Most MCP clients display them in a separate sidebar and do not prompt before reading. Tools route through the client's tool-execution path and may prompt depending on annotations (readOnlyHint, destructiveHint) and the client's policy. So a docs server that ships Resources gets a frictionless UX. An action server that ships mutate Tools should prompt, and the macos-use Tools each fuse a write with a tree read, so they cannot honestly set readOnlyHint: true. That is the right answer for UI driving (the user wants to see when the agent is about to click) and the wrong answer for a docs server (where prompting every reference lookup is noise).

Stale or wrong-version docs. A docs MCP server pulls reference material from somewhere (GitHub, npm, official docs site) and serves it to the agent. If the index is older than the version the user is on, the agent codes against the older API and produces calls that compile and then fail at runtime. The good docs servers expose a version parameter and let the agent pin (Context7 does this). The bad ones serve whatever they indexed last and pretend it is current. Always check whether a docs server can pin to your installed version before you trust it.

Drift between what the action server thinks the world looks like and what the world actually looks like. A click_and_traverse call returns the new accessibility tree, but if the agent does not look at the diff, it acts on the previous state. A filesystem write_file succeeds, but if a build process is watching the file, the next read sees the post-build version. A GitHub create_pull_request succeeds, but a status check could be running. Action servers are real-world side effects, so they have to return enough information about the post-action state for the agent to make the next decision. The macos-use server addresses this by returning a structured diff (added, removed, modified) on every Tool call.

If you only need macOS reference material (AppleScript dictionaries, framework headers, Apple developer docs), a docs server is not really what you want either, because Apple's stuff is unevenly indexed by the public docs servers. The honest answer: search the Apple developer site or run osascript -e 'tell application X to get the dictionary'. macos-use is for driving Mac apps, not learning about them. If you want to drive but do not have macOS, look at Terminator for Windows. If you want a docs index for your own codebase, Context7 or Outline MCP. Different jobs.

Usually. Look for the verbs. Action servers describe what they do: 'click,' 'press,' 'create,' 'send,' 'merge,' 'open,' 'type,' 'navigate.' Docs servers describe what they expose: 'docs,' 'reference,' 'docs index,' 'API explorer,' 'search.' The MCP marketplace listings are getting better about flagging this, but the fast check is the verb. If the verbs are imperative, it is action. If the verbs are interrogative or noun-y ('list,' 'get,' 'search'), it is docs. The macos-use Tool names are unambiguously action: open_application, click, type, press_key, scroll, set_value, press_ax, set_selected.

One, and only one: refresh_traversal. It walks the accessibility tree of a target application and returns a structured summary plus a file path. It does not mutate the world; it just inspects. It is the closest thing to a Resource that the server publishes, but it is still a Tool, not a Resource, because the tree is dynamic per-PID and has no stable URI. Everything else is mutate-and-observe. So 8 of 9 Tools are action and 1 is read, and there are 0 Resources. The shape is unambiguously action server.