AWS Builder Center

Builder Center

Building Your First MCP Server with Kiro's Spec-Driven Development (Part 1: Setup)

Building Your First MCP Server with Kiro's Spec-Driven Development (Part 1: Setup)

Learn to build a Model Context Protocol (MCP) server using Kiro's spec-driven development in this three part tutorial. Create a developer tools server following Kiro's three-phase methodology—requirements, design, and implementation—transform ideas into production-ready code. The process demonstrates how AI-assisted development combines with structured planning to create robust, maintainable software that extends your AI assistant's capabilities.

robbrad

Introduction

Tutorial Part 1 of 3
Building AI-powered tools has never been more accessible, but creating robust, maintainable solutions still requires thoughtful planning and structured development. In this tutorial, you'll learn how to build a Model Context Protocol (MCP) server using Kiro's spec-driven development methodology—a systematic approach that transforms rough ideas into production-ready code through three distinct phases: requirements, design, and implementation.

What is Kiro?

 Kiro  is an AI-powered IDE and assistant that helps developers build software through a structured, iterative process. Rather than jumping straight into code, Kiro guides you through creating clear requirements, thoughtful designs, and actionable implementation plans. This spec-driven approach ensures that what you build actually solves the problem you set out to address, with fewer surprises along the way.

What is the Model Context Protocol (MCP)?

The Model Context Protocol (MCP) is an open protocol that enables AI assistants like Kiro to interact with external tools, data sources, and services. Think of MCP servers as plugins that extend an AI assistant's capabilities—they can provide access to APIs, databases, file systems, or custom utilities that the AI can use to help you accomplish tasks.
MCP servers expose three main types of capabilities:
  • Tools: Functions that the AI can call to perform actions (e.g., format code, generate UUIDs, calculate hashes)
  • Resources: Data sources that the AI can read from (e.g., documentation, configuration files, reference data)
  • Prompts: Pre-defined prompt templates that guide AI interactions

Why Spec-Driven Development for MCP Servers?

Building an MCP server involves making decisions about what tools to expose, how to handle errors, what data formats to use, and how to ensure reliability. Spec-driven development helps you:
  • Clarify requirements early: Define exactly what your MCP server should do before writing code
  • Design with intention: Think through architecture, error handling, and edge cases upfront
  • Build incrementally: Break implementation into manageable, testable steps
  • Maintain quality: Ensure every feature maps back to a documented requirement
  • Iterate confidently: Make changes with a clear understanding of their impact

The Spec-Driven Development Workflow


Screenshot of Kiro's integrated development environment interface displaying the spec-driven development workflow.
The left sidebar shows a file explorer with the .kiro/specs folder expanded, revealing the developer-tools-mcp subfolder containing three markdown files: requirements.md, design.md, and tasks.md. The right panel shows Kiro's chat interface where an AI assistant is actively helping create spec documents through conversational interaction. The interface demonstrates the iterative nature of the workflow with clear visual separation between file management and AI-assisted development.- Context: Introduction section, illustrating the complete spec-driven development workflow in Kiro - Key elements: File explorer showing .kiro/specs directory structure, three spec documents (requirements, design, tasks), Kiro chat interface with AI assistance, visual representation of the iterative workflow

The workflow consists of three iterative phases:
  1. Requirements Phase: Transform your idea into clear, testable requirements using structured patterns (EARS - Easy Approach to Requirements Syntax)
  1. Design Phase: Create a comprehensive design document that addresses all requirements, including architecture diagrams, component specifications, and error handling strategies
  1. Tasks Phase: Break down the design into numbered, actionable implementation tasks that build incrementally on each other
  1. Implementation: Execute tasks one at a time with Kiro's assistance, ensuring each step is complete before moving to the next

What You'll Build

In this tutorial, you'll create a "Developer Tools" MCP server that provides practical utilities for common development tasks:
  • format_code: Format code snippets in Python, JavaScript, and JSON
  • generate_uuid: Generate UUIDs in different formats (UUID4, UUID5, short format)
  • encode_decode: Base64 and URL encoding/decoding utilities
  • calculate_hash: Calculate MD5, SHA256, and SHA512 hashes
  • common-regex-patterns: Access a library of frequently-used regex patterns
  • http-status-codes: Quick reference for HTTP status codes
This example is practical enough to be immediately useful while remaining simple enough to understand the core concepts.

Prerequisites Overview

Before starting this tutorial, you should have:
  • Basic Python knowledge: Familiarity with Python 3.12+ syntax and async/await patterns
  • Command line comfort: Ability to run terminal commands and navigate directories
  • 15-30 minutes: Time to work through the tutorial without interruption
You'll install additional tools (uv/uvx for Python package management and mcpdoc for documentation access) as part of the setup process in the next section.

What You'll Learn

By the end of this tutorial, you'll be able to:
  • Set up a development environment for building MCP servers
  • Use Kiro's spec-driven methodology to plan and build features systematically
  • Leverage the mcpdoc MCP server to access documentation during development
  • Implement MCP tools and resources using the FastMCP framework
  • Test and integrate your custom MCP server back into Kiro
  • Apply best practices for error handling, input validation, and code organization
Let's get started by setting up your development environment.


Prerequisites and Environment Setup

Before building your MCP server, you'll need to set up your development environment with the necessary tools. This section will guide you through installing Python, the uv/uvx package manager, and configuring the mcpdoc MCP server for accessing documentation.

Required Tools

Here's what you'll need installed on your system:
Tool
Version
Purpose
Python
3.12 or higher
Runtime for MCP server and FastMCP framework
uv/uvx
Latest
Fast Python package manager and runner
Kiro IDE
Latest
AI-powered IDE for spec-driven development

Step 1: Install Python 3.12+

Most modern systems come with Python pre-installed, but you'll need version 3.12 or higher for this tutorial.
Check your current Python version:
python3 --version
If you see  Python 3.12.x  or higher, you're all set. If not, install or upgrade Python:
macOS (using Homebrew):
brew install python@3.12
Linux (Ubuntu/Debian):
sudo apt update
sudo apt install python3.12 python3.12-venv python3-pip
Windows: Download the installer from  python.org  and ensure you check "Add Python to PATH" during installation.
Verify the installation:
python3 --version
# Should output: Python 3.12.x or higher

Step 2: Install uv and uvx

 uv  is a fast Python package manager written in Rust, and  uvx  is its companion tool for running Python applications without explicit installation. These tools make it easy to run MCP servers without managing complex virtual environments.
Install uv (includes uvx):
macOS and Linux:
curl -LsSf https://astral.sh/uv/install.sh | sh
Windows (PowerShell):
powershell -c "irm https://astral.sh/uv/install.ps1 | more"
Verify the installation:
uv --version
# Should output: uv 0.x.x or higher

uvx --version
# Should output: uvx 0.x.x or higher
What is uvx?
 uvx  allows you to run Python applications directly without installing them globally. When you run  uvx package-name , it:
  1. Downloads the package if needed
  1. Creates an isolated environment
  1. Runs the application
  1. Cleans up automatically
This is perfect for MCP servers, as you can run them on-demand without cluttering your system.

Step 3: Install Kiro IDE

If you haven't already installed Kiro, download it from the official website:
Download Kiro:
  • Download the version for your operating system
  • Follow the installation instructions for your platform
Verify Kiro is installed:
  • Launch Kiro
  • Open a new workspace or folder
  • Verify you can access the Kiro chat interface

Step 4: Configure mcpdoc MCP Servers for Documentation Access

The  mcpdoc MCP server  is a powerful tool that provides AI assistants with access to documentation through  llms.txt  files. In this step, you'll configure two separate instances of mcpdoc to access different documentation sources, demonstrating how multiple MCP servers can work together in your development environment.

Understanding llms.txt Files

Before configuring mcpdoc, it's important to understand what llms.txt files are and why they're useful:
What is llms.txt?
llms.txt is a standardized, markdown-based format designed to make documentation easily accessible to Large Language Models (LLMs) and AI assistants. Think of it as a "sitemap for AI"—it provides a structured index of documentation content that AI systems can efficiently navigate and search.
Key characteristics of llms.txt:
  • Structured format: Organizes documentation into sections with clear hierarchies
  • AI-optimized: Designed for efficient parsing and retrieval by language models
  • Human-readable: Still readable by humans, making it easy to verify and maintain
  • Standardized: Follows a consistent format across different projects and documentation sites
How mcpdoc uses llms.txt:
The mcpdoc MCP server reads llms.txt files from specified URLs and exposes their content through MCP tools that Kiro can use. When you ask Kiro a question about FastMCP or the MCP Protocol, it can:
  1. Search the documentation index
  1. Retrieve relevant sections
  1. Provide accurate, up-to-date answers based on official documentation
  1. Reference specific documentation pages for deeper exploration
This is particularly valuable when building MCP servers because you can access framework documentation and protocol specifications without leaving your development environment.

Why Configure Two mcpdoc Instances?

For this tutorial, you'll configure two separate mcpdoc servers:
  1. mcpdoc-fastmcp: Accesses FastMCP framework documentation from gofastmcp.com
  • Provides information about FastMCP's API, decorators, and patterns
  • Helps you understand how to implement tools, resources, and prompts
  • Offers examples and best practices for FastMCP development
  1. mcpdoc-mcp-protocol: Accesses MCP Protocol specification from modelcontextprotocol.io
  • Provides the official MCP Protocol specification
  • Explains protocol concepts, message formats, and communication patterns
  • Helps ensure your server follows protocol standards
Having both sources available means you can ask Kiro questions like "How do I define a tool in FastMCP?" or "What are the MCP protocol requirements for error handling?" and get accurate answers from the official documentation.

Setting Up mcpdoc Servers in Kiro

1. Create the MCP configuration directory:
Kiro stores MCP server configurations in  .kiro/settings/mcp.json  within your workspace. First, ensure the directory exists:
mkdir -p .kiro/settings
2. Create or update the MCP configuration file:
Create or open  .kiro/settings/mcp.json  in your workspace and add the following configuration:
{
  "mcpServers": {
    "mcpdoc-fastmcp": {
      "command": "uvx",
      "args": ["--from","mcpdoc","mcpdoc", "--urls", "FastMCP:https://gofastmcp.com/llms.txt","--transport", "stdio"],
      "env": {
        "FASTMCP_LOG_LEVEL": "ERROR"
      },
      "disabled": false,
      "autoApprove": []
    },
    "mcpdoc-mcp-protocol": {
      "command": "uvx",
      "args": ["--from","mcpdoc","mcpdoc", "--urls", "MCPProtocolDocs:https://modelcontextprotocol.io/llms.txt","--transport", "stdio"],
      "env": {
        "FASTMCP_LOG_LEVEL": "ERROR"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}
Understanding the configuration:
Let's break down each configuration field:
  • Server name ( "mcpdoc-fastmcp" ,  "mcpdoc-mcp-protocol" ): Unique identifier for each MCP server instance. You can name these anything, but descriptive names help you remember their purpose.
  •  command : The executable to run. We use  uvx  which automatically downloads and runs the mcpdoc package without requiring explicit installation.
  •  args : Arguments passed to the command:
  •  "mcpdoc" : Specifies the mcpdoc package and version (latest ensures you always get the newest version)
  •  "--urls" : Flag that tells mcpdoc where to find the llms.txt file
  • The URL: Points to the specific llms.txt file for each documentation source
  •  env : Environment variables for the server:
  •  "FASTMCP_LOG_LEVEL": "ERROR" : Reduces log verbosity to only show errors, keeping your console clean
  •  disabled : Boolean flag to enable/disable the server without removing the configuration. Set to  false  to enable.
  •  autoApprove : Array of tool names that Kiro can call without asking for permission. Empty array means you'll approve each tool call manually (recommended for security).
3. Save the configuration file:
After adding the configuration, save the file. Kiro will automatically detect the changes.
4. Restart or reconnect MCP servers in Kiro:
After saving the configuration, Kiro will load the new servers:
Using the MCP Server View
  1. Open the Kiro sidebar (usually on the left side of the window)
  1. Look for the "MCP SERVERS" section or panel
  1. You should see "mcpdoc-fastmcp" and "mcpdoc-mcp-protocol" listed
  1. Click the refresh/reconnect icon next to each server
  1. Wait for the status to change to "Connected" (indicated by a green checkmark)


Verifying mcpdoc Servers Are Working

It's important to verify that your mcpdoc servers are properly configured and functioning before proceeding. Here are several ways to test them:
Verification Method 1: Check Server Status in Kiro
  1. Open the MCP Servers panel in Kiro's sidebar
  1. Verify both servers show "Connected" status
  1. Click on each server to expand and see available tools
  1. You should see tools like:
  •  list_doc_sources : This Lists the document sources
  •  fetch_docs : Fetch documentation from URLs

Verification Method 2: Test with a Documentation Query
In Kiro's chat interface, try asking a question that requires documentation access:
Can you search the FastMCP documentation for information about creating tools with the @mcp.tool() decorator?
If the mcpdoc-fastmcp server is working correctly, Kiro will:
  1. Use the  search_content  tool to search FastMCP documentation
  1. Retrieve relevant information about the  @mcp.tool()  decorator
  1. Provide an answer based on the official documentation
  1. Potentially include links to specific documentation pages
Try another query for the MCP Protocol documentation:
What are the required fields in an MCP tool definition according to the protocol specification?
This should trigger the mcpdoc-mcp-protocol server to search the protocol documentation.
Expected Success Indicators:
✅ Both servers show "Connected" status in Kiro's MCP Server panel ✅ Each server lists available tools (search_content, fetch_docs, etc.) ✅ Kiro can answer questions using documentation from both sources ✅ No error messages appear in Kiro's console or MCP Server logs ✅ Tool calls complete successfully and return relevant documentation

Next Steps

With your environment set up, you're ready to start building your MCP server using Kiro's spec-driven development methodology. In the next section, you'll create the requirements document that defines exactly what your Developer Tools MCP server should do.
Now you are ready to proceed to  Part 2: Design 

This tutorial is part of the AWS Builder Center's collection of developer resources. For more tutorials, guides, and community content, visit  https://builder.aws.com/ .
# mcp-server# kiro# ai# agentic-ai# spec-drivien-development
Any opinions in this article are those of the individual author and may not reflect the opinions of AWS.
Enjoyed reading this content? Let the author know!

Your likes, comments, shares, and saves help creators reach more builders.

Loading recommendations

Loading article