Connect an agent

Chronicle is an MCP server. Desktop and command-line clients start it locally over stdio. Hosted agents such as ChatGPT and the model APIs reach it over Streamable HTTP through a tunnel you control.

• Claude Code
• Claude Desktop and Cowork
• Cursor
• VS Code (Copilot)
• OpenAI Codex CLI
• Gemini CLI
• Windsurf
• Cline
• LM Studio
• Zed
• Continue
• Goose
• ChatGPT
• OpenAI Responses API
• Anthropic Messages API
• Gemini API
• Any HTTP client
• Any other client

Two ways to run the server

Installed. After uv tool install "chronicle-context[graph]", chronicle mcp install <client> writes the server into that client's config and keeps the old file as *.chronicle-backup. chronicle mcp config <client> prints the snippet instead, and --dry-run shows what would be written. Restart the client afterwards.

Without installing. Any client can run the published package through uvx, as long as uv is on its PATH:

{
  "mcpServers": {
    "chronicle": {
      "command": "uvx",
      "args": ["--from", "chronicle-context[graph]", "chronicle-context", "mcp"]
    }
  }
}

A stdio server can record by itself when the agent calls start_recording. Only one Chronicle process captures at a time (whichever holds ~/.chronicle/capture.lock), so this is safe alongside chronicle serve. Add --no-record to the args to turn it off. On macOS, the client app then needs the Screen Recording and Accessibility permissions.

Desktop and command-line clients

Claude Code

The plugin installs the server and a skill that tells Claude to call get_context before acting:

claude plugin marketplace add aniketxdey/chronicle
claude plugin install chronicle@chronicle

Or register the installed command directly, then run /mcp inside Claude Code to check it:

chronicle mcp install claude-code    # runs: claude mcp add --scope user chronicle -- chronicle mcp

Claude Desktop and Cowork

In Claude Desktop's plugin settings, add the marketplace aniketxdey/chronicle and install chronicle. Or write the config yourself:

chronicle mcp install claude-desktop

Quit and reopen Claude Desktop.

Cursor

Add to Cursor uses the uvx config. Or:

chronicle mcp install cursor

Check in Cursor's MCP settings that chronicle is enabled.

VS Code (Copilot agent mode)

chronicle mcp install vscode

Or, without installing Chronicle, let VS Code add it:

code --add-mcp '{"name":"chronicle","command":"uvx","args":["--from","chronicle-context[graph]","chronicle-context","mcp"]}'

Open Copilot Chat in Agent mode and enable the Chronicle tools from the tools picker.

OpenAI Codex CLI

chronicle mcp install codex

This adds a [mcp_servers.chronicle] table to ~/.codex/config.toml (%USERPROFILE%\.codex\config.toml on Windows), replacing an older Chronicle entry if there is one. Start a new session; /mcp lists the servers.

Gemini CLI

The extension installs the server and a GEMINI.md with instructions for when to call each tool:

gemini extensions install https://github.com/aniketxdey/chronicle

Or chronicle mcp install gemini-cli, which writes ~/.gemini/settings.json (%USERPROFILE%\.gemini\settings.json on Windows). /mcp in a session lists the tools.

Windsurf

chronicle mcp install windsurf

Writes ~/.codeium/windsurf/mcp_config.json (under %USERPROFILE% on Windows). Restart Windsurf.

Cline

chronicle mcp install cline

LM Studio

chronicle mcp install lm-studio

Writes ~/.lmstudio/mcp.json (under %USERPROFILE% on Windows). Use a local model that supports tool calls.

Zed

Print the snippet and add it under context_servers in Zed's settings (Zed: Open Settings):

chronicle mcp config zed

Continue

Add the printed block to ~/.continue/config.yaml. MCP tools work in agent mode.

chronicle mcp config continue

Goose

Add the printed block to ~/.config/goose/config.yaml, or run goose configure › Add Extension › Command-line extension with the command chronicle mcp.

chronicle mcp config goose

Hosted agents and model APIs

These run on someone else's servers, so they need a public HTTPS URL. chronicle serve exposes MCP at /mcp (protocol versions 2025-06-18, 2025-03-26, and 2024-11-05). Set a token first: with CHRONICLE_TOKEN set, every route except the UI shell and /health requires it, and requests with a non-local Origin header are rejected.

export CHRONICLE_TOKEN=$(openssl rand -hex 16)
export CHRONICLE_PUBLIC_URL=https://<your-tunnel-host>
chronicle serve &
cloudflared tunnel --url http://127.0.0.1:3030     # or ngrok, tailscale funnel
echo "$CHRONICLE_PUBLIC_URL/mcp/$CHRONICLE_TOKEN"

$env:CHRONICLE_TOKEN = -join ((1..32) | ForEach-Object { '{0:x}' -f (Get-Random -Max 16) })
$env:CHRONICLE_PUBLIC_URL = "https://<your-tunnel-host>"
Start-Process chronicle serve
cloudflared tunnel --url http://127.0.0.1:3030
"$env:CHRONICLE_PUBLIC_URL/mcp/$env:CHRONICLE_TOKEN"

Anyone with that URL can read your Chronicle data. Stop the tunnel when you're done, and rotate the token if the URL leaks. Clients that support headers can use /mcp with Authorization: Bearer $CHRONICLE_TOKEN instead.

ChatGPT

1. Start the server and tunnel as above.
2. In ChatGPT, open Settings › Connectors › Advanced and turn on Developer mode.
3. Create a connector with the URL https://<tunnel>/mcp/<token> and no authentication.

The search and fetch tools return the shapes that connectors and deep research expect. ChatGPT's app directory only lists hosted servers, so this per-user route is the supported one.

OpenAI Responses API

from openai import OpenAI

client = OpenAI()
response = client.responses.create(
    model="gpt-5",
    tools=[{"type": "mcp", "server_label": "chronicle", "server_url": URL, "require_approval": "never"}],
    input="Use get_context for the task 'file this week's expense report', then tell me the steps.",
)
print(response.output_text)

A fuller script is in examples/openai_responses.py.

Anthropic Messages API

Use the MCP connector beta alongside the computer-use tool, so Claude reads context before it clicks. examples/anthropic_computer_use.py shows the first turn.

response = client.beta.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=2048,
    betas=["mcp-client-2025-04-04"],
    mcp_servers=[{"type": "url", "url": URL, "name": "chronicle"}],
    messages=[{"role": "user", "content": "Call get_context for 'reply to the Acme thread' and summarize what I need."}],
)

Gemini API

The google-genai SDK accepts an MCP session as a tool and calls it automatically, so Gemini can use the local stdio server with no tunnel. chronicle mcp config gemini-api prints a complete script; install google-genai and mcp first.

Any Streamable HTTP client

curl -s "$URL" -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Any other client

{ "mcpServers": { "chronicle": { "command": "chronicle", "args": ["mcp"] } } }

Clients that read the official MCP Registry can search for io.github.aniketxdey/chronicle. To inspect the server by hand: npx @modelcontextprotocol/inspector --cli chronicle mcp --method tools/list.

Provider model names and beta flags change often. Treat the API snippets as starting points and check the provider's MCP docs.