How to Create an MCP Server: Tutorial

A developer has published a tutorial explaining how to create a Model Context Protocol (MCP) server, which allows AI assistants like Kiro, Codex, and Claude to interact with external systems. The tutorial uses a fictional TodoHub API to demonstrate how MCP servers provide an AI-friendly abstraction over REST APIs, translating simple tool inputs into complex API calls. It includes configuration examples using an mcp.json file and explains the architecture of AI agent, MCP client, and MCP server.

Model Context Protocol MCP allows an AI assistant such as Kiro, Codex, Claude, or another MCP-compatible agent to interact with external systems in a structured way. A useful mental model is: php AI Agent -- MCP Client -- MCP Server -- External API / Database / Application For this example, assume we have an internal Todo Management API called TodoHub . TodoHub provides REST APIs such as: GET /todos/123 POST /todos PUT /todos/123 POST /todos/123/comments We want an AI agent to understand requests such as: Show todo 123 or: Create a high-priority todo for fixing the login issue. Our MCP server acts as the bridge between the AI agent and the TodoHub API. Our architecture will look like this: php User ---- "Show todo 123" AI Agent Kiro / Codex / Claude ---- MCP tool call TodoHub MCP Server ---- HTTP REST call --- TodoHub API The MCP server exposes tools such as: get todo create todo update todo add comment These are MCP tools . The AI does not need to know exactly how the underlying REST API works. It only needs to understand the tool and its input: Tool: get todo Input: todo id The MCP server handles the actual API communication. For example: php AI ---- get todo todo id=123 | |----- MCP Server --- GET /api/todos/123 ---- TodoHub This distinction is important. You might wonder: Why don't we simply give the AI our REST API? The reason is that an MCP server provides the AI with a cleaner, AI-friendly abstraction over the underlying API. Your REST API might require something like: POST /api/v2/workitems with a request body: { "subject": "...", "type id": 7, "priority id": 3, "workspace id": 19, "creator": 758 } However, exposing all these internal implementation details to the AI is unnecessary. Instead, the MCP tool could expose a much simpler interface: create todo title, description, priority The MCP server translates the AI-friendly parameters into the parameters required by the internal application. For example: priority = "high" │ ▼ MCP Server │ ▼ priority id = 3 So the architecture becomes: AI-friendly parameters │ ▼ MCP Server │ ▼ Internal application parameters │ ▼ REST API This keeps implementation details away from the AI and gives the AI a simpler interface to work with. An MCP server can expose different tools for different operations. For our TodoHub example: | MCP Tool | Purpose | |---|---| get todo | Retrieve a todo | create todo | Create a new todo | update todo | Update an existing todo | add comment | Add a comment to a todo | For example: get todo Input: todo id: integer create todo Input: title: string description: string priority: string The AI can then select the appropriate tool based on the user's request. The AI agent needs to know how to start and communicate with the MCP server. For example, we can create an mcp.json configuration file: { "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json", "mcpServers": { "todohub": { "type": "stdio", "command": "uvx", "args": "--from", "mcp-todohub", "mcp-todohub" , "env": { "TODOHUB URL": "https://todos.example.com", "TODOHUB API KEY": "xxxxx" } } } } The important parts are: mcpServers │ └── todohub │ | SKILL.md ├── type ├── command ├── args └── env The configuration tells the AI client: todohub is available. stdio . uvx is used to start the server.Let's follow one complete request. Show me todo 123. The AI determines that the user wants information about a todo. Intent: Retrieve todo information Todo ID: 123 The MCP server has advertised tools such as: get todo todo id: int create todo ... update todo ... add comment ... The AI chooses: get todo with: todo id = 123 Conceptually, the request looks like: { "name": "get todo", "arguments": { "todo id": 123 } } The MCP server receives the request and executes something equivalent to: get todo 123 The MCP server then communicates with TodoHub: GET https://todos.example.com/api/todos/123 TodoHub returns: { "id": 123, "title": "Payment timeout", "status": "In Progress" } The MCP server sends the result back to the AI: TodoHub ↓ MCP Server ↓ AI The AI can now respond to the user: Task 123 is "Payment timeout"and is currentlyIn Progress. Putting everything together: User │ │ "Show me todo 123" ▼ AI Agent │ │ Understands intent ▼ Selects MCP Tool │ │ get todo todo id=123 ▼ MCP Server │ │ Translates tool input ▼ REST API │ │ GET /api/todos/123 ▼ TodoHub │ │ Returns JSON ▼ MCP Server │ │ Returns structured result ▼ AI Agent │ │ Generates natural-language response ▼ User The key idea is: MCP provides a standardized bridge between an AI agent and external systems. The AI works with meaningful tools such as get todo and create todo , while the MCP server takes care of authentication, API calls, parameter translation, and other implementation details. That is the complete MCP cycle. SKILL.md Additionally, we can have a SKILL.md file under the MCP project directory structure mentioned above. This becomes particularly useful when the MCP tool needs business context or parameter-building guidance that cannot be expressed cleanly through the tool schema alone . SKILL.md vs MCP Server An important distinction is: | Component | Purpose | |---|---| MCP Tool Definition | Tells the AI what the tool does and what parameters it accepts. | SKILL.md | Provides additional instructions, context, rules, examples, and parameter-building guidance for the agent. | MCP Server Code | Validates and translates the parameters before making the actual REST API call. | A SKILL.md generally contains: → Business context → How to construct parameters → Business rules → Examples For example, the MCP tool might simply define: create task title, description, priority While SKILL.md can explain how the AI should derive those parameters from the user's request , including business rules and examples. SKILL.md Maintainable If SKILL.md becomes too large, we can split the content into multiple Markdown files and organize them under a references directory. For example: taskhub-mcp/ ├── SKILL.md ├── server.py ├── tools/ │ ├── get task.py │ ├── create task.py │ ├── update task.py │ └── add comment.py └── references/ ├── task-creation.md ├── priority-rules.md └── business-rules.md This keeps the main SKILL.md concise while allowing more detailed business context to be maintained separately. Happy reading