MCP Guide

Understand MCP so you can decide if you need one — and build one if you do.

This is an educational skill. It doesn't install anything. It teaches agents and humans what MCP (Model Context Protocol) is, when it's the right tool, and when simpler alternatives (CLIs + skills) are better.

Triggers

• "what is MCP"
• "should I build an MCP server"
• "MCP vs CLI"
• "how do MCPs work"
• "build an MCP"
• "connect [service] to my agent"
• When an agent is trying to figure out how to integrate an external service

What Is MCP?

MCP (Model Context Protocol) is an open standard that lets AI agents talk to external services through a structured interface. Think of it as a universal adapter between your AI agent and the tools it uses.

The Restaurant Metaphor

Without MCP, every integration is custom. With MCP, there's a standard way for agents to discover tools, understand their inputs/outputs, and call them.

How It Works

Your Agent (Claude Code, etc.)
    ↕ MCP Protocol (JSON-RPC)
MCP Server (runs locally or remotely)
    ↕ API calls
External Service (Gmail, Slack, Square, etc.)

An MCP server:

1. Advertises tools — "I can send emails, read inbox, create filters"
2. Describes each tool — "send_email takes: to, subject, body. Returns: message_id"
3. Executes tool calls — Agent says "call send_email with these params" → server makes the API call → returns the result
4. Handles auth — Server manages API keys, OAuth tokens, etc.

The agent never touches the raw API. It just calls structured tools.

When Do You Need an MCP?

You probably DON'T need an MCP if:

This repo's approach: We use CLIs + skills wherever possible. gws for Google Workspace, stripe for payments, gcloud for GCP. The skill provides the domain knowledge; the CLI provides the tool. No MCP needed.

You probably DO need an MCP if:

The Decision Flowchart

Does a good CLI already exist for this service?
├── Yes → Use CLI + skill. Done.
└── No
    ├── Is it a simple REST API with < 10 endpoints?
    │   ├── Yes → Write curl patterns in a skill. Done.
    │   └── No
    │       ├── Do multiple agents/users need this?
    │       │   ├── Yes → Build an MCP server.
    │       │   └── No
    │       │       ├── Do you need real-time data (webhooks/streaming)?
    │       │       │   ├── Yes → Build an MCP server.
    │       │       │   └── No → Write a script + skill. Probably enough.
    │       │       └──
    │       └──
    └──

MCP Architecture (for the curious)

Components

Transport Options

For most SMBs, stdio is fine — the MCP server runs on the same machine as your agent.

Tool Anatomy

Every MCP tool has:

{
  "name": "slack_send_message",
  "description": "Send a message to a Slack channel or DM",
  "inputSchema": {
    "type": "object",
    "properties": {
      "channel": {"type": "string", "description": "Channel ID or user ID"},
      "text": {"type": "string", "description": "Message text (supports Slack markdown)"}
    },
    "required": ["channel", "text"]
  },
  "annotations": {
    "readOnlyHint": false,
    "destructiveHint": false
  }
}

The agent sees this schema, knows what inputs are needed, and can call the tool without knowing anything about the Slack API underneath.

Building Your Own MCP Server

If you've decided you need one, here's the path:

Recommended Stack

The Build Process

1. Research the API — Understand endpoints, auth, data models
2. Plan your tools — List operations to expose, prioritize by usage
3. Set up the project — Scaffold with the MCP SDK
4. Implement tools — One at a time, with proper error handling
5. Test — Use MCP Inspector to verify tools work
6. Create evals — Write test questions to verify LLMs can use your tools effectively

Official Build Guide

Anthropic maintains a comprehensive MCP builder skill with templates, best practices, and language-specific guides:

Anthropic MCP Builder Skill

This includes:

• Step-by-step implementation guides for TypeScript and Python
• MCP best practices (naming, pagination, error handling, response formats)
• Evaluation creation guide (test that LLMs can actually use your server)
• Project structure templates
• Quality checklists

To use it with Claude Code:

# Add the official MCP builder skill
npx skills add anthropics/skills@mcp-builder -g -y

Or just tell your agent: "I want to build an MCP server for [service]. Use the mcp-builder skill."

Naming Conventions

Tool Naming

• Use snake_case with service prefix: slack_send_message, github_create_issue
• Be action-oriented: start with verbs (get, list, search, create, update, delete)
• Be specific: slack_send_message not send_message (avoids conflicts with other MCPs)

Key Best Practices

1. Tool descriptions must be precise. The agent reads these to decide which tool to use. Vague descriptions = wrong tool choices.
2. Return structured data. JSON for programmatic use, Markdown for human readability. Support both when possible.
3. Pagination is mandatory for any tool that lists things. Default to 20-50 items. Return has_more and next_offset.
4. Error messages must be actionable. Not "Error 403" but "Permission denied — the bot token needs the chat:write scope. Add it at api.slack.com/apps → OAuth & Permissions."
5. Annotate your tools. Mark read-only vs destructive. This helps agents (and humans) understand the risk of each operation.
6. Don't over-build. Start with the 5-10 most common operations. Add more based on actual usage, not speculation.

Finding Existing MCP Servers

Before building your own, check if one already exists:

• MCP Server Registry — Official directory of community MCP servers
• Smithery — MCP server marketplace
• npm — Search for mcp-server-{service} or {service}-mcp
• PyPI — Search for {service}-mcp or {service}_mcp

Common existing servers: GitHub, Slack, Google Drive, Postgres, SQLite, Brave Search, Puppeteer, and many more.

MCP vs Other Integration Patterns

This repo's philosophy: Start simple (CLI + skill), upgrade to MCP only when you hit a wall. Most SMB needs are well-served by CLIs and skills.

Related Skills

• google-workspace — Example of CLI + skill pattern (uses gws CLI, no MCP needed)
• secrets-manager — Secure credential storage (needed by MCP servers too)
• slack — Example of API + skill pattern (curl calls, no MCP needed)

External Resources

• MCP Specification — The official protocol spec
• Anthropic MCP Builder — Official skill for building MCP servers
• MCP Server Registry — Directory of existing servers
• TypeScript SDK — Official TypeScript implementation
• Python SDK — Official Python implementation

Understand the tool before you reach for it. Sometimes a screwdriver is better than a power drill.