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

Claude → Custom integration → Your database
GPT-5  → Different custom integration → Your database
Gemini → Yet another integration → Your database

Claude ─┐
GPT-5  ─┼── MCP Protocol ── MCP Server ── Your database
Gemini ─┘

┌─────────────────────────────────────────────────┐
│                  AI Application                   │
│  (Claude Desktop, Cursor, Custom App)             │
│                                                   │
│  ┌─────────────┐                                  │
│  │  MCP Client  │                                  │
│  └──────┬───────┘                                  │
└─────────┼──────────────────────────────────────────┘
          │ MCP Protocol (JSON-RPC over stdio/HTTP)
          │
┌─────────┼──────────────────────────────────────────┐
│  ┌──────┴───────┐                                   │
│  │  MCP Server   │                                   │
│  │               │                                   │
│  │  ┌─────────┐  │                                   │
│  │  │  Tools   │  │  → search_docs(), create_ticket()│
│  │  ├─────────┤  │                                   │
│  │  │Resources │  │  → files, database records        │
│  │  ├─────────┤  │                                   │
│  │  │ Prompts  │  │  → templates, workflows           │
│  │  └─────────┘  │                                   │
│  └───────────────┘                                   │
│                                                      │
│  External Services: Database, API, File System       │
└──────────────────────────────────────────────────────┘

# server.py
from mcp.server import Server
from mcp.server.stdio import stdio_server
from mcp.types import Tool, TextContent

app = Server("my-tools")

@app.list_tools()
async def list_tools():
    return [
        Tool(
            name="search_docs",
            description="Search documentation by keyword",
            inputSchema={
                "type": "object",
                "properties": {
                    "query": {
                        "type": "string",
                        "description": "Search query"
                    },
                    "limit": {
                        "type": "integer",
                        "description": "Max results",
                        "default": 5
                    }
                },
                "required": ["query"]
            }
        ),
        Tool(
            name="get_user",
            description="Get user information by ID",
            inputSchema={
                "type": "object",
                "properties": {
                    "user_id": {
                        "type": "string",
                        "description": "User ID"
                    }
                },
                "required": ["user_id"]
            }
        )
    ]

@app.call_tool()
async def call_tool(name: str, arguments: dict):
    if name == "search_docs":
        # Your search logic here
        results = search_documentation(arguments["query"], arguments.get("limit", 5))
        return [TextContent(type="text", text=str(results))]

    elif name == "get_user":
        user = get_user_by_id(arguments["user_id"])
        return [TextContent(type="text", text=str(user))]

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

def search_documentation(query, limit):
    # Replace with your actual search logic
    return [{"title": f"Doc about {query}", "url": f"https://docs.example.com/{query}"}]

def get_user_by_id(user_id):
    # Replace with your actual database query
    return {"id": user_id, "name": "John Doe", "email": "[email]"}

async def main():
    async with stdio_server() as (read_stream, write_stream):
        await app.run(read_stream, write_stream)

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

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

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

server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [
    {
      name: "search_docs",
      description: "Search documentation by keyword",
      inputSchema: {
        type: "object",
        properties: {
          query: { type: "string", description: "Search query" },
          limit: { type: "number", description: "Max results", default: 5 }
        },
        required: ["query"]
      }
    },
    {
      name: "create_ticket",
      description: "Create a support ticket",
      inputSchema: {
        type: "object",
        properties: {
          title: { type: "string" },
          description: { type: "string" },
          priority: { type: "string", enum: ["low", "medium", "high"] }
        },
        required: ["title", "description"]
      }
    }
  ]
}));

server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;

  switch (name) {
    case "search_docs": {
      const results = await searchDocs(args.query, args.limit || 5);
      return { content: [{ type: "text", text: JSON.stringify(results) }] };
    }
    case "create_ticket": {
      const ticket = await createTicket(args.title, args.description, args.priority);
      return { content: [{ type: "text", text: `Ticket created: ${ticket.id}` }] };
    }
    default:
      throw new Error(`Unknown tool: ${name}`);
  }
});

async function searchDocs(query: string, limit: number) {
  // Your search implementation
  return [{ title: `Result for ${query}`, score: 0.95 }];
}

async function createTicket(title: string, description: string, priority?: string) {
  // Your ticket creation logic
  return { id: "TICKET-123", title, status: "open" };
}

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

# Python
pip install mcp

# Node.js
npm install @modelcontextprotocol/sdk

{
  "mcpServers": {
    "my-tools": {
      "command": "python",
      "args": ["server.py"],
      "cwd": "/path/to/your/server"
    }
  }
}

{
  "mcp": {
    "servers": {
      "my-tools": {
        "command": "node",
        "args": ["server.js"]
      }
    }
  }
}

from mcp.client import ClientSession
from mcp.client.stdio import stdio_client

async def main():
    async with stdio_client(["python", "server.py"]) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()

            # List available tools
            tools = await session.list_tools()
            print("Available tools:", [t.name for t in tools.tools])

            # Call a tool
            result = await session.call_tool("search_docs", {"query": "authentication"})
            print("Results:", result.content[0].text)

@app.call_tool()
async def call_tool(name: str, arguments: dict):
    try:
        result = await execute_tool(name, arguments)
        return [TextContent(type="text", text=str(result))]
    except ValidationError as e:
        return [TextContent(type="text", text=f"Invalid input: {e.message}")]
    except NotFoundError as e:
        return [TextContent(type="text", text=f"Not found: {e.message}")]
    except Exception as e:
        return [TextContent(type="text", text=f"Error: {str(e)}")]

from mcp.server.sse import SseServerTransport
from starlette.applications import Starlette
from starlette.routing import Route

transport = SseServerTransport("/messages")

async def handle_sse(request):
    async with transport.connect_sse(request.scope, request.receive, request._send) as streams:
        await app.run(streams[0], streams[1])

starlette_app = Starlette(routes=[
    Route("/sse", endpoint=handle_sse),
    Route("/messages", endpoint=transport.handle_post_message, methods=["POST"])
])

from openai import OpenAI

# Your AI application uses Crazyrouter for model access
client = OpenAI(
    api_key="your-crazyrouter-key",
    base_url="https://api.crazyrouter.com/v1"
)

# MCP tools are passed as function definitions
response = client.chat.completions.create(
    model="claude-sonnet-4-5",  # or gpt-5, gemini-3-pro
    messages=[{"role": "user", "content": "Search our docs for authentication guides"}],
    tools=mcp_tools_as_openai_format,  # Converted from MCP tool definitions
    tool_choice="auto"
)