Getting Started¶

Quick Start Guide¶

Get up and running with MCP in minutes.

Prerequisites¶

Python 3.11+ or Node.js 18+
Git for version control
Text editor or IDE
Terminal/Command line access

Installation¶

Python¶

# Using uv (recommended)
uv add mcp

# Using pip
pip install mcp

Node.js¶

npm install @modelcontextprotocol/sdk

Your First MCP Server¶

Step 1: Create Server File¶

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

# Create server instance
server = Server("hello-server")

@server.list_tools()
async def list_tools():
    return [
        Tool(
            name="say_hello",
            description="Greet someone by name",
            inputSchema={
                "type": "object",
                "properties": {
                    "name": {"type": "string"}
                },
                "required": ["name"]
            }
        )
    ]

@server.call_tool()
async def call_tool(name: str, arguments: dict):
    if name == "say_hello":
        name_arg = arguments.get("name", "World")
        return [TextContent(type="text", text=f"Hello, {name_arg}!")]
    
    raise ValueError(f"Unknown tool: {name}")

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

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

Step 2: Run the Server¶

# STDIO mode (for development and testing)
python hello_mcp.py

Step 3: Test Your Server¶

You can test your MCP server using:

MCP Inspector (development tool):

npx @modelcontextprotocol/inspector python hello_mcp.py

Claude Desktop: Add to your configuration file
Manual JSON-RPC testing: The server communicates via stdio using JSON-RPC messages

Next Steps¶

Essential Reading¶

📋 Standards - Protocol specifications
🏗️ Architecture - System design
💻 Development Guide - Language-specific guides

Hands-On Tutorials¶

Sample Projects¶

Common Patterns¶

Tool Registration¶

@mcp.tool()
def my_tool(param: str) -> str:
    """Tool description"""
    return result

Resource Exposure¶

@mcp.resource("config://settings")
def get_settings() -> str:
    return json.dumps(config)

Error Handling¶

@mcp.tool()
def safe_operation(data: str) -> str:
    try:
        return process(data)
    except Exception as e:
        raise McpError(f"Operation failed: {e}")

Troubleshooting¶

Common Issues¶

Port Already in Use

# Find process using port
lsof -i :8000
# Kill process or use different port

Module Not Found

# Ensure MCP is installed
pip list | grep mcp
# Reinstall if needed
pip install --upgrade "mcp[cli]"

Connection Refused - Check server is running - Verify correct port - Check firewall settings