MCP Server

The Clockchain exposes its temporal causal graph via the Model Context Protocol (MCP), making it accessible to any compatible AI agent framework (Claude, GPT, custom agents).

Status

Live — Clockchain MCP v1.26.0 is deployed at clockchain.timepointai.com/mcp/ using Streamable HTTP transport.

Endpoint

https://clockchain.timepointai.com/mcp/

Transport: Streamable HTTP

MCP Tools

Tool	Description
`clockchain_stats`	Get graph statistics (node count, edge types, date range)
`clockchain_search`	Search moments by keyword, date range, entity, location
`clockchain_moment`	Get a specific moment by canonical path with edges
`clockchain_neighbors`	Get causally connected moments (1 hop)
`traverse_moments`	Walk the causal graph N hops from a moment — map its causes and consequences
`find_path`	Find the shortest chain of historical connections linking two moments
`flash_render`	Render a new historical moment (requires auth)

traverse_moments and find_path are free read tools — no authentication required, rate-limited like the other read tools. They power multi-hop reasoning over the causal graph (the same capability behind the Temporal Navigator in the web app).

traverse_moments

Walk the causal graph N hops from a moment to map its causes and consequences.

Argument	Type	Description
`path`	string	Canonical path of the anchor moment (required)
`direction`	string	`past`, `future`, or `both` (default `both`)
`depth`	int	Hops from the anchor, 1–4 (default 2)
`edge_types`	string	Optional CSV of edge types (default: causal types)
`limit`	int	Max nodes, capped at 200 (default 50)

Example tool call:

{
  "name": "traverse_moments",
  "arguments": {
    "path": "/-44/march/15/1030/italy/lazio/rome/assassination-of-julius-caesar",
    "direction": "future",
    "depth": 2
  }
}

Response:

{
  "anchor": "/-44/march/15/1030/italy/lazio/rome/assassination-of-julius-caesar",
  "direction": "future",
  "depth": 2,
  "nodes": [
    {"id": "/-44/march/15/1030/italy/lazio/rome/assassination-of-julius-caesar", "name": "Assassination of Julius Caesar", "year": -44, "hop": 0},
    {"id": "/-43/november/27/1200/italy/lazio/rome/second-triumvirate-formed", "name": "Second Triumvirate Formed", "year": -43, "hop": 1}
  ],
  "edges": [
    {"source": "/-44/march/15/1030/italy/lazio/rome/assassination-of-julius-caesar", "target": "/-43/november/27/1200/italy/lazio/rome/second-triumvirate-formed", "type": "causes", "weight": 0.9}
  ],
  "node_count": 12,
  "edge_count": 17,
  "truncated": false
}

find_path

Find the shortest chain of historical connections linking two moments.

Argument	Type	Description
`from_path`	string	Canonical path of the start moment (required)
`to_path`	string	Canonical path of the end moment (required)
`max_hops`	int	Search bound (default 6)

Example tool call:

{
  "name": "find_path",
  "arguments": {
    "from_path": "/-44/march/15/1030/italy/lazio/rome/assassination-of-julius-caesar",
    "to_path": "/-31/september/2/1400/greece/epirus/actium/battle-of-actium"
  }
}

Response:

{
  "found": true,
  "from": "/-44/march/15/1030/italy/lazio/rome/assassination-of-julius-caesar",
  "to": "/-31/september/2/1400/greece/epirus/actium/battle-of-actium",
  "hops": 2,
  "nodes": [
    {"id": "/-44/march/15/1030/italy/lazio/rome/assassination-of-julius-caesar", "name": "Assassination of Julius Caesar", "hop": 0},
    {"id": "/-43/november/27/1200/italy/lazio/rome/second-triumvirate-formed", "name": "Second Triumvirate Formed", "hop": 1},
    {"id": "/-31/september/2/1400/greece/epirus/actium/battle-of-actium", "name": "Battle of Actium", "hop": 2}
  ],
  "edges": [
    {"source": "/-44/march/15/1030/italy/lazio/rome/assassination-of-julius-caesar", "target": "/-43/november/27/1200/italy/lazio/rome/second-triumvirate-formed", "type": "causes", "weight": 0.9},
    {"source": "/-43/november/27/1200/italy/lazio/rome/second-triumvirate-formed", "target": "/-31/september/2/1400/greece/epirus/actium/battle-of-actium", "type": "precedes", "weight": 0.7}
  ]
}

When no path exists within max_hops, the tool returns "found": false rather than an error. On invalid input the tools return an {"error": ..., "suggestion": ...} object instead of raising, so agents can self-correct.

Integration Example

Connect the Clockchain MCP server to your AI agent:

{
  "mcpServers": {
    "clockchain": {
      "url": "https://clockchain.timepointai.com/mcp/",
      "transport": "streamable-http"
    }
  }
}

Direct HTTP Access

Any AI agent can also query the Clockchain directly using the public REST API:

# Get graph stats
GET /api/v1/stats

# Search moments
GET /api/v1/moments?q=rome&year_from=-500&year_to=500

# Get specific moment
GET /api/v1/moments/{canonical-path}

No authentication required. 60 requests/minute rate limit. Sign up at timepointai.com for early access to authenticated tools.

Getting Started

Products

API Reference

MCP Server

MCP Server

Status

Endpoint

MCP Tools

Temporal Navigation Tools

traverse_moments

find_path

Integration Example

Direct HTTP Access

​MCP Server

​Status

​Endpoint

​MCP Tools

​Temporal Navigation Tools

​traverse_moments

​find_path

​Integration Example

​Direct HTTP Access

MCP Server

Status

Endpoint

MCP Tools

Temporal Navigation Tools

traverse_moments

find_path

Integration Example

Direct HTTP Access