Skip to content

External Integrations

What is this?

A specification for how ChatKcal receives data from the outside world, covering the "Magic Link" protocol and future Model Context Protocol (MCP) support.

ChatKcal is designed to be an "Intelligence Sink" — receiving structured data from external AI agents.

The primary ingestion mechanism is a deep link generated by an LLM.

Structure: https://chatkcal.app/log?meal_json=<JSON_String>

(Note: We prioritize readable, structured data over URL compression for now).

JSON Payload:

{
  "mealSummary": "Homemade Beef Chili",
  "emoji": "\ud83c\udf72",
  "calories": 650.5,
  "protein": 45.2,
  "carbs": 35,
  "fat": 38.5,
  "notes": "High fat estimate due to generous cheddar..."
}

Note on Compatibility: The system remains backward compatible with the legacy snake_case format (meal_summary, calories_kcal, etc.).

2. Future: MCP Support

Goal: Remove the "Copy/Paste" step entirely.

We plan to implement the Model Context Protocol (MCP) to allow local LLMs (like Claude Desktop) to connect directly to ChatKcal as a tool resource.

  • Tool: add_meal(meal_data)
  • Flow: The user talks to Claude, Claude calls the add_meal tool, and ChatKcal updates instantly.

3. Programmatic API (GraphQL)

For direct script access, iOS Shortcuts, or CLI tools, ChatKcal exposes a standard GraphQL API.

Authentication

Programmatic access requires a Personal Access Token (PAT), which can be generated in the Settings > API Access section of the Web App.

Header: Authorization: ck_live_...

Key Operations

Add a Meal

mutation AddMeal($mealSummary: String!, $calories: Float!, $protein: Float!, $carbs: Float!, $fat: Float!, $notes: String!, $userDate: String!) {
  addMeal(mealSummary: $mealSummary, calories: $calories, protein: $protein, carbs: $carbs, fat: $fat, notes: $notes, userDate: $userDate) {
    message
    item {
      sk
      mealSummary
      calories
    }
  }
}

Fetch Daily History

query GetMeals($from: String!, $to: String!) {
  getMeals(from: $from, to: $to) {
    count
    meals {
      mealSummary
      calories
      userDate
    }
  }
}

Quotas & Safety

To maintain low infrastructure costs, API usage is subject to daily quotas:

  • Reads: 5,000 / day
  • Writes: 500 / day

Note: Quota tracking use probabilistic sampling (writes are sampled at 5%, reads at 2%) to minimize database overhead.