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 causal graph of 196+ historical moments spanning 2000+ years
Generate timepoints — rich historical scenes with narratives, characters, dialog, and AI images (coming soon)
Navigate time — step forward/backward from any moment to discover what came before and after (coming soon)
Chat with historical characters — in-context conversations with period-appropriate personalities (coming soon)
Run simulations — multi-entity temporal scenarios via the SNAG engine (coming soon)

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

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 at 30 req/min. Generation and simulation tools require an API key and 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

Phase 1 (live now) — Clockchain read tools

Tool	Auth	Description
`search_moments`	Optional	Search the temporal causal graph for historical events
`get_moment`	Optional	Get full detail for a historical moment by its canonical path
`browse_graph`	Optional	Browse the graph hierarchy — year, month, day, location, event
`get_connections`	Optional	Get causal/thematic connections: what caused this, what it caused
`today_in_history`	Key	Events that happened on today's date across all eras
`random_moment`	Key	Random historical moment for serendipitous discovery
`graph_stats`	Optional	Node/edge counts, date range, source distribution

Phase 2 (coming soon) — Generation tools

Tool	Credits	Description
`generate_timepoint`	5-10	Generate a historical timepoint with scene, characters, dialog, image
`temporal_navigate`	2	Step forward/backward in time from an existing timepoint
`chat_with_character`	1	Converse with a historical character in context
`get_timepoint`	0	Retrieve a previously generated timepoint
`list_my_timepoints`	0	List your generated timepoints
`get_credit_balance`	0	Check credits and usage

Phase 3 (planned) — Simulation tools

Tool	Credits	Description
`run_simulation`	10	Run a SNAG temporal simulation
`get_simulation_result`	0	Get simulation results

Pricing

Tier	Price	Monthly Credits	Rate Limit
Anonymous	Free	—	30 req/min (read-only)
Free	Free	5 signup credits	60 req/min
Explorer	$7.99/mo	100	60 req/min
Creator	$19.99/mo	300	300 req/min
Studio	$49.99/mo	1,000	1,000 req/min

Credit packs also available as one-time purchases.

HTTP endpoints

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

Method	Path	Description
GET	`/`	Landing page (JSON for agents, redirect for browsers)
GET	`/health`	Service health check
GET	`/account/status`	Auth status and tier info
POST	`/admin/create-key`	Create API key (requires admin key)

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
 Clockchain  Flash      Billing
 (graph)    (writer)   (Stripe/IAP)

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

Tech stack

Python 3.11+ with FastMCP, Starlette, httpx, asyncpg
Transport: Streamable HTTP (production), stdio (local dev)
Database: PostgreSQL (API keys + usage logs)
Deployment: Railway (Docker)

Environment variables

# Downstream services
FLASH_URL=https://api.timepointai.com
FLASH_SERVICE_KEY=...
FLASH_ADMIN_KEY=...
CLOCKCHAIN_URL=...
CLOCKCHAIN_SERVICE_KEY=...
BILLING_URL=...
BILLING_SERVICE_KEY=...

# Database
DATABASE_URL=postgresql://...

# Server
PORT=8000

Timepoint MCP