Rhylthyme MCP server

A Model Context Protocol server for schedules that a person executes: cooking several dishes so they finish together, running a bench protocol with overlapping incubations, calling an event, running a workout. An agent describes the process, the server validates and analyzes the resulting program, and publishes it as a live timeline on rhylthyme.com that the person follows on their phone.

This repository is the source of the server that runs at mcp.rhylthyme.com. It is the same code as mcp-api/ in the rhylthyme-server application, copied here with the static assets it needs so it can be read, tested and self-hosted.

Endpoints

Transport: Streamable HTTP, stateless. No sign-in is needed for the public catalog or the pure tools; account tools take a per-user token from the login tool. Server instructions describing the workflow are sent at initialize.

Related MCP server: Orchestro

Connect

Claude Code

claude mcp add --transport http rhylthyme https://mcp.rhylthyme.com/mcp
claude mcp add --transport http rhylthyme-kitchen https://mcp.rhylthyme.com/kitchen/mcp

Claude Desktop / claude.ai: Settings → Connectors → Add custom connector → paste one of the URLs above. Public tools work immediately; run login only to save to your own account.

Cursor (.cursor/mcp.json):

{ "mcpServers": { "rhylthyme": { "url": "https://mcp.rhylthyme.com/kitchen/mcp" } } }

Claude API (MCP connector, one request):

import anthropic
client = anthropic.Anthropic()
resp = client.beta.messages.create(
    model="claude-opus-5", max_tokens=16000,
    betas=["mcp-client-2025-11-20"],
    mcp_servers=[{"type": "url", "url": "https://mcp.rhylthyme.com/kitchen/mcp", "name": "rhylthyme"}],
    tools=[{"type": "mcp_toolset", "mcp_server_name": "rhylthyme"}],
    messages=[{"role": "user", "content": "Plan Thanksgiving for 8 with one oven, dinner at 6pm."}],
)

Tools

Annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) are set on every tool; four tools also declare an outputSchema and return structuredContent. Failures set isError and say what to do next.

Resources and prompt

• rhylthyme://schema/program: the program JSON Schema (0.3.0-alpha)

• rhylthyme://guide/authoring: one-page authoring rules, trigger vocabulary, how to make tracks finish together, repeated work (replicates, per-instance instances: "each" chains, "all" barriers and maxInFlight), choice branching

• rhylthyme://examples/{breakfast_schedule, lab_experiment, stir_fry_with_choice, hiit_cardio_workout, corporate_presentation, cookies_three_trays}: complete valid programs (cookies_three_trays is the 0.3.0-alpha per-instance / in-flight worked example)

• prompt plan_schedule(goal, finishAt?, constraints?): walks the model through search → build → validate → analyze → visualize, and names replicates / instances / maxInFlight in its constraints step

What a program looks like

{
  "schemaVersion": "0.1.0",
  "programId": "eggs-and-toast",
  "name": "Eggs and toast",
  "tracks": [
    { "trackId": "eggs", "name": "Eggs", "steps": [
      { "stepId": "whisk", "name": "Whisk", "task": "prep",
        "duration": { "type": "fixed", "seconds": 60 },
        "startTrigger": { "type": "programStart" } },
      { "stepId": "cook", "name": "Cook", "task": "stove",
        "duration": { "type": "variable", "minSeconds": 120, "maxSeconds": 240, "defaultSeconds": 180 },
        "startTrigger": { "type": "afterStep", "stepId": "whisk" } } ] },
    { "trackId": "toast", "name": "Toast", "steps": [
      { "stepId": "toast", "name": "Toast", "task": "toaster",
        "duration": { "type": "fixed", "seconds": 180 },
        "startTrigger": { "type": "afterStep", "stepId": "cook", "event": "start", "offsetSeconds": 60 } } ] }
  ],
  "resourceConstraints": [
    { "task": "prep", "maxConcurrent": 1 },
    { "task": "stove", "maxConcurrent": 2 },
    { "task": "toaster", "maxConcurrent": 1 }
  ]
}

Steps in one track run sequentially; parallel work goes in separate tracks; every task needs a resource constraint; durations and offsets take seconds or strings like "5m". Triggers: programStart, programStartOffset, afterStep (end or event: "start", signed offset), afterStepWithBuffer, manual, onAbort, or {logic: all|any, triggers}. Durations: fixed, variable (ended early by the executor), indefinite (ended by the executor).

Self-hosting

git clone https://github.com/rhylthyme/rhylthyme-mcp
cd rhylthyme-mcp
npm install            # Node 20 or newer
npm test                 # SDK in-memory + HTTP entry-point tests, no network
PORT=3000 npm start      # http://localhost:3000/mcp and the four vertical paths

Docker: docker build -t rhylthyme-mcp . && docker run -p 3000:3000 rhylthyme-mcp. Vercel: vercel in the repository root; vercel.json rewrites the endpoint paths to the function.

What self-hosting does and does not give you: validation, timing analysis, the renderer, resources and prompts run in your process. Catalog search, sharing (visualize_schedule), imports and account tools call the public API at https://www.rhylthyme.com (API_BASE in mcp-api/index.js), so those still depend on the hosted service. The PNG preview route /api/og/timeline.png additionally needs SUPABASE_URL and SUPABASE_ANON_KEY for read access to shared programs; nothing else does.

Layout

• mcp-api/index.js: tool, resource and prompt registration; vertical detection; OG-image route; Vercel handler

• mcp-api/schedule.js: validator and analyzer (pure)

• static/js/timeline-render.js: timing engine and SVG Gantt (also published as @rhylthyme/timeline)

• static/schema/, static/examples/: the resources

• src/index.js: standalone HTTP runner

• mcp-api/server.json: MCP registry manifest

Known limitations

• login hands the user a URL and expects a pasted, short-lived access token that then travels as a tool argument; it is outside MCP's OAuth 2.1 flow. Hosts that require OAuth for authenticated servers can still use every public tool.

• search_public_recipes searches one environment at a time; the generic endpoint defaults to kitchen.

• Tool annotations are self-declared hints; hosts may ignore them.

License

MIT (this repository). The renderer in static/js/timeline-render.js carries its own Apache-2.0 header.