MCP Server Reference

Recommended Agent interface. Cloud MCP is the default path for durable memory, context, knowledge bases, files, and workspace governance. The standalone CLI enables advanced local runtime workflows: automatic Sessions, directed Tasks, Agent communication, and diagnostics.

Stable compatibility surface. Cloud MCP remains the supported public interface for durable knowledge. Runtime delivery, sessions, tasks, and communication stay in the connected TokST Runtime and Dashboard.

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.

Scope

Cloud MCP provides durable memory, knowledge-base selection, workspace governance, evidence files, and account status. Every request resolves the credential to a stable agt_... audit identity. Tasks, automatic sessions, Agent communication, handoffs, endpoint health, and automatic-memory controls use the connected TokST Runtime and Dashboard.

Connection Modes

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/mcp and /.well-known/oauth-authorization-server. Clients that support Dynamic Client Registration can register automatically.

When a client reaches /mcp without credentials, TokST returns 401 Unauthorized with WWW-Authenticate: Bearer, the required mcp scope, and the protected-resource metadata URL. MCP clients use this challenge to start browser authorization instead of treating the endpoint as unreachable.

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.

Tool Reference

TokST Cloud MCP exposes memory, organization, attachment, and account tools. The public endpoint provides 32 focused 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. Exact active records in the same workspace, atlas, and type return the existing ID with duplicate: true and duplicateOf. Ordinary MCP writes preserve the supplied content and do not run automatic sensitive-content classification. Encrypted sensitive storage is optional and disabled by default. A Workspace Owner can enable it in Dashboard Settings; a user then explicitly selects it for a manually saved record. Those records use encryption, skip embeddings and automatic capture, and require confirmSensitive: true for a confirmed read.

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 accessible memories with stable cursor pagination. Continue with nextCursor until hasMore is false.

The result includes count, hasMore, snapshotAt, and nextCursor when another page is available. Unknown parameters are rejected.

tokst_memory_get

For a controlled sensitive record, MCP returns metadata with the body hidden by default. Pass confirmSensitive: true only after the user explicitly asks to view the original. Every confirmed read is audited.

Get a single memory with full details and attachments.

tokst_memory_update

Update one or more fields on a memory. A content update refreshes its retrieval vector. The response includes the saved title, tags, content byte count, and embedding status.

Provide at least one of title, content, or tags.

tokst_memory_append

Append content to an existing memory. Surrounding blank lines are normalized to one \n\n separator. Updating or appending to a verified memory returns it to needs_review.

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_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. fileUrl must be a publicly reachable HTTPS download URL and may not resolve to a private network. Remote MCP uploads are limited to 50 MB per file. The result identifies the failed stage when a source, upload authorization, object upload, or upload confirmation cannot complete.

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_archive

Archive an atlas. Its memories and attachments remain recoverable in the Dashboard archive view.

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.

tokst_workspace_archive

Archive a workspace. Its resources remain recoverable in the Dashboard archive view.

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
• CLI Runtime: tokst login --key <key> stores its cloud credential in ~/.tokst/config.json for connected endpoint, session, task, and diagnostic workflows.

Connected Runtime

Install the TokST CLI to connect supported Agents. The Runtime uses authenticated WSS delivery for task assignment, Agent communication, automatic-session capture, handoffs, endpoint health, and execution results. Use the Dashboard to manage these workflows; use MCP to retrieve and store durable knowledge.