Mira MCP: an open household manager over the Model Context Protocol

Mira is the AI household manager inside Kinetic Home, built for the Amazon Developer Hackathon "Build, Ship, Shape" (Alexa+ track). This repository is the open-source, run-anywhere version of her MCP server: a Streamable HTTP server on the official MCP TypeScript SDK, an Amazon Bedrock agent that discovers and calls her tools, a browser MCP client, an Agent Skill and integration tests. It runs on your own machine with a sample household. No accounts are needed.

Why it matters

Household coordination is a place where an AI should do the legwork but never hold the pen. A family wants something that can read the day, work out what one change knocks loose, and draft the fix. It does not want a model that sends, books or approves on its own.

This server puts that boundary in the protocol layer, so any client inherits it:

• The token an agent holds can read and draft only. Approval needs a separate human token the agent never sees, and only an adult member can approve.

• Stale plans are refused. If the household changed after a plan was drafted, approval fails and the agent must re-analyze.

• Requests are idempotent. Reusing a request key returns the same result; reusing it for a different action is rejected.

• Every approval leaves a receipt, and no external action runs without a connected adapter.

• Source text, notes and transcripts are treated as data, never as instructions.

Anyone building an Alexa+ add-on, a Bedrock agent or another MCP client for families can reuse the pattern.

Related MCP server: Relay

What is inside

How it works

1. Connect. A client sends POST /mcp with Authorization: Bearer <MCP_TOKEN>. The server listens on loopback only and rejects browser Origins it does not know. Each request gets a fresh stateless server and transport, with JSON responses.

2. Discover. tools/list returns four tools and resources/list returns household://progress/current:

3. Decide. A person approves with POST /approvals/:id, using the separate APPROVAL_TOKEN and an adult member as the actor. The agent has no tool for this.

4. Agent loop. agent.mjs connects as an MCP client, lists the tools, converts each tool's JSON Schema into a Bedrock Converse toolSpec, and loops through tool calls for up to eight steps. It never needs hand-written tool definitions: change the server and the agent follows.

Run it

macOS or Linux:

npm ci
export MCP_TOKEN=$(openssl rand -hex 32)
export APPROVAL_TOKEN=$(openssl rand -hex 32)
npm start

Windows PowerShell:

npm ci
$env:MCP_TOKEN = [guid]::NewGuid().ToString('N') + [guid]::NewGuid().ToString('N')
$env:APPROVAL_TOKEN = [guid]::NewGuid().ToString('N') + [guid]::NewGuid().ToString('N')
npm start

Open http://127.0.0.1:4317/, enter your MCP_TOKEN and connect. Save a draft, analyze the soccer change, prepare a plan, then enter the separate APPROVAL_TOKEN to record a human decision. The page does not store either token. Never give the approval token to an agent.

Run the Amazon Bedrock agent

With the server running, in a second terminal set AWS_REGION, BEDROCK_MODEL_ID and the same MCP_TOKEN, then:

npm run agent -- "Soccer moved to October 16 at 4:30 PM Eastern, ending at 5:30. Check the ripple effects and prepare a plan for my approval."

Or do everything in one step, for example in AWS CloudShell:

BEDROCK_MODEL_ID=us.anthropic.claude-haiku-4-5-20251001-v1:0 bash run-bedrock-test.sh

AWS credentials come from the standard AWS credential chain. Nothing is read from source files.

Status, honestly. On October 22, 2026 we ran the agent in AWS CloudShell (us-east-2) on a new AWS account. The server started, the agent connected over MCP and loaded the tools, and Bedrock refused every model call with "Too many tokens per day". Every "Model invocation max tokens per day" quota on that account is 0 and marked not adjustable, and approving Anthropic model access did not change it. The code path up to the model call is verified; the full loop needs an account with a normal Bedrock quota. We logged this as product feedback for the Bedrock team.

Test

npm test

The tests cover MCP initialization, tool discovery and calls, travel-time conflicts, non-mutating analysis, human-only approval, rejection of child approvals and stale plans, duplicate prevention and Origin validation.

Optional: bridge to a hosted household

Set BASE44_BRIDGE_URL, BASE44_APP_USER_TOKEN and BASE44_HOUSEHOLD_ID as server-side environment settings, never in a browser or in source. The bridge requires HTTPS. In this mode the server exposes the hosted household's read and draft tools instead of the sample data, and approvals happen only in the household app.

About Kinetic Home

Kinetic Home turns "we should" into time together. Mira plans family time, reads every family member's calendar, drafts invitations and, after a person approves, calls relatives in other homes. Scout, her research partner, finds real options with numbered sources. The hosted app runs its own MCP server with seven tools and an MCP Apps plan card for screen devices: kinetichome.vantalystlabs.com.

License

MIT. See LICENSE.