MCP Server Reference

The TokST MCP (Model Context Protocol) server lets AI agents interact with your memory system directly. Claude Code, Codex, Pi, WorkBuddy, ZCode, Qoder, Kimi, and other MCP clients can store, search, and manage memories through natural language.

For durable decisions, architecture, meeting notes, and tasks, send structured Markdown in content. Use headings, lists, task checkboxes, links, tables, and code blocks when they improve review. Short facts can remain plain text; keep credentials, private keys, raw reasoning, and transient tool output outside memory records.

Trusted Agent Identity and Messages

Every local or remote MCP request resolves the API Key to a stable agt_... identity and refreshes its last active time. source on tokst_remember remains a human-readable source label. The full toolset includes tokst_agent_list, tokst_message_send, tokst_message_inbox, tokst_message_acknowledge, and tokst_message_close. Broadcast messages create a receipt for every active Agent in the target workspace.

Automatic Memory

Automatic memory uses tokst_auto_status and tokst_auto_configure across remote MCP, stdio MCP, and the local CLI. Native bridges identify their source as workbuddy, opencode, pi, codex, or claude; ACP uses acp. Claude Desktop uses these same MCP Session tools in assisted mode. The local service performs redaction and compiles one revocable memory when a durable task ends.

Connection Modes

Local SQLite mode

Run tokst setup --local once, then set TOKST_MODE=local for @tokst/mcp-server. The package delegates to the same local CLI runtime and uses the same tool names and SQLite profile.

{ "mcpServers": { "tokst-local": { "command": "tokst-mcp", "env": { "TOKST_MODE": "local" } } } }

Remote Setup (for ChatGPT & remote agents)

The public MCP manifest is available at https://api.tokst.com/.well-known/mcp. It advertises the Streamable HTTP endpoint, OAuth metadata, and the API-key path for static clients.

Configure a remote MCP client with the endpoint below. On first connection, the client opens TokST sign-in and approval in the browser. TokST uses OAuth 2.1 authorization-code flow with PKCE and creates a stable trusted Agent identity for the approved client.

{
  "mcpServers": {
    "tokst": {
      "type": "streamable-http",
      "url": "https://api.tokst.com/mcp"
    }
  }
}

The remote endpoint is stateless Streamable HTTP: every request carries authentication and can be served by any healthy instance. It returns JSON tool responses and does not require a persistent MCP session ID.

The authorization server advertises OAuth metadata at /.well-known/oauth-protected-resource and /.well-known/oauth-authorization-server. Clients that support Dynamic Client Registration can register automatically.

API Key remote setup

WorkBuddy, ZCode, Qoder, Kimi, CI, and other clients with static MCP settings can connect with a dedicated API key. Create it in Dashboard API Keys, then use this configuration:

{
  "mcpServers": {
    "tokst": {
      "type": "streamable-http",
      "url": "https://api.tokst.com/mcp",
      "headers": {
        "Authorization": "Bearer tk_live_your_api_key"
      }
    }
  }
}

Create a separate key for each client. Store it in the client's protected environment-variable store, keep it out of source code and version control, and revoke keys that are no longer used.

SSE compatibility setup

Some MCP directories only offer SSE and stdio. Select SSE and configure the endpoint below. Add TOKST_API_KEY as a private environment variable in the directory; its value is a dedicated tk_live_... API key.

{
  "mcpServers": {
    "tokst": {
      "type": "sse",
      "url": "https://api.tokst.com/sse?api_key=${TOKST_API_KEY}"
    }
  }
}

TokST validates the opening SSE connection with the API key, then returns a short-lived session endpoint for MCP requests. Use Streamable HTTP for clients that support it.

Local Setup (for desktop agents)

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "tokst": {
      "command": "bun",
      "args": ["x", "-y", "@tokst/mcp-server"]
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "tokst": {
      "command": "bun",
      "args": ["x", "-y", "@tokst/mcp-server"]
    }
  }
}

Codex CLI

# ~/.codex/config.toml
[mcp_servers.tokst]
command = "bun"
args = ["x", "-y", "@tokst/mcp-server"]

The Cloud MCP endpoint uses browser authorization or a dedicated API key. Local MCP uses the private Local SQLite profile created by tokst setup --local. Both expose the complete 57-tool surface, including automatic-memory Session control and normalized event reporting; Cloud also provides workspace governance, Agent collaboration, attachments, and account operations. Set TOKST_MCP_TOOLSET=core on a remote deployment only for the focused 11-tool memory surface.

Tool Reference

Remote and local MCP both expose administrative, team, and attachment tools by default. TOKST_MCP_TOOLSET=core limits a remote service to the 11 core memory tools.

Workspace Governance Tools

These tools use the same role checks as the dashboard. confirm: true is required for accepting or declining invitations, revoking invitations, leaving, changing roles, removing members, and transferring ownership.

Memory Operations

tokst_remember

Store a new memory with auto-routing and embedding generation.

tokst_search

Adaptive scoped search shared with CLI and REST.

The tool result includes the same ordered memories and meta timing/cache fields as REST.

tokst_context

Get a structured context snapshot grouped by memory type.

tokst_memory_list

List recent memories.

tokst_memory_get

Get a single memory with full details and attachments.

tokst_memory_update

Replace a memory's content.

tokst_memory_append

Append content to an existing memory (adds \n\n separator).

tokst_memory_verify

Verify a memory with supporting evidence, confidence, and an optional expiry date.

tokst_memory_supersede

Mark an older memory as superseded by a newer record in the same Atlas.

tokst_memory_archive

Soft-archive a memory (restorable).

tokst_memory_restore

Restore an archived memory to active status.

tokst_memory_delete

Permanently delete a memory.

tokst_attach_file

Attach one ChatGPT-uploaded file or remote URL to an existing memory. The remote server downloads it and uploads it to R2.

Provide either files or fileUrl. Remote MCP uploads are limited to 50 MB per file.

tokst_download_file

Get secure download links for one or all attachments on a memory. Links expire after 15 minutes and are also returned as MCP resource_link content.

Atlas Operations

tokst_atlas_list

List all atlases. No parameters.

tokst_atlas_init

Create a new atlas (knowledge base).

tokst_atlas_rename

Rename an atlas.

tokst_atlas_profile

Set auto-routing keywords for an atlas.

tokst_atlas_delete

Delete an atlas and all its memories.

Workspace Operations

tokst_workspace_list

List all workspaces. No parameters.

tokst_workspace_create

Create a new workspace.

Cloud Team workspace creation uses the account's available Team workspace quota. Local MCP continues to use the local workspace model.

tokst_workspace_delete

Delete an empty workspace.

Account

tokst_status

Get account overview: plan, usage, storage, workspace/atlas counts. No parameters.

Authentication

• Remote: API Key in Authorization: Bearer tk_live_xxx header
• Local: reads ~/.tokst/config.json (created by tokst login --key <key>)

Session Memory Protocol

Use Session tools for work that spans multiple actions or needs a durable handoff.

`tokst_session_start` — atlasId, task
`tokst_session_capture` — sessionId, kind, content, tags
`tokst_session_checkpoint` — sessionId, summary
`tokst_session_finalize` — sessionId, summary
`tokst_session_reopen` — sessionId (cloud/stdio ACP only; keeps the same automatic memory)
`tokst_session_revert_automatic_memory` — sessionId, reason (cloud/stdio only; archives the automatic memory and retains audit history)
`tokst_session_status` — sessionId
`tokst_session_list` — workspaceId, scope, atlasId, status
`tokst_session_list_candidates` — workspaceId, scope, atlasId, status
`tokst_session_moderate_candidate` — sessionId, candidateId, action
`tokst_session_archive` — sessionId, archived

Session start returns scoped context. Capture stores durable candidates. Finalize writes a snapshot and compiles candidates into formal memories by default. Workspace owners and admins can review the managed Session view, compile or dismiss candidates, revert compiled candidates, and archive completed work without losing the audit trail.

Read the Session Memory guide for a full Agent operating flow, handoff rules, review permissions, Local parity, and retry behavior.