MCP Server с нуля:
полное руководство для разработчиков

LLM сильны в рассуждениях, но слабы в исполнении. Первым исправлением стал OpenAI Function Calling (июнь 2023): задаёте JSON-схемы, модель эмитит структурированные вызовы, ваш код их выполняет. Работало — но только внутри API OpenAI. Каждой другой модели нужен отдельный адаптер.

ChatGPT Plugins (март 2023) попробовали модель маркетплейса: каждый plugin — bespoke REST-обёртка со своим manifest. Discovery централизован в store OpenAI, а не в runtime агента. Когда Anthropic выпустил Tool Use, а LangChain популяризировал agent frameworks, в индустрии оказалось три несовместимых tool schema и ни одного переносимого server layer.

Design rationale Anthropic похож на USB-C: стандартизировать порт, а не каждый кабель. MCP не заменяет REST API — он оборачивает их в uniform discovery и invocation layer, чтобы AI-клиенты перестали заботиться о вендоре или фреймворке на другой стороне. К Q2 2026 governance перешла в Linux Foundation AAIF; OpenAI, Google и Microsoft ship native MCP client support.

MCP работает на JSON-RPC 2.0 с bidirectional messaging. Host (Cursor, Claude Desktop) встраивает один или несколько MCP Clients. Каждый Client поддерживает 1:1 session с MCP Server, который мостит к реальным системам.

Servers expose три типа capability: Tools (исполняемые действия с side effects), Resources (read-only данные с URI-идентификаторами) и Prompts (переиспользуемые template strings, которые client может pre-fill). Core RPC methods: tools/list, tools/call, resources/list, resources/read, prompts/list и prompts/get.

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "query_database",
    "arguments": { "sql": "SELECT id, email FROM users LIMIT 10" }
  },
  "id": 42
}

STDIO transport: Host spawn Server как subprocess; сообщения идут через stdin/stdout. Нулевые сетевые зависимости, сильная process isolation, идеально для local dev. Lifecycle: spawn → initialize handshake → capability negotiation → persistent session → subprocess exit при disconnect.

HTTP + SSE / streamable-http: Server работает как long-lived HTTP service. Client открывает SSE stream для server-push events; tool calls идут через POST. Позволяет remote deploy, team-shared servers, horizontal scaling — но требует session affinity для SSE и proper auth на edge. Спека 2026 добавляет streamable-http как рекомендуемый remote transport, заменяя legacy SSE-only patterns.

Выберите SDK stack: Python с mcp + FastMCP для fastest iteration или TypeScript с @modelcontextprotocol/sdk для Node-native HTTP servers. Рекомендуемая структура проекта:

my-mcp-server/
  pyproject.toml
  src/
    server.py          # FastMCP entry
    tools/             # tool modules
    resources/         # resource handlers
    prompts/           # prompt templates
  tests/
    test_tools.py
  Dockerfile

Установка: pip install mcp или npm install @modelcontextprotocol/sdk. Отладка через MCP Inspector (npx @modelcontextprotocol/inspector) — подключается к STDIO или HTTP endpoints и показывает live tools/list. Подключение в Cursor: Settings → MCP → add server config; Claude Desktop — через claude_desktop_config.json.

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("hello-mcp")

@mcp.tool()
def greet(name: str) -> str:
    return f"Hello, {name}!"

if __name__ == "__main__":
    mcp.run()

Tools с Pydantic input: FastMCP derives JSON Schema из type hints и Pydantic models автоматически. Ниже — пять практичных tools: calculator, file I/O, HTTP fetch, DB query и time с async support и structured error returns.

import asyncio
import httpx
from datetime import datetime, timezone
from pathlib import Path
from pydantic import BaseModel, Field
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("utility-server")

class CalcInput(BaseModel):
    expression: str = Field(description="Math expression e.g. 2 + 3 * 4")

@mcp.tool()
def calculate(input: CalcInput) -> str:
    try:
        allowed = set("0123456789+-*/(). ")
        if not all(c in allowed for c in input.expression):
            return "Error: invalid characters in expression"
        return str(eval(input.expression, {"__builtins__": {}}, {}))
    except Exception as e:
        return f"Error: {e}"

@mcp.tool()
def read_file(path: str) -> str:
    try:
        target = Path(path).resolve()
        if not target.is_file():
            return f"Error: {path} is not a file"
        return target.read_text(encoding="utf-8", errors="replace")[:50000]
    except Exception as e:
        return f"Error: {e}"

@mcp.tool()
async def http_get(url: str) -> str:
    try:
        async with httpx.AsyncClient(timeout=15.0) as client:
            resp = await client.get(url)
            return resp.text[:10000]
    except Exception as e:
        return f"Error: {e}"

@mcp.tool()
async def db_query(sql: str) -> str:
  try:
    import aiosqlite
    async with aiosqlite.connect("app.db") as db:
      cursor = await db.execute(sql)
      rows = await cursor.fetchall()
      return str(rows[:100])
  except Exception as e:
    return f"Error: {e}"

@mcp.tool()
def current_time(tz: str = "UTC") -> str:
    return datetime.now(timezone.utc).isoformat()

Resources: статические URI map к fixed files; dynamic URI принимают parameters. Filesystem resource server expose project docs, которые agent читает без tool side effects.

from mcp.server.fastmcp import FastMCP
from pathlib import Path

mcp = FastMCP("fs-resources")
DOCS = Path("./docs")

@mcp.resource("docs://index")
def docs_index() -> str:
    files = [f.name for f in DOCS.glob("*.md")]
    return "\n".join(files)

@mcp.resource("docs://{filename}")
def read_doc(filename: str) -> str:
    path = DOCS / filename
    if not path.exists():
        return f"Error: {filename} not found"
    return path.read_text(encoding="utf-8")

Prompts: переиспользуемые templates с argument slots. Code-review prompt pre-fills context, чтобы agent следовал checklist review вашей команды.

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("review-prompts")

@mcp.prompt()
def code_review(file_path: str, language: str) -> str:
    return f"""Review {file_path} ({language}) for:
1. Security vulnerabilities (injection, auth bypass)
2. Performance bottlenecks
3. Error handling gaps
4. Test coverage holes
Provide severity-rated findings with fix suggestions."""

Streamable HTTP transport — default 2026 для remote MCP Servers. Запуск FastMCP: mcp.run(transport="streamable-http") или TypeScript SDK StreamableHTTPServerTransport. Security на edge:

Workflow отладки: сначала MCP Inspector, затем client logs, затем unit tests. Inspector показывает raw JSON-RPC, schema validation errors и timing per call.

import pytest
from server import calculate, CalcInput

def test_calculate_valid():
    result = calculate(CalcInput(expression="2 + 3"))
    assert result == "5"

def test_calculate_invalid_chars():
    result = calculate(CalcInput(expression="import os"))
    assert result.startswith("Error:")

Шестишаговый runbook от assessment до production-ready MCP Server:

Production paths: package через Docker (python:3.12-slim base, non-root user, health check на HTTP port). Варианты платформ:

Monitoring: export request latency и tool-call counters в Prometheus; exceptions в Sentry с MCP method name tags. Pin SDK versions в pyproject.toml / package.json и tag Docker images per release — MCP spec revisions 2026 всё ещё ship breaking transport changes.

Capstone: personal knowledge base MCP. Combine ChromaDB vector store, embedding model (local Ollama или API) и semantic search tool:

import chromadb
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("knowledge-base")
client = chromadb.PersistentClient(path="./chroma_data")
collection = client.get_or_create_collection("notes")

@mcp.tool()
def semantic_search(query: str, n: int = 5) -> str:
    results = collection.query(query_texts=[query], n_results=n)
    docs = results.get("documents", [[]])[0]
    return "\n---\n".join(docs) if docs else "No matches found."

@mcp.tool()
def ingest_note(text: str, source: str) -> str:
    collection.add(documents=[text], metadatas=[{"source": source}], ids=[source])
    return f"Indexed: {source}"

Экосистемные servers для изучения в 2026: mcp-server-filesystem (official reference), GitHub MCP (repo/PR/issue ops), Brave Search MCP (web retrieval), Postgres MCP (SQL с schema introspection), Slack MCP (channel messaging). Тренды H2 2026: OAuth 2.1 standardized auth, unified server registries, multi-tenant hosted MCP marketplaces и Agent-to-Agent (A2A) orchestration над tool layer MCP.

Командам, которые запускают MCP Servers рядом с Cursor agents, ChromaDB ingestion и iOS CI на одном always-on узле, аренда облачного Mac Mini у MESHLAUNCH обычно лучший production host: dedicated Apple Silicon, без sleep disconnects, гибкая оплата день/неделя/месяц и стабильный дом для tool definitions как portable team assets вместо per-developer laptop configs. Спеки узлов — на странице цен; SSH и сеть — в центре помощи.