> ## Documentation Index
> Fetch the complete documentation index at: https://docs.timepointai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server

> Clockchain MCP interface for AI agent frameworks.

# 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)                               |

## Temporal Navigation Tools

`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](/products/clockchain#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:**

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

**Response:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```bash theme={null}
# 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](https://timepointai.com) for early access to authenticated tools.