How to effectively do spec-based development with Kiro

My learnings from using Kiro to build an MCP server end-to-end

Lopez Narvaez, Ramon

Published Jul 15, 2025

Last modified Jul 15, 2025

Recently, I wanted to build an  MCP server  for demo purposes. The idea was to access a graph-based code search backend (a story for another day) from within IDE's through MCP. My backend is exposed by Amazon API Gateway. So I thought to myself:
If I'd write up my requirements nicely - how far can I get with Kiro?
So that's exactly what I did. Here is what I did and what I learned along the way.
Don't rush the SpecWhen I first started to use Kiro, I would let it create a spec quickly and rush into code generation. I thought I would just fix all the inconsistencies later. That turned out to be a mistake! Modifying the spec after the first code generation, and then having to touch potentially dozens of files will cost more time and maybe even have unwanted side-effects.
So in my case, I had the details of my API Gateway backend and I knew that the MCP server should only expose a single tool. Here is a prompt that worked really well for me:
plaintext
I want to build an MCP Server that can query an API to search through a code base.
The backend is hosted in AWS API Gateway. Use the "searchCodeGraph" endpoint using the following arguments:
﻿
?command=queryGraph&index=class_metadata&query=asdf
or
?command=queryGraph&index=function_metadata&query=asdf
﻿
Endpoint URL: https://abcdefghijklm.execute-api.us-west-2.amazonaws.com/prod/searchCodeGraph
﻿
Response format when using index=class_metadata:
{
"responseBody": [
{
[INSERT_SAMPLE_RESPONSE]
}
﻿
Response format when using index=function_metadata
{
"responseBody": [
{
[INSERT_SAMPLE_RESPONSE]
}
﻿
 - The MCP Server should expose only a single tool.
 - Write the MCP server in Typescript and NodeJS
 - Write a short README that describes how to build the MCP server and how to configure it for the users MCP client.
Note that I provided actual sample responses from my API Gateway backend. This allowed Kiro to build tests against the API and implement it correctly on first try. You can also see that you don't need to provide a full API-specification or use a specific syntax - Kiro understands well enough what is code and what is an instruction.
Leverage Agent Steering depending on the maturity of your projectBy default, I found Kiro tries to build code that is close to production-readiness. I wanted to build "mature prototypes", meaning not a vibe-coded single file app but also not a full-fledged app with thousands of lines, performance tests etc.
That's where Agent Steering comes into play. These are Markdown files that Kiro will consider when generating code and writing specs. I started really simple with the following  coding_standards.md :
﻿
Then I clicked Refine in the top right corner and Kiro generated coding standards that reflected my intentions but added more detail:
﻿
This resulted in an app that was much leaner and faster to build. And once I'm happy with the results, I can still add more error handling, unit tests, integration tests...
Let it build the frontend for youI'm not a frontend developer but I do appreciate a well-functioning and nice-looking UI. Even if it's just for demo purposes or an easy-to-use admin interface, building a frontend takes time and effort. 
I found Kiro did a great job building a UI off of the Spec it created earlier. Because the backend code is in the same project context, Kiro can iterate autonomously to build a fully functional UI. This was my prompt:
plaintext
Build me a dashboard for the MCP Server we just built. 
 - Make it look like one of those hip AI product websites. 
 - The MCP Server can connect to it via WebSocket. 
 - The website should show activity of the MCP server live
 - It should show the result of each tool call
Kiro built the web frontend without any other intervention from me. And indeed, the color scheme does look suspiciously close to another hip AI product! 😇
﻿
Terminal awareness with context modifiersAnd one last tip: Working with web frontends you might be using your terminal a lot. But then you want help from your coding assistant to debug an error message. Which means copy-pasting exceptions and stack traces...
Not with Kiro. Just use the  #Terminal  context modifier and Kiro will be aware of what went on in your current terminal session.
﻿
Happy building!