Build an MCP Server from Scratch:
Hands-On AI Tool Calling

Introduction: Why AI Needs MCP

Even the strongest models have training cutoffs. They cannot magically know your CRM customers, last night's logs, or the live state of an internal API. The industry path is clear: Function Calling → Plugins → MCP. The first two are mostly vendor-specific formats—switch models and you rewrite the integration layer. MCP standardizes how AI discovers and invokes tools, so you write once and reuse across Clients.

1. 01

   Pain point: You want Claude or GPT to query databases, call APIs, and manipulate files—but every vendor speaks a different format.

2. 02

   Scenario: In Cursor, have AI read your Markdown notes; in Claude Desktop, pull GitHub Issues on demand.

3. 03

   Promise: This guide takes you from an empty directory to a deployable Server, with complete code and a troubleshooting table.

Development Environment Setup

3.1 Choose a Language

Python (official mcp SDK with FastMCP decorators) is the best starting point for newcomers. TypeScript (@modelcontextprotocol/sdk) suits frontend and full-stack teams. This guide uses Python as the primary example, with TypeScript noted where relevant.

# Python
python -m venv .venv && source .venv/bin/activate
pip install mcp httpx pydantic

# TypeScript (reference)
npm init -y && npm install @modelcontextprotocol/sdk

3.2 Project Structure

my-mcp-server/
├── server.py            # Main entry point
├── tools/               # calculator.py, web_search.py
├── resources/           # file_reader.py
├── prompts/             # templates.py
├── tests/test_tools.py
├── pyproject.toml
└── README.md

3.3 Debugging Tools

1. 1

   MCP Inspector: npx @modelcontextprotocol/inspector python server.py

2. 2

   Claude Desktop: Edit claude_desktop_config.json to register your Server.

3. 3

   Cursor: Settings → MCP → add command + args.

Tools: Building Functions the AI Can Call

5.1 Basic Structure

Your function signature is the documentation: parameter types, return types, and docstrings are exposed to the model for tool selection. Use snake_case with verb prefixes (search_web, read_file). Return structured JSON on errors instead of raw exceptions so the model can self-correct.

5.2 Complex Parameters (Pydantic)

from pydantic import BaseModel, Field

class SearchInput(BaseModel):
    query: str = Field(description="Search keywords")
    max_results: int = Field(default=5, description="Maximum results to return")
    language: str = Field(default="en", description="Result language")

@mcp.tool()
def web_search(input: SearchInput) -> list[dict]:
    """Run a web search and return matching results"""
    ...

5.3 Five Practical Tools to Build

5.4 Async Tools

@mcp.tool()
async def fetch_url(url: str) -> str:
    """Fetch content from a URL"""
    async with httpx.AsyncClient(timeout=30.0) as client:
        response = await client.get(url)
        return response.text

5.5 Error Handling Best Practices

• !

  Set timeouts on network and I/O operations (15–30s recommended).

• !

  Apply permission checks on sensitive operations (API keys, allowed paths).

• !

  Return {"error": "...", "hint": "..."} so the model can retry intelligently.

Prompts: Reusable Prompt Templates

MCP Prompts are predefined prompt fragments with dynamic parameter injection, improving team consistency and maintainability.

from mcp.types import PromptMessage, TextContent

@mcp.prompt()
def code_review_prompt(language: str, code: str) -> list[PromptMessage]:
    """Code review prompt template"""
    return [PromptMessage(
        role="user",
        content=TextContent(type="text", text=f"""Review the following {language} code:
1. Quality and readability  2. Bugs and security  3. Performance

```{language}
{code}
```""")
    )]

You can define multi-turn templates with user + assistant roles for interview simulations, debugging assistants, and more. Clients call prompts/get to retrieve the filled message chain.

Debugging and Testing

9.1 MCP Inspector

Inspector provides a GUI to test tools/list, tools/call, inspect JSON-RPC logs, and simulate error scenarios.

9.2 Unit Tests (pytest + ClientSession)

@pytest.mark.asyncio
async def test_calculator_tool():
    server_params = StdioServerParameters(command="python", args=["server.py"])
    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            result = await session.call_tool("calculate", {"expression": "2 + 2"})
            assert result.content[0].text == "4"

9.3 Common Errors

Project: Personal Knowledge Base MCP Server

Goal: Let AI search local Markdown notes, run semantic retrieval, and create or update notes. In Cursor, ask: "What did I write about MCP last week?"

Tech Stack

Core Tools

1. 1

   index_notes: Scan a directory and build a vector index.

2. 2

   semantic_search: Return relevant snippets by meaning.

3. 3

   write_note: Create or append Markdown files.

4. 4

   Resource: notes://{path} to read a single note directly.

The AI calls semantic_search, synthesizes answers from retrieved snippets, and saves tokens compared to stuffing your entire note library into context.

FAQ

Closing

MCP is the standard protocol for AI tool integration—mastering the full path from Hello World to production deployment is a core skill for AI engineers in 2026. What tool will you build first? Share your Server design after you ship it.

Hidden cost rarely lives in writing code—it lives in the runtime environment. Windows-primary workflows plus a cloud Mac running Cursor MCP mean TCC dialogs, Python virtualenvs, and Inspector logs must be cross-checked in a graphical session on the same machine. Buying a Mac mini adds sleep, OS updates, and depreciation; 8 GB RAM chokes under vector indexing plus concurrent Servers.

To validate your MCP toolchain hourly with on-machine GUI checks for TCC and Inspector, rent a remote Mac through VNCMac: use the primary button below for the pricing page, or browse plans on the homepage first.