Kiro + Civic MCP Reference Implementation

A reference implementation showing how to integrate Civic's MCP gateway with Kiro IDE for Google Calendar and Gmail access.

What This Is

A Node.js app that connects to Civic Hub (a remote MCP gateway) to interact with Google Calendar and Gmail. It demonstrates:

• Kiro project structure — .kiro/ directory with steering files, specs, and MCP configuration
• Civic MCP integration — Streamable HTTP transport to Civic's hosted gateway
• Calendar operations — List events, create events
• Gmail operations — List messages, create drafts

All OAuth tokens and API credentials are managed by Civic server-side — no Google credentials are stored locally.

Prerequisites

• Node.js 20+
• A Civic account with Google Calendar and Gmail servers added to a toolkit
• A Civic token (generate from Install → MCP URL)

Setup

1. Clone and install:

   cd aws-kiro-reference-implementation-civic
   npm install

2. Configure environment:

   cp .env.example .env

   Edit .env with your Civic credentials:

   CIVIC_URL=https://api.civic.com/mcp?profile=your-toolkit-name
   CIVIC_TOKEN=your-civic-token-here
   

3. Authorize Google services in Civic:

   • Go to app.civic.com
   • Add Google Calendar and Google Gmail MCP servers to your toolkit
   • Complete the OAuth authorization flow for each

4. Start the server:

   npm start

5. Open in browser:

   http://localhost:3000
   

Using with Kiro IDE

Open this project folder in Kiro:

• Steering files in .kiro/steering/ give Kiro context about the project
• MCP config in .kiro/settings/mcp.json connects Kiro's agent to Civic — you can use Calendar/Gmail tools directly in Kiro chat
• Specs in .kiro/specs/ document the feature requirements and design

To use Civic tools in Kiro chat, add your CIVIC_URL and CIVIC_TOKEN to your environment or Kiro's MCP settings.

Project Structure

.kiro/
├── settings/mcp.json           # Civic MCP gateway config for Kiro
├── steering/                   # AI context files
│   ├── product.md
│   ├── tech.md
│   └── structure.md
└── specs/                      # Feature specifications
    └── calendar-gmail-integration/
src/
├── server.js                   # Express entry point
├── mcp-client.js               # Civic MCP client wrapper
└── routes.js                   # API route handlers
public/
└── index.html                  # Web UI

API Endpoints

Method	Path	Description
GET	/api/tools	List available MCP tools
GET	/api/events	List calendar events
POST	/api/events	Create a calendar event
GET	/api/messages	List Gmail messages
POST	/api/drafts	Create a Gmail draft

Troubleshooting

• "Missing CIVIC_URL or CIVIC_TOKEN" — Copy .env.example to .env and fill in your credentials
• No tools returned — Check that your CIVIC_URL includes ?profile=your-toolkit-name and the toolkit has Calendar/Gmail servers configured
• 401 errors — Your Civic token may be expired (30-day expiry). Regenerate at app.civic.com
• Tool name mismatch — Run GET /api/tools to see actual tool names from your Civic profile and update routes.js if they differ

License

MIT