MCP Implementation Playbooks: The Setup Guide.

Playbook 1: Local MCP on Claude Desktop

This is the right starting point if you've never run an MCP server and want to confirm the whole thing works before writing code.

Step 1 — Find your config file

Claude Desktop only reads MCP configuration from one file, which is read once on application launch. Locations depend on your OS:

Step 2 — Add a server block

Expose your local filesystem to Claude by adding a server block to the JSON config file. Here is a minimal entry:

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

Step 3 — Fully quit and relaunch

Minimize is not enough. You must fully quit the app. On Windows, check the system tray because Claude Desktop keeps running in the background. On macOS, use Cmd+Q.

Step 4 — Verify with a direct ask

Don't ask "is MCP working." Ask Claude to list the specific tools the server exposes, e.g., "What filesystem tools do you have access to right now?" If the tools don't show up, check for JSON formatting errors.

Playbook 2: MCP for Coding Agents

If your actual goal is to let your CLI agent query databases or index local docs while it works, you want MCP wired into your terminal environment.

The mechanics are identical to Playbook 1 (same mcpServers JSON block), but the configuration is local to the project repo rather than global. A project-level agent config should only expose the tools needed for that repository. Giving standing access to your entire filesystem in a coding agent is a major security risk.

Playbook 3: Remote, Hosted MCP Servers

Use this playbook when you want your entire team using a shared SaaS server (Slack, Notion, Jira) without each developer managing individual API keys.

Remote MCP servers run over HTTP rather than stdio process pipes. Authentication relies on OAuth 2.1 — developers authenticate through a browser login, and the host platform holds a scoped token. This allows you to revoke access for one user without rotating shared keys, and scope permissions to match the user's role.

Playbook 4: Building Your Own Server

Build a custom server only when you've verified that nothing in the community registry (which has passed 200+ implementations) covers your proprietary data source.

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/shared/protocol.js";

const server = new Server(
  { name: "my-internal-server", version: "1.0.0" },
  { capabilities: { tools: {} } }
);

server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [{
    name: "get_account_status",
    description: "Look up account status by customer ID",
    inputSchema: {
      type: "object",
      properties: { customerId: { type: "string" } },
      required: ["customerId"]
    }
  }]
}));

// Run transport loop...

Three Rules for Production-Ready Servers

1. Validate every input server-side: Never assume LLMs send well-formed arguments. Schema validation (Zod in TypeScript, Pydantic in Python) is mandatory to catch hallucinated parameters.
2. Return structured errors, not exceptions: A thrown exception gives the model nothing to reason about. Returning a typed error block (like { error: "RATE_LIMIT_EXCEEDED", retryAfter: 60 }) lets it retry or inform the user.
3. One server, one clear purpose: Avoid creating a single mega-server. Smaller, single-purpose servers are easier to audit and keep within the context window limits.

Failure Modes & Security Checklist

The Failure Modes Nobody Mentions

Keep these in mind when configuring your environment:

• Config edited, app not restarted: The single most common support ticket. Claude reads the file once on boot.
• Invalid JSON, silently: A trailing comma or unescaped path separator (\) on Windows will cause Claude to fail loading all configured servers. Run your file through a JSON validator.
• Credentials in the wrong place: Keep API keys out of config JSONs or schemas. The model can leak these in outputs. Use environment variables.
• The rug pull: Compromised third-party servers can alter their tool schemas dynamically after you approve them. Treat schemas as untrusted inputs.
• Over-broad scope: Connecting a server with write access when you only need to read one table is a major security vulnerability. Scope down at connection time.

Security Checklist

Verify these answers before connecting any third-party server:

• 🔐 Is authentication handled via OAuth or scoped tokens (not raw API keys)?
• 🔍 Does the server documentation clearly outline what resources are exposed?
• 🛡️ Is the server source verified (official vendor or ref repository)?
• 📦 If local, is the server running in a restricted sandbox or local user context?
• 📝 Are invocations logged with timestamps and arguments for audits?