geolocal-io/docs/engineering/technical-roadmap.md

Product & Technical Roadmap

1. The Guiding Principle

geolocal.io is an infrastructure platform, not a destination site.

Everything we build must follow a single principle: make it dead simple for a partner to deploy an MCP endpoint for a local business, and make that endpoint compelling enough that AI agents prefer it.

This means:

• No coding required for the business or partner to set up
• Centralized MCP hosting (multi-tenant) with a simple JSON pointer for each business
• Rich, structured data that gives AI agents a reason to trust and use our endpoints
• A self-reinforcing network where more data attracts more agents, which generates more data

---

2. Technical Architecture Overview

2.1 High-Level System Components

Component	Description	Technology Stack
MCP Gateway	Multi-tenant router that directs requests to the correct business MCP server	Node.js/TypeScript, FastMCP framework
Business MCP Server	Hosts the actual MCP tools for each business; dynamically generated from database	TypeScript, MCP SDK
Business Database	Stores business profiles, metadata, structured content, and telemetry	PostgreSQL, Supabase / Railway
JSON Manifest Generator	Generates the /.well-known/mcp-server JSON file for each business	Static file generation
Partner Dashboard	Agency-facing portal for onboarding, management, and analytics	React/Next.js, Tailwind
CoC Dashboard	Chamber-facing portal for member management and analytics	React/Next.js, Tailwind
Business Dashboard	SMB-facing portal for profile management and analytics	React/Next.js, Tailwind
Telemetry Pipeline	Captures and processes MCP interaction data for analytics and DaaS	Postgres, Redis, Webhooks

2.2 Data Flow

AI Agent → MCP Gateway → Business MCP Server → Database / Cal.com / Stripe ↓ Telemetry Pipeline → Dashboards / Analytics

---

3. Technical Enablers: MCP Patterns You Can Leverage

3.1 Orchestration Pattern

Multiple MCP servers can be composed into a single endpoint, exposing tools from multiple sources to the AI as a unified interface.

Relevance to you: Your gateway will handle orchestration, enabling you to pull in tools from Cal.com's MCP or your own proprietary tools seamlessly.

3.2 Deployment Modes

Mode	Description	Best For
Managed-Shared	Single MCP server instance serves multiple users simultaneously	Your scenario: Centralizing data from many businesses into one server
Managed-Dedicated	Each business gets their own container instance	High-security or high-traffic businesses
Remote	MCP server hosted by a third party; you just get a URL	Cal.com's MCP server integration

3.3 Transport Options

Transport	Description	Best For
SSE (Server-Sent Events)	Simple, server-push capable, easier for older clients	Quick start, simple use cases
Streamable HTTP	More efficient, supports larger payloads, recommended for production	Recommended for your platform

3.4 Tool Design Best Practices

Best Practice	Example
Granular tools	get_business_info, check_availability, book_appointment (not one giant do_everything tool)
Clear descriptions	Descriptions help the AI decide which tool to call
Structured inputs	Use JSON Schema for parameters
Rich outputs	Include links to visuals, booking confirmation, etc.

---

4. Phase 1: MVP (90 Days)

4.1 MVP Scope

Component	Features	Priority
MCP Gateway	Single multi-tenant MCP endpoint; basic routing by tenant	Must-have
Business Database	Store: business name, address, hours, services, description, photos URLs, Cal.com link	Must-have
MCP Tools	get_business_info, get_hours, get_services, get_booking_link	Must-have
Cal.com Integration	Redirect to Cal.com booking page (Phase 1: no deep API integration)	Must-have
JSON Manifest Generator	Generate /.well-known/mcp-server file for each business	Must-have
Partner Dashboard	Partner sign-up, client onboarding (add client → generate manifest)	Must-have
Telemetry	Basic logging: request counts, tool calls, response times	Nice-to-have

4.2 Implementation Plan: 90-Day Sprint

Week	Deliverable
1-2	Stand up PostgreSQL database; define schema; build business CRUD API
3-4	Build MCP server using TypeScript + MCP SDK; implement first tools (get_business_info, get_hours)
5-6	Implement JSON manifest generator; test discovery flow
7-8	Build Partner Dashboard (sign-up, client management, manifest download)
9-10	Integrate Cal.com (redirect); test end-to-end flow
11-12	Onboard 10 pilot businesses; collect feedback; iterate

4.3 Hosting Infrastructure Decision

Option	Pros	Cons	Recommended?
Railway	One-click deployment, free tier, simple	Less control, scaling limits	✅ Recommended for MVP
CreateOS	Native MCP auto-discovery, persistent Postgres, marketplace	Newer platform, smaller community	Consider for production
AWS ECS / Fargate	Full control, enterprise-grade	Operational overhead, more complex	Later stage
Google Cloud Run	Serverless, scales well	Cold starts, less MCP-specific tooling	Later stage

Recommendation: Start with Railway for MVP speed. Plan to migrate to CreateOS or AWS for production scale.

---

5. Phase 2: Scale & Features (180 Days)

5.1 Expanded Scope

Component	Features
MCP Tools (Expanded)	check_availability (via Cal.com API), book_appointment (via Cal.com API)
Deep Cal.com Integration	Direct API integration (not just redirect); availability checks; booking creation
Stripe Integration	Payment capture for deposits; account creation for businesses
Rich Content Layer	Story, owner bio, high-quality photos, video; structured for AI extraction
Related Businesses Tool	get_related_businesses handshake; competitive intelligence capture
MCP Gateway (Advanced)	Rate limiting, authentication, OAuth support
Business Dashboard	SMB-facing portal for profile management; basic analytics
Partner Dashboard (Expanded)	White-label support; client analytics; commission tracking
CoC Dashboard	Member management; group analytics; lead reporting
Telemetry Pipeline	Structured logging; event tracking; basic analytics dashboards

5.2 Implementation Plan

Phase	Month	Deliverable
5.2.1	4	Deep Cal.com API integration; Stripe payment capture; expanded MCP tools
5.2.2	5	Related Businesses tool; telemetry pipeline; basic analytics
5.2.3	6	Business Dashboard; CoC Dashboard; white-label support

---

6. Phase 3: Ecosystem & Monetization (360 Days)

6.1 Expanded Scope

Component	Features
Data-as-a-Service (DaaS)	Anonymized telemetry data for licensing; AI Local Demand Index; competitive benchmarks
Plugin Ecosystem	WordPress plugin; Webflow app; Framer plugin
Chamber Partnership Portal	White-labeled CoC onboarding; member analytics; lead reporting
Multi-Vertical Support	Auto repair, beauty, home services, wellness, etc.
Developer API	Public API for custom MCP server development
OAuth & Authorization	OAuth 2.1 with Dynamic Client Registration (DCR) for partner integrations
Advanced Telemetry	Agent behavior analysis; market trend identification; anomaly detection
Feedback Loop	Verification tools; AI agent conflict reporting; automated data correction

6.2 Implementation Plan

Phase	Month	Deliverable
6.2.1	7-9	WordPress plugin; Webflow app; Chamber Partnership Portal
6.2.2	10-12	DaaS product launch; multi-vertical support; OAuth/authorization layer
6.2.3	12+	Feedback loop; advanced telemetry; public developer API

---

7. Technology Stack Recommendations

Layer	Technology	Rationale
Backend	Node.js / TypeScript	MCP SDK is TypeScript-first; large ecosystem
API Framework	FastMCP	High-performance, minimal boilerplate for MCP servers
Database	PostgreSQL (Supabase / Railway)	Reliable, JSON support, hosted options
Frontend	React / Next.js	Modern, fast, server-side rendering for dashboards
Hosting	Railway (MVP) → CreateOS / AWS (prod)	Balance of speed, cost, and control
Cache	Redis	For rate limiting, session management
Analytics	Postgres / Custom	You control the telemetry; build your own analytics layer
Payment	Stripe	Mature, API-first, handles deposits and subscriptions
Booking	Cal.com API	MCP-aware, structured API, booking + payment integration

---

8. Key Technical Risks & Mitigation

Risk	Mitigation
MCP protocol changes rapidly	Follow the official MCP GitHub; use stable SDK versions; subscribe to release notes
Cal.com API changes	Build a small abstraction layer; use Cal.com's official MCP server where possible
Scalability of multi-tenant MCP	Design for horizontal scaling; use Redis for session management; monitor performance
Latency from AI agents	Optimize tool responses; use caching; prioritize frequent tools
Security of OAuth flows	Use OAuth 2.1 with PKCE; follow MCP's security recommendations; regular audits
Data privacy concerns	Design privacy-first; avoid storing sensitive PII; comply with GDPR/CCPA
Telemetry volume growth	Use cost-effective storage; batch writes; use data compression

---

9. Technical Guiding Principles

Principle	Why It Matters
Standard-first	Follow MCP standards; avoid proprietary customizations
Simple over complex	Start simple; add complexity only when needed
Observable by design	Log everything; make telemetry a first-class feature
Security by default	OAuth, rate limiting, data validation from day one
Partner-first UX	Dashboards and onboarding should prioritize partner ease over "consumer polish"
Data ownership	Capture telemetry; build a data moat

---

10. Citation Table

ID	Source
[1]	Anthropic, "Model Context Protocol GitHub Repository," 2024-2026
[2]	MCP Documentation, "Server Deployment Modes," 2026
[3]	MCP Documentation, "Transport Options," 2026
[4]	MCP Documentation, "Tool Design Best Practices," 2026
[5]	Railway, "MCP Server Deployment Guide," 2026
[6]	CreateOS, "MCP Server Hosting Documentation," 2026
[7]	Cal.com, "MCP Server Documentation," 2026