# 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

| Mode | Transport | Use Case |
|---|---|---|
| **Remote (Streamable HTTP, 51 tools)** | `https://api.tokst.com/mcp` | ChatGPT, web-based agents, memory and workspace workflows |
| **Remote (SSE compatibility, 51 tools)** | `https://api.tokst.com/sse` | MCP directories and clients that only accept SSE or stdio |
| **Local (stdio, 51 tools)** | `tokst local mcp` | Desktop agents using the standalone installer |

## 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.

```json
{ "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`](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.

```json
{
  "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](https://tokst.com/dashboard/api-keys), then use this configuration:

```json
{
  "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.

```json
{
  "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`:

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

### Cursor

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

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

### Codex CLI

```toml
# ~/.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.

| Tool | Purpose |
|---|---|
| `tokst_workspace_members` | List members and roles |
| `tokst_workspace_invitations` | List invitations sent from a workspace |
| `tokst_workspace_invite` | Send one or more invitations with role and expiry |
| `tokst_workspace_invitation_inbox` | List invitations for the current user |
| `tokst_workspace_invitation_respond` | Accept or decline an invitation |
| `tokst_workspace_invitation_revoke` | Revoke a pending invitation |
| `tokst_workspace_leave` | Leave a workspace |
| `tokst_workspace_member_role` | Set a member to `admin` or `member` |
| `tokst_workspace_member_remove` | Remove a member |
| `tokst_workspace_owner_transfer` | Transfer Owner to an existing member |

### Memory Operations

#### `tokst_remember`

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

| Parameter | Type | Required | Description |
|---|---|---|---|
| `content` | string | yes | The memory content |
| `type` | string | no | `fact`, `decision`, `preference`, `task`, `architecture`, `note` (default: `note`) |
| `tags` | string | no | Comma-separated tags |
| `source` | string | no | Source name (default: `mcp`) |
| `evidence` | string | no | Evidence URL or source file path |
| `confidence` | number | no | Confidence from 0 to 1 |
| `validUntil` | string | no | ISO expiry date-time |
| `atlasId` | string | no | Target atlas (auto-routes by keyword if omitted) |
| `title` | string | no | Optional title |

#### `tokst_search`

Adaptive scoped search shared with CLI and REST.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `query` | string | yes | Search query |
| `type` | string | no | Filter by type |
| `tags` | string | no | Comma-separated tag filter |
| `atlasId` | string | no | Scope to a specific atlas |
| `mode` | string | no | `auto`, `keyword`, `semantic`, or `hybrid` (default: `auto`) |
| `limit` | number | no | Max results (default: 20) |

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.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `atlasId` | string | no | Atlas ID (all if omitted) |
| `limit` | number | no | Max items per type (default: 10) |

#### `tokst_memory_list`

List recent memories.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `type` | string | no | Filter by type |
| `atlasId` | string | no | Scope to atlas |
| `limit` | number | no | Max results (default: 20) |

#### `tokst_memory_get`

Get a single memory with full details and attachments.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes | Memory ID |

#### `tokst_memory_update`

Replace a memory's content.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes | Memory ID |
| `content` | string | yes | New content |

#### `tokst_memory_append`

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

| Parameter | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes | Memory ID |
| `content` | string | yes | Content to append |

#### `tokst_memory_verify`

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

| Parameter | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes | Memory ID to verify |
| `evidence` | string | no | Evidence URL or source file path |
| `confidence` | number | no | Confidence from `0` to `1` |
| `validUntil` | string | no | ISO expiry date-time |

#### `tokst_memory_supersede`

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

| Parameter | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes | Memory being superseded |
| `replacementMemoryId` | string | yes | Newer replacement memory |

#### `tokst_memory_archive`

Soft-archive a memory (restorable).

| Parameter | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes | Memory ID |

#### `tokst_memory_restore`

Restore an archived memory to active status.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes | Memory ID |

#### `tokst_memory_delete`

Permanently delete a memory.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes | Memory ID |

#### `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.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `memoryId` | string | yes | Memory ID |
| `files` | array | no | File supplied by ChatGPT (`openai/fileParams`) |
| `fileUrl` | string | no | Downloadable URL for generic MCP clients |
| `filename` | string | no | Override filename |

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.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `memoryId` | string | yes | Memory ID |
| `attachmentId` | string | no | Specific attachment; omit for all attachments |

### Atlas Operations

#### `tokst_atlas_list`

List all atlases. No parameters.

#### `tokst_atlas_init`

Create a new atlas (knowledge base).

| Parameter | Type | Required | Description |
|---|---|---|---|
| `name` | string | yes | Atlas name |
| `workspaceId` | string | no | Workspace (uses default if omitted) |
| `keywords` | string | no | Comma-separated keywords for auto-routing |

#### `tokst_atlas_rename`

Rename an atlas.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `atlasId` | string | yes | Atlas ID |
| `name` | string | yes | New name |

#### `tokst_atlas_profile`

Set auto-routing keywords for an atlas.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `atlasId` | string | yes | Atlas ID |
| `keywords` | string | yes | Comma-separated keywords |

#### `tokst_atlas_delete`

Delete an atlas and all its memories.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `atlasId` | string | yes | Atlas ID |

### 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.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `name` | string | yes | Workspace name |

#### `tokst_workspace_delete`

Delete an empty workspace.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `workspaceId` | string | yes | Workspace ID |

### 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.

```text
`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](/docs/sessions) for a full Agent operating flow, handoff rules, review permissions, Local parity, and retry behavior.