timepoint-mcp

MCP server for the Timepoint AI temporal knowledge platform.

Live at: mcp.timepointai.com

What is this?

A hosted Model Context Protocol server that gives AI agents structured access to the Timepoint ecosystem:

• Search & browse a continuously growing temporal causal graph of historical moments spanning 700 BCE to 2026

• Generate moments — rich historical scenes rendered by the Flash reality-writing engine

• Publish moments — promote your private moments into the public clockchain

• Index TDF records — load pre-formatted Timepoint Data Format records directly (admin)

Planned: temporal navigation, character chat, and multi-entity SNAG simulations.

Works with Claude Desktop, Cursor, Windsurf, VS Code Copilot, the Anthropic Agent SDK, and any MCP-compatible client.

Related MCP server: Bi-Temporal Knowledge Graph MCP Server

Get an API key

Visit timepointai.com or reach out on X @timepointai to request access.

Clockchain read tools (search, browse, moment detail) work without authentication, rate-limited at 30 req/min. Write tools require an API key with the appropriate scope, and generation also requires credits.

Quick start

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "timepoint": {
      "url": "https://mcp.timepointai.com/mcp",
      "headers": {
        "X-API-Key": "tp_mcp_..."
      }
    }
  }
}

Cursor / Windsurf

Add to .cursor/mcp.json or equivalent:

{
  "mcpServers": {
    "timepoint": {
      "url": "https://mcp.timepointai.com/mcp",
      "headers": {
        "X-API-Key": "tp_mcp_..."
      }
    }
  }
}

Anthropic Agent SDK

from claude_agent_sdk import Agent
from claude_agent_sdk.mcp import MCPServerRemote

agent = Agent(
    model="claude-sonnet-4-6",
    mcp_servers=[
        MCPServerRemote(
            url="https://mcp.timepointai.com/mcp",
            headers={"X-API-Key": "tp_mcp_..."},
        )
    ],
)
result = agent.run("What happened in Rome in 44 BC?")

Local development

git clone https://github.com/timepointai/timepoint-mcp.git
cd timepoint-mcp
pip install -e .

# stdio transport (for Claude Desktop local)
python -m app.server --transport stdio

# HTTP transport (for remote testing)
python -m app.server --transport http --port 8000

Available tools

Clockchain read tools — live now

No authentication required; anonymous callers are rate-limited.

Write tools — live now

Require an API key with the listed scope.

Planned

• Temporal navigation — step forward/backward in time from an existing moment

• Character chat — converse with historical characters in context

• Simulations — multi-entity temporal scenarios via the SNAG engine

Pricing

Credit packs are also available as one-time purchases.

HTTP endpoints

In addition to the MCP protocol at /mcp, the server exposes:

Architecture

MCP Clients (Claude Desktop, Cursor, agents, SDKs)
        |
        | Streamable HTTP + X-API-Key
        v
   timepoint-mcp (mcp.timepointai.com)
   FastMCP + Starlette + asyncpg
        |
   -----+----------+-------------+----------+
   |               |             |          |
   v               v             v          v
 Clockchain      Flash      API Gateway   Billing
 (graph)        (writer)     (credits)    (tiers)

The MCP server is a thin coordination layer. It authenticates requests via API keys, resolves user tiers via Billing, checks and spends credits via the API Gateway, routes tool calls to the appropriate backend, and enforces per-tier rate limits. It never stores credits or subscriptions — the Gateway and Billing own those.

Tech stack

• Python 3.11+ with FastMCP, Starlette, httpx, asyncpg, uvicorn

• Transport: Streamable HTTP (production), stdio (local dev)

• Database: PostgreSQL (API keys + usage logs)

• Deployment: Railway (Docker)

Environment variables

# Downstream services
FLASH_URL=https://flash.timepointai.com
FLASH_OUTBOUND_KEY=...        # key sent to Flash as X-Service-Key (legacy alias: FLASH_SERVICE_KEY)
FLASH_ADMIN_KEY=...           # admin key gating POST /admin/create-key
CLOCKCHAIN_URL=...
CLOCKCHAIN_SERVICE_KEY=...
BILLING_URL=...
BILLING_SERVICE_KEY=...
GATEWAY_URL=...               # API Gateway — owns the credit ledger
GATEWAY_SERVICE_KEY=...

# Database
DATABASE_URL=postgresql://...  # API keys + usage logs; runs anonymous-only if unset

# Server
PORT=8000                      # honored by the Docker CMD (Railway sets this)
MCP_HOST=0.0.0.0               # defaults to 0.0.0.0; MCP_PORT defaults to 8000
MCP_SIGNING_SECRET=...         # request-signing secret

Timepoint Suite

Render the past. Simulate the future. Score the predictions. Accumulate the graph.

License

Proprietary. Copyright 2026 Timepoint AI.