Model Context Protocol (MCP) Complete Guide: The New Standard for AI-World Integration

Number of models × Number of tools = Integration code written

Claude + (Slack + GitHub + DB + Notion) = 4 Claude integrations
GPT-4 + (Slack + GitHub + DB + Notion) = 4 GPT-4 integrations
Gemini + (Slack + GitHub + DB + Notion) = 4 Gemini integrations

Total: 12 separate integration codebases

Number of tools = Number of MCP servers (reusable across models)

1 Slack MCP server → works with Claude, GPT-4, Gemini, and any future model
1 GitHub MCP server → same story

┌─────────────────────┐         ┌──────────────────────┐
│     MCP Client      │◄───────►│     MCP Server       │
│  (Claude Desktop,   │  JSON   │  (your tools, DBs,   │
│   Cursor, your app) │  RPC    │   APIs, files, etc.) │
└─────────────────────┘         └──────────────────────┘

An MCP Server exposes three primitives:

├── Resources (read-only data)
│   └── files, DB query results, API responses
│
├── Tools (executable actions)
│   └── write file, call API, modify DB
│
└── Prompts (reusable prompt templates)
    └── structured templates like "review this code"

from mcp.server import Server
from mcp.server.models import InitializationOptions
import mcp.types as types
import json
import asyncio

app = Server("my-database-server")

# Register Resources: expose read-only data
@app.list_resources()
async def list_resources() -> list[types.Resource]:
    return [
        types.Resource(
            uri="db://customers",
            name="Customer Database",
            description="Access customer records. Returns up to 100 records.",
            mimeType="application/json"
        ),
        types.Resource(
            uri="db://orders",
            name="Order History",
            description="Access order history for all customers",
            mimeType="application/json"
        )
    ]

@app.read_resource()
async def read_resource(uri: str) -> str:
    if uri == "db://customers":
        customers = await db.fetch_all(
            "SELECT id, name, email, created_at FROM customers LIMIT 100"
        )
        return json.dumps([dict(c) for c in customers])

    elif uri == "db://orders":
        orders = await db.fetch_all(
            "SELECT id, customer_id, total, status, created_at FROM orders LIMIT 100"
        )
        return json.dumps([dict(o) for o in orders])

    raise ValueError(f"Unknown resource: {uri}")

# Register Tools: expose executable actions
@app.list_tools()
async def list_tools() -> list[types.Tool]:
    return [
        types.Tool(
            name="create_customer",
            description=(
                "Create a new customer record in the database. "
                "Use this when a user wants to add a new customer. "
                "Returns the new customer's ID on success."
            ),
            inputSchema={
                "type": "object",
                "properties": {
                    "name": {
                        "type": "string",
                        "description": "Customer's full name"
                    },
                    "email": {
                        "type": "string",
                        "description": "Customer's email address"
                    },
                    "phone": {
                        "type": "string",
                        "description": "Customer's phone number (optional)"
                    }
                },
                "required": ["name", "email"]
            }
        ),
        types.Tool(
            name="search_customers",
            description=(
                "Search customers by name or email. "
                "Use this to look up existing customers before creating new ones."
            ),
            inputSchema={
                "type": "object",
                "properties": {
                    "query": {
                        "type": "string",
                        "description": "Search query — matches against name and email fields"
                    }
                },
                "required": ["query"]
            }
        )
    ]

@app.call_tool()
async def call_tool(name: str, arguments: dict) -> list[types.TextContent]:
    if name == "create_customer":
        try:
            result = await db.execute(
                "INSERT INTO customers (name, email, phone) VALUES (:name, :email, :phone)",
                {
                    "name": arguments["name"],
                    "email": arguments["email"],
                    "phone": arguments.get("phone", None)
                }
            )
            return [types.TextContent(
                type="text",
                text=f"Customer created successfully. ID: {result.lastrowid}"
            )]
        except Exception as e:
            return [types.TextContent(
                type="text",
                text=f"Error creating customer: {str(e)}"
            )]

    elif name == "search_customers":
        query = f"%{arguments['query']}%"
        customers = await db.fetch_all(
            "SELECT id, name, email FROM customers WHERE name LIKE :q OR email LIKE :q",
            {"q": query}
        )
        if not customers:
            return [types.TextContent(type="text", text="No customers found matching that query")]

        result = "\n".join([
            f"ID: {c.id}, Name: {c.name}, Email: {c.email}"
            for c in customers
        ])
        return [types.TextContent(type="text", text=result)]

    raise ValueError(f"Unknown tool: {name}")

# Run the server
async def main():
    from mcp.server.stdio import stdio_server
    async with stdio_server() as (read_stream, write_stream):
        await app.run(
            read_stream,
            write_stream,
            InitializationOptions(
                server_name="my-database-server",
                server_version="0.1.0"
            )
        )

if __name__ == "__main__":
    asyncio.run(main())

// macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
// Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "my-database": {
      "command": "python",
      "args": ["/path/to/your/mcp_server.py"],
      "env": {
        "DATABASE_URL": "postgresql://user:pass@localhost/mydb"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/username/projects"]
    }
  }
}

# Tied to OpenAI's API format
tools = [{"type": "function", "function": {"name": "search", ...}}]
response = openai.chat.completions.create(tools=tools, ...)

# Tied to the LangChain framework
from langchain.tools import tool

@tool
def search(query: str) -> str:
    """Search the web"""
    return web_search(query)

# Works with any MCP-compatible client
@app.list_tools()
async def list_tools():
    return [types.Tool(name="search", ...)]

# Node.js servers
npx -y @modelcontextprotocol/server-github

# Python servers
pip install mcp

# Bad
types.Tool(name="query_db", description="Query database")

# Good
types.Tool(
    name="search_customers",
    description=(
        "Search customer records by name or email. "
        "Use this when you need to find an existing customer. "
        "Returns customer ID, name, email, and account creation date. "
        "Use get_orders for order-related queries."
    )
)

@app.call_tool()
async def call_tool(name: str, arguments: dict):
    try:
        result = await execute_operation(arguments)
        return [types.TextContent(type="text", text=json.dumps(result))]
    except Exception as e:
        # Return error as a normal response — the AI can adapt
        return [types.TextContent(
            type="text",
            text=f"Error: {str(e)}. Please check the input and try again."
        )]