MCP Server

Relevant source files

The following files were used as context for generating this wiki page:

• src/lib/mcp/server.ts
• src/app/api/mcp/route.ts
• CLAUDE.md
• PRODUCT.md
• src/lib/chat/tools.ts
• PRIVACY.md

The Hearth Model Context Protocol (MCP) server enables Large Language Model (LLM) agents to query household data through a standardized interface. It provides a set of read-only tools that allow agents to retrieve information about contracts, warranties, travel, vehicles, properties, inventory, and net worth. The server operates as a stateless service, requiring independent authorization for each request to ensure privacy and security.

Sources: src/app/api/mcp/route.ts:7-12, src/lib/mcp/server.ts:69-77, PRODUCT.md:32-34

Architecture and Data Flow

The MCP server is mounted as an API route at /api/mcp. It utilizes the @modelcontextprotocol/sdk to implement a transport-agnostic server that communicates via a web-standard streamable HTTP transport. Each incoming request initiates a new server and transport instance.

Request Lifecycle

1. Authorization: The server validates the Authorization: Bearer header against the MCP_TOKEN environment variable. If the token is missing or incorrect, the request fails with a 401 or 404 status.
2. Server Initialization: A new McpServer instance is created, and tools are registered based on the household's enabled modules.
3. Transport Binding: The server connects to a WebStandardStreamableHTTPServerTransport.
4. Tool Execution: The transport handles the request by executing the requested tool and returning the result as a JSON payload.

Sources: src/app/api/mcp/route.ts:18-31, src/lib/mcp/server.ts:69-77, CLAUDE.md:144-147

The diagram shows the sequential flow from an agent request through authentication and tool registration to data retrieval.
Sources: src/app/api/mcp/route.ts, src/lib/mcp/server.ts

Core Tools

The MCP server provides always-on tools for core features and dynamically registers additional tools for optional modules. All tools are read-only; they never modify household data or expose sensitive account credentials and raw document bytes.

Sources: src/lib/mcp/server.ts:72-77, CLAUDE.md:144-147

Contract Tools

These tools provide access to the Contract table, applying specific serialization to calculate spend and deadlines.

Tool Name	Description	Parameters
list_contracts	Lists contracts, optionally filtered.	status (Enum), category (Enum)
get_contract	Returns full details and document metadata for one contract.	id (String)
search_contracts	Case-insensitive search across title, provider, number, and notes.	query (String)
upcoming_renewals	Lists active contracts with deadlines within N days.	withinDays (Number, default 30)
spend_summary	Estimates total and per-category monthly spend.	N/A

Sources: src/lib/mcp/server.ts:80-176

Module-Gated Tools

Tools for optional modules only appear if the corresponding module is enabled in the household settings.

Module	Tool Name	Description
Travel	list_trips	Lists trips with segment counts.
Vehicles	list_vehicles	Lists vehicles and expiry dates.
Home	list_properties	Lists properties and valuation details.
Inventory	list_inventory_items	Lists catalogued household valuables.
Wealth	net_worth	Summarizes portfolio, property, and inventory value.

Sources: src/lib/mcp/server.ts:192-243, src/lib/chat/tools.ts:208-270

Data Serialization

The server serializes database records before returning them to the agent. For contracts, this includes calculating estimated monthly spend and specific renewal deadlines.

Contract Timing Logic

The server calculates several timing-related fields:

• daysUntilEnd: Days remaining until the endDate.
• cancelBy: The last date to give notice, derived from noticePeriodDays.
• daysUntilDeadline: The count until cancelBy if it is in the future, otherwise the count until endDate.
• estimatedMonthlySpend: The cost normalized to a monthly value based on billingFrequency.

Sources: src/lib/mcp/server.ts:46-64, src/lib/chat/tools.ts:74-88

This sequence diagram illustrates the stateless request handling where a server is instantiated per call.
Sources: src/app/api/mcp/route.ts, src/lib/mcp/server.ts

Security and Privacy

The MCP server maintains strict security boundaries:

• Read-Only: No write tools are registered. The server cannot create, update, or delete records.
• Sensitive Data: Account credentials and raw document bytes are never returned. get_contract only returns document filenames and metadata.
• Authentication: The endpoint returns a 404 if MCP_TOKEN is unset. Access requires a matching Bearer token.
• Local Scope: The server is designed for local or private network access as part of a self-hosted instance.

Sources: src/lib/mcp/server.ts:72-77, src/app/api/mcp/route.ts:13-17, PRIVACY.md:42

Summary

The Hearth MCP server acts as a standardized read-only gateway for LLM agents to understand household state. By integrating core contract management with optional modules like Wealth and Vehicles, it provides a comprehensive context for AI assistants while strictly preserving privacy through token-gated access and local serialization of sensitive data.