Skip to main content

​
Integration Surfaces

How the same business logic is exposed to different consumers. This document maps every integration surface to the underlying functions/ layer and defines which surface serves which audience. Updated: 2026-03-25 | PRD: PRD-20

​
Surface Architecture

                         ┌──────────────────┐
                         │    Clerk Auth     │
                         │  (JWT / API key)  │
                         └────────┬─────────┘
                                  │
         ┌────────────────────────┼────────────────────────┐
         │                        │                        │
┌────────▼────────┐   ┌──────────▼──────────┐   ┌────────▼────────┐
│   REST API      │   │   MCP Server        │   │  Reflex States  │
│   (FastAPI)     │   │   (FastMCP)         │   │  (UI surface)   │
│                 │   │                     │   │                 │
│  /api/ext/*     │   │  /mcp               │   │  CheckinState   │
│  /api/diet/*    │   │                     │   │  ChatState      │
│  /api/v1/*      │   │  Consumer tools:    │   │  CatalogState   │
│  /api/health    │   │  chat_with_shrine   │   │  ProfileState   │
│                 │   │  log_food           │   │  etc.           │
│  Chrome ext     │   │  get_diet_score     │   │                 │
│  Shopify sync   │   │  ...               │   │  Web app only   │
│  Slack          │   │                     │   │                 │
└────────┬────────┘   └──────────┬──────────┘   └────────┬────────┘
         │                        │                        │
         └────────────────────────┼────────────────────────┘
                                  │
                       ┌──────────▼──────────┐
                       │   Service Layer     │
                       │   api/services/     │
                       │                     │
                       │  ChatService        │
                       │  DietService        │
                       │  CheckinService     │
                       │  ProfileService     │
                       │  LLMService         │
                       └──────────┬──────────┘
                                  │
                       ┌──────────▼──────────┐
                       │   functions/        │
                       │   (business logic)  │
                       └──────────┬──────────┘
                                  │
                       ┌──────────▼──────────┐
                       │   PostgreSQL +      │
                       │   Milvus/Zilliz     │
                       └─────────────────────┘

​
Surface Comparison

SurfaceAudienceAuthTransportLocationStatus
REST API — ExtensionChrome extension usersClerk JWTHTTPS JSONapi/routes/extension_api.pyProduction
REST API — DietWeb app + extensionClerk JWTHTTPS JSONapi/routes/diet.pyProduction
REST API — IntegrationPartner apps (Shopify)Clerk JWT + scopesHTTPS JSONapi/routes/integration.pyProduction
REST API — Consumer ShopifyEnd users (order sync)Clerk JWTHTTPS JSONapi/routes/consumer_shopify.pyProduction
REST API — PairingDevice pairingPairing codeHTTPS JSONapi/routes/pairing.pyProduction
REST API — HealthMonitoringNoneHTTPS JSONapi/routes/health.pyProduction
REST API — SlackSlack botSlack signingHTTPS JSONapi/routes/slack.pyBeta
REST API — StripeStripe webhooksStripe signatureHTTPS JSONapi/routes/stripe_webhook.pyProduction
REST API — TokensToken managementClerk JWTHTTPS JSONapi/routes/tokens.pyBeta
MCP Server — ConsumerAI clients (Claude, ChatGPT, VS Code)Clerk JWT (OAuth 2.1)Streamable HTTPapi/mcp/server.py (NEW)Planned (PRD-20)
Reflex StatesWeb app usersClerk sessionWebSocketstates/Production

​
Consumer MCP vs REST API

The consumer MCP and REST API serve different interaction patterns:
AspectREST APIConsumer MCP
ConsumerChrome extension, web app, scriptsAI assistants (Claude, ChatGPT, Copilot)
InteractionProgrammatic, structured requestsNatural language → tool selection by LLM
AuthAuthorization: Bearer <jwt> headerMCP OAuth 2.1 (same Clerk JWT underneath)
DiscoveryOpenAPI spec (docs/api/openapi.json)MCP tools/list + tool descriptions
Tool designREST conventions (GET/POST/PUT/DELETE)LLM-optimized descriptions, fewer but richer tools
StreamingSSE for chat endpointsSSE via MCP Streamable HTTP transport

​
Overlap

Several operations are available on both surfaces. This is intentional — different clients need different access patterns:
OperationREST EndpointMCP ToolSame functions/ call
Get health profileGET /api/ext/profileget_health_profileget_health_profile_sync()
Log foodPOST /api/ext/food-loglog_foodcreate_food_log_sync()
Diet scoreGET /api/diet/scoreget_diet_scorecompute_diet_fulfillment_score()
Diet gapGET /api/diet/gapget_diet_gapcompute_diet_gap()
Analyze foodPOST /api/ext/diet/analyzeanalyze_foodanalyze_food_text()
Health snapshotGET /api/diet/snapshotget_health_snapshotbuild_health_snapshot()

​
MCP-Only Operations

These operations only make sense in the MCP context:
MCP ToolWhy MCP-only
chat_with_shrineConversational AI — requires agent loop, not a single REST call
get_my_checkinsBrowsing context for ShrineAI — REST equivalent exists but MCP version is optimized for LLM consumption

​
Partner MCP (Future, Separate)

Partner operations are scoped to a separate MCP server on the Shopify tech stack. This is not part of PRD-20.
ScopeConsumer MCPPartner MCP
UserIndividual longevitianDTC brand / wellness partner
AuthClerk JWT (user role)Clerk JWT (partner role) + Shopify OAuth
ToolsHealth data, ShrineAI, dietProtocol CRUD, adherence analytics, feedback
Data boundaryUser’s own data onlyPartner’s protocols + anonymized aggregate data
DeploymentJournals app (/mcp)Shopify app (separate)

​
Adding a New Surface

When exposing business logic to a new integration surface:
  1. Ensure logic is in functions/ — not in states/ or api/routes/
  2. Add or extend a service in api/services/ that wraps the function calls
  3. Create the surface adapter (route, MCP tool, Reflex state method)
  4. Auth: All surfaces must authenticate via Clerk JWT or equivalent
  5. Update this document with the new surface entry
  6. Update FUNCTION_TAXONOMY.md with any new MCP tool mappings

​
Agent Policy

Syntropy Health adopts an ultra-open stance toward external AI agents:
  • All user-facing business logic in functions/ is available to authenticated agents
  • We do not restrict based on which AI client is connecting
  • Only internal UI state and partner operations are excluded from consumer MCP
  • The value is in health data and ShrineAI intelligence, not interface control
This policy applies to the consumer MCP. Partner MCP has separate access controls.