Model Context Protocol Anthropic: Official MCP Guide

The Model Context Protocol (MCP) is Anthropic's open JSON-RPC standard for connecting AI coding agents to tools running on your local machine—filesystem access, database queries, screenshot capture, browser automation—without uploading anything to an API. Instead of pasting file contents into a chat or manually describing your screen, your agent calls an MCP server at 127.0.0.1, which reads the file, takes the screenshot, or queries the database and hands back structured data the agent can act on. Most developers assume MCP is a Claude-only feature or a vague "plugin layer," but it's a published protocol (MIT license, full spec on GitHub) that works with any agent that speaks JSON-RPC over stdio: Claude Code, Cursor, Codex, Zed, or your own custom agent.

What is the Model Context Protocol from Anthropic?

MCP is a client-server protocol where your AI agent is the client and an MCP server (a small program on your Mac) is the server. The agent sends a JSON-RPC request—tools/list to see available tools, tools/call with arguments to invoke one—and the server responds with the result: file contents, query rows, a base64 screenshot, an accessibility tree. The connection happens over stdio (standard in/out) or SSE (server-sent events over HTTP), always locally, never to Anthropic's API.

The official Model Context Protocol documentation lives at spec.modelcontextprotocol.io and the reference TypeScript SDK is on the model context protocol GitHub repo: github.com/modelcontextprotocol/typescript-sdk. Anthropic maintains the spec, but MCP itself is vendor-neutral—Ollama models, local LLMs, and non-Anthropic agents can implement it.

An MCP server exposes tools (functions the agent can call), resources (URIs the agent can read, like file:///path), and prompts (canned multi-shot examples). Most practical servers focus on tools: filesystem_read_file, screenshot_capture, database_query, browser_navigate.

How does the Model Context Protocol work with Claude Code on Mac?

Claude Code ships with built-in MCP support. When you add an MCP server, Claude Code spawns the server process (a Node.js or Python script), communicates over stdio, and lists its tools in the command palette. Mid-task, Claude can call tools/call with the tool name and arguments; the server runs the function and returns JSON.

Setup on macOS in three steps:

1. Install the MCP server. Example (filesystem server from the official SDK): npx -y @modelcontextprotocol/create-server filesystem ~/Documents.
2. Add the server to Claude Code's config. Open ~/Library/Application Support/Claude/claude_desktop_config.json and add:

   {
     "mcpServers": {
       "filesystem": {
         "command": "npx",
         "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/yourname/Documents"]
       }
     }
   }

1. Restart Claude Code. The server appears in the MCP menu (⌘K → MCP Servers). Claude can now call read_file, write_file, list_directory on ~/Documents.

The model context protocol llm flow: you ask Claude to "read config.json and fix the port number." Claude calls the MCP filesystem server's read_file tool with path config.json, gets the file content, edits it, calls write_file with the new content. You never paste the file into chat.

What MCP servers are available right now?

Anthropic publishes five official reference servers (filesystem, SQLite, PostgreSQL, Puppeteer browser, Git) at github.com/modelcontextprotocol/servers. The community has built dozens more: Slack, Linear, GitHub, Figma, Todoist, Google Drive. A curated list lives at best MCP servers.

The model context protocol Ollama story: Ollama itself doesn't implement MCP client support yet (as of Aug 2026), but you can run Ollama models behind an MCP-speaking wrapper (e.g., a Python script that accepts MCP requests and forwards prompts to Ollama's REST API). The protocol is LLM-agnostic.

How do I install an MCP server for Cursor or VS Code?

Cursor and VS Code with Continue or Codex follow the same pattern: add the server to a JSON config, restart the editor.

For Cursor (using the built-in MCP support introduced Dec 2025):

1. Open Settings → Features → Enable MCP (Beta).
2. Edit ~/.cursor/mcp.json:

   {
     "mcpServers": {
       "filesystem": {
         "command": "npx",
         "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/yourname/Projects"]
       }
     }
   }

1. Restart Cursor. The Composer can now call filesystem tools.

For VS Code + Continue extension:

1. Install Continue from the marketplace.
2. Open ~/.continue/config.json and add:

   {
     "experimental": {
       "modelContextProtocolServers": [
         {
           "transport": {
             "type": "stdio",
             "command": "npx",
             "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path"]
           }
         }
       ]
     }
   }

1. Reload the window. Continue's chat can invoke MCP tools.

See Cursor MCP setup for a full walkthrough and Claude Code vs Cursor for how each editor integrates MCP differently.

What does an MCP server actually return to the agent?

When the agent calls tools/call, the server returns a JSON object with content (an array of text or image blocks) and optional metadata. Example from a screenshot server:

{
  "content": [
    {
      "type": "image",
      "data": "iVBORw0KGgoAAAANS...",
      "mimeType": "image/png"
    },
    {
      "type": "text",
      "text": "Screenshot captured: 1920×1080, activeWindow=Xcode"
    }
  ]
}

The agent sees the image and the metadata. If the server also exposes an accessibility tree (like PinVari's MCP server), the JSON includes the UI element hierarchy:

{
  "content": [
    {
      "type": "text",
      "text": "AXButton \"Save\" at frame (850,600,80,30) inside AXWindow \"Document.swift\""
    }
  ]
}

Now the agent knows the exact button name and position. It can generate AppleScript to click it or file a bug referencing "the Save button in Document.swift window." This is the moat: MCP servers that return named, structured data (element roles, coordinates, confidence scores) beat servers that return pixel screenshots alone.

How do I write my own MCP server?

Use the official TypeScript SDK (@modelcontextprotocol/sdk) or the Python SDK (mcp). Here's a minimal TypeScript server that exposes one tool, reverse_string:

import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

const server = new Server({ name: 'reverse', version: '1.0.0' }, { capabilities: { tools: {} } });

server.setRequestHandler('tools/list', async () => ({
  tools: [{ name: 'reverse_string', description: 'Reverse a string', inputSchema: { type: 'object', properties: { text: { type: 'string' } }, required: ['text'] } }]
}));

server.setRequestHandler('tools/call', async (request) => {
  if (request.params.name === 'reverse_string') {
    const reversed = request.params.arguments.text.split('').reverse().join('');
    return { content: [{ type: 'text', text: reversed }] };
  }
});

const transport = new StdioServerTransport();
await server.connect(transport);

Save as server.ts, run tsx server.ts, and the agent can call reverse_string. For a real server, add filesystem/database/API calls in the tools/call handler.

The model context protocol documentation at spec.modelcontextprotocol.io covers resources (URI-addressable data), prompts (multi-shot examples), and sampling (agent requests completion from the server's LLM). Most practical servers start with tools.

What are the failure modes of MCP servers?

1. Server crashes mid-task. The agent sees a broken pipe and either retries or asks you to restart. Wrap server code in try-catch and log errors to a file.
2. Wrong directory/database path. The server starts but returns "file not found" or "table does not exist." Always test with absolute paths first.
3. Agent doesn't see the server. Restart the editor after editing the MCP config. Check that command is an executable in PATH (npx, python3, /path/to/script).
4. Tool returns unstructured text. The agent hallucinates next steps. Return structured JSON: { "status": "success", "rows": [...] } beats a multiline string dump.
5. AX tree is empty on some apps. Canvas-based UIs (games, some Electron windows) expose no accessibility tree. PinVari's server falls back to on-device Vision OCR; a pure-AX server returns nothing.

See best screenshot MCP servers for how different servers handle the AX-blind fallback and can Claude Code see my screen for the agent's perspective on what MCP screenshot tools actually deliver.

How is MCP different from OpenAI function calling or LangChain tools?

MCP's differentiator: it's a local-first protocol with no vendor lock-in. You can switch from Claude Code to Cursor to a custom agent without rewriting the server. OpenAI function calling requires sending the entire function schema to the API on every request; MCP servers describe themselves once via tools/list. LangChain tools are Python/TS abstractions, not a wire protocol—two agents using different frameworks can't share the same tool without a wrapper.

For teams using AI coding agents across multiple editors, MCP means writing one server (filesystem, screenshot, database) and connecting it to Claude Code, Cursor, and Codex with three config edits instead of three separate integrations.

What should I build an MCP server for?

Build an MCP server when:

• You have a local data source the agent needs repeatedly: SQLite database, log files, a monorepo the agent should search.
• You want the agent to control a local tool: browser automation (Puppeteer), screenshot capture, AX tree inspection, Docker commands.
• You're tired of pasting data into chat: API responses, CSV dumps, JSON configs.

PinVari's MCP server solves "the agent fixed the wrong button" by exposing pinvari_next_instruction (returns the circled element's AX path, the spoken instruction, a cropped screenshot, and a confidence score) and pinvari_mark_done (closes the capture). You hold ⌥⌘A, circle the real button, say "make this Save instead of Submit," and the agent gets the exact AXButton role and frame. Install PinVari, connect it to Claude Code with one click (PinVari → Connect → Claude Code), and the server is live at ~/.pinvari/mcp/pinvari-mcp. See Claude Code MCP setup for the full flow.

How do I debug an MCP server that won't connect?

1. Test the server standalone. Run the command directly in Terminal: npx -y @modelcontextprotocol/server-filesystem /path. It should block (waiting for stdin) and log nothing if healthy. Type {"jsonrpc":"2.0","id":1,"method":"initialize","params":{}} + Enter. You should see a JSON response with server info.
2. Check the config path. ~/Library/Application Support/Claude/claude_desktop_config.json for Claude Code, ~/.cursor/mcp.json for Cursor. Typo in the server key or args array? Fix it.
3. Restart the editor. MCP servers spawn on editor launch. Kill all processes and reopen.
4. Look for server logs. Add console.error('Server starting') to the server script. Logs appear in the editor's developer console (Help → Toggle Developer Tools in Claude Code).
5. Verify command is in PATH. which npx should return /usr/local/bin/npx or similar. If the command is a relative path, make it absolute.

For PinVari's MCP server specifically: the app must be running (the connector talks to it on 127.0.0.1:3402). If the app isn't open, the agent sees "connection refused."

FAQ

What is the Model Context Protocol from Anthropic?

Model Context Protocol (MCP) is Anthropic's open JSON-RPC standard for connecting AI agents to local tools (filesystem, database, screenshot) over stdio or SSE at 127.0.0.1. The agent calls a tool, the server does the work, the agent gets structured JSON—no uploads to an API. Full spec at spec.modelcontextprotocol.io.

Does MCP only work with Claude?

No. MCP is a vendor-neutral protocol. Claude Code, Cursor, Codex, and Zed all support it. Any agent that speaks JSON-RPC over stdio can connect to an MCP server. Anthropic maintains the spec, but you can use MCP with Ollama models, local LLMs, or custom agents.

How do I add an MCP server to Claude Code on Mac?

Edit ~/Library/Application Support/Claude/claude_desktop_config.json, add the server under "mcpServers" with "command" and "args" keys (e.g., "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path"]), and restart Claude Code. The server spawns on launch and appears in the MCP menu.

What's the difference between MCP tools and OpenAI function calling?

MCP tools run locally (127.0.0.1 stdio) with no API upload; OpenAI function calling sends the schema and call logs to openai.com. MCP is an open spec (MIT license) that works with any agent; OpenAI function calling is proprietary and requires the OpenAI API. MCP servers describe themselves once via tools/list; OpenAI functions require the schema on every request.

Can I use MCP with Ollama or local LLMs?

Ollama itself doesn't implement MCP client support yet (as of Aug 2026), but you can wrap an Ollama model in a Python script that accepts MCP requests and forwards prompts to Ollama's REST API. The protocol is LLM-agnostic—any agent that speaks JSON-RPC can call MCP servers. Community wrappers exist on GitHub.

Why does my MCP server return empty results?

Check: (1) the path argument is absolute and points to a real file/database, (2) the server has read permissions (try ls -l /path), (3) you restarted the editor after editing the config, (4) the server didn't crash (run it standalone in Terminal and paste a test JSON-RPC request). For screenshot/AX servers, some apps (canvas UIs, games) expose no accessibility tree—look for servers that fall back to OCR.