Guide

Connect an agentic client with MCP

TimeStrands runs a Model Context Protocol server so tools like Claude, opencode and Cursor can read and author your timelines. You authenticate with a personal access token, choose what it can do, and revoke it any time.

1. Create a personal access token

Go to Profile → API tokens (log in first) , give the token a name such as “Claude Desktop”, pick its abilities, and create it. Copy the value — it starts with ts_ and is shown once.

Read — list timelines and read tracks, events and exports.
Write — create and edit timelines, tracks and events.

Treat the token like a password. Anyone holding it can act as you, within the abilities you granted.

2. The endpoint

The server speaks the Streamable HTTP transport (JSON-RPC 2.0 over POST). Authenticate every request with a bearer token.

https://timestrands.com/mcp

Alias: https://timestrands.com/api/mcp. Either works; use whichever your client prefers.

Authorization: Bearer ts_your_token_here
Content-Type: application/json
Accept: application/json, text/event-stream

3. Configure your client

opencode

Add a remote MCP server to opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "timestrands": {
      "type": "remote",
      "url": "https://timestrands.com/mcp",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer ts_your_token_here"
      }
    }
  }
}

Claude Code

claude mcp add --transport http timestrands https://timestrands.com/mcp \
  --header "Authorization: Bearer ts_your_token_here"

Claude Desktop

Claude Desktop connects to remote servers through the mcp-remote bridge. Add this to claude_desktop_config.json:

{
  "mcpServers": {
    "timestrands": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://timestrands.com/mcp",
        "--header",
        "Authorization: Bearer ts_your_token_here"
      ]
    }
  }
}

Cursor

In .cursor/mcp.json:

{
  "mcpServers": {
    "timestrands": {
      "url": "https://timestrands.com/mcp",
      "headers": {
        "Authorization": "Bearer ts_your_token_here"
      }
    }
  }
}

4. What the agent can do

The server exposes a focused toolset. Read tools need the read ability; write tools need write. It deliberately exposes no external search: the agent should research topics with its own knowledge or web search, then write the result in.

Tool	Ability	Purpose
list_timelines	read	List the timelines in your organizations.
get_timeline	read	Metadata, tracks and range for one timeline.
list_tracks	read	Tracks (swimlanes) on a timeline.
list_events	read	Events, optionally filtered by track.
get_event	read	One event with raw date components and sources.
export_timeline	read	Canonical, re-importable JSON export.
create_timeline	write	Create a new private timeline.
update_timeline	write	Edit title, summary, license or range.
set_timeline_range	write	Set the default year span.
publish_timeline	write	Publish as public, unlisted or protected.
unpublish_timeline	write	Return a timeline to private draft.
create_track	write	Add a track.
update_track	write	Edit a track.
delete_track	write	Delete a track and its events.
create_event	write	Add an event.
update_event	write	Edit an event.
delete_event	write	Delete an event.
import_timeline	write	Bulk-load from an export document.

5. Resources and skills

Beyond tools, the server publishes resources and prompts (skills) your client can surface:

timestrands://reference/time-model — the date rules (BCE years, precision, circa, ranges). The agent is told to read this before writing dates.
timestrands://timeline/{uuid} — one resource per timeline, returning its canonical export.
build_historical_timeline — a skill that guides research-to-timeline creation from a topic.
extend_timeline — research and add to an existing timeline.
time_model_reference — the date reference as a skill.

Try prompts like:

Using TimeStrands, build a timeline of the Space Race from 1955 to 1975.
Add a track for "Missions" and plot the key launches with sources.
Then list my timelines and export the one called "Space Race".

6. Date model quick reference

Years are signed integers: negative = BCE (-44 is 44 BCE).
Every event carries a precision: millennium, century, decade, era, year, month, day, or the clock units hour/minute/second/millisecond.
A point event has no end year; a range sets end_year; a running thing sets is_ongoing.
Approximate dates use the honest precision plus start_is_circa: true.
importance is 1–5 (5 = pivotal).

7. Troubleshooting

401 Unauthorized: The token is missing, mistyped, revoked or expired. Create a fresh one under Profile → API tokens.
405 on GET: Expected. This server is request/response only and does not open a server-sent event stream; clients fall back to POST automatically.
“does not have the write ability”: The token was created read-only. Revoke it and issue one with the Write ability.
429 Too Many Requests: The endpoint is throttled. Back off and retry; agents that batch dozens of writes may need pacing.