​

MCP Setup Guide

Connect AI clients to Syntropy Health via the Model Context Protocol (MCP). Audience: End users (longevitians) and developers adding new tools.

​

Quick Start (Users)

​

1. Generate an API Token

1. Open Settings in the Syntropy Health app
2. Expand Admin Tokens
3. Click Create New Token
4. Name it (e.g., “Claude Desktop”) and set an expiration
5. Copy the token immediately — it’s shown only once

​

2. Connect Your AI Client

​

3. Test the Connection

“What’s my diet score this week?”

​

Available Tools

​

Rate Limits

​

Developer Guide: Adding New MCP Tools

​

Architecture

MCP Tool (@mcp_server.tool)
  → _require_user_id(ctx)     # Auth
  → _check_rate(user_id, op)  # Rate limiting
  → _log_call(tool, user_id)  # Structured logging
  → _get_service(name)        # Service layer
  → service.method(user_id)   # Business logic
  → functions/*.py             # Data layer

​

Step-by-Step

1. Ensure the function exists in functions/ Check FUNCTION_TAXONOMY.md for the scope classification. Only User-Application and User-Data functions should be exposed via MCP.
2. Ensure a service method exists If the function isn’t wrapped by a service in api/services/, add a method. See INTEGRATION_SURFACES.md for the service layer pattern.
3. Add the tool to api/mcp/server.py
   @mcp_server.tool()
   async def my_new_tool(
       param: str,
       ctx: Context = ...,
   ) -> dict[str, Any]:
       """Clear description for LLM tool selection.
   
       Args:
           param: What this parameter does.
       """
       try:
           user_id = _require_user_id(ctx)
           _check_rate(user_id, "read")  # or "write"
           _log_call("my_new_tool", user_id)
           svc = _get_service("service_name")
           return await svc.my_method(user_id, param)
       except ValueError as e:
           return _error(str(e))
       except Exception as e:
           logger.error("my_new_tool failed: %s", e, exc_info=True)
           return _error("Service temporarily unavailable")
   
4. Add a contract test In tests/unit/test_mcp_server_contracts.py, add the tool name to the must_tools or should_tools list.
5. Update this document Add the tool to the Available Tools table above.

​

Tool Design Guidelines

• Descriptions are for LLMs, not humans. Be specific about what the tool returns.
• Use ctx: Context = ... — never = None. FastMCP injects Context via type annotation.
• Always call _check_rate before any service call.
• Always call _log_call for observability.
• Return _error() dicts on failure, not exceptions. MCP tools should not raise.
• Use “read” rate limit for data retrieval, “write” for data mutation and LLM calls.

​

What NOT to Expose

• Internal UI state management (states/)
• Partner operations (functions/partner/)
• Admin config (states/base.py ConfigurableState)
• Shopify sync operations (functions/consumer/shopify_*)
• Infrastructure (embeddings, checkpointers, middleware)

​

Troubleshooting

​

Environment Variables