MCP errors and write recovery
이 상세 자료는 아직 한국어로 번역되지 않아 영문 원문을 표시합니다.
GA 공개 출처와 지원 범위
- Status
- GA
- Component
- Thegram Cloud MCP
- Deployment
- Cloud service https://vault.thegram.one/mcp
- Applies to version
- Latest
- 출처 확인일
- 2026-10-25
- Owner
- thegram-one/thegram-vault
- Public evidence
- Basis
- Current public instructions identify the Cloud MCP service; the page’s desktop socket recovery material is explicitly historical rather than current Cloud onboarding.
All pages: version and status matrix
출처 확인은 실제 계정 설치·기기 동작·서비스 상태의 검증을 뜻하지 않습니다.
This page retains source-pinned Core and legacy desktop error evidence. Desktop socket recovery instructions apply only to that historical producer, not current Cloud onboarding. For current API key connection and authentication errors, use the Coding agent API setup guide and live endpoint tool discovery.
Response model
Section titled “Response model”MCP tools/call failures return tool-level results with isError and structured error:{code,message,...details}; these are distinct from JSON-RPC transport/protocol errors. The desktop helper separately returns JSON-RPC -32000 with data.code: E_APP_NOT_RUNNING for an unavailable app or JSON-RPC -32603 when HTTP has no body. Success commonly includes structured content and text content. There is no official per-tool output JSON Schema: consult each tool's documented source-grounded result contract, and treat optional fields as conditional. The compact response budget is 16,384 bytes.
Exact operational codes
Section titled “Exact operational codes”| Code | Meaning and action |
|---|---|
E_ARGUMENT |
Invalid/missing input, unknown key, selector conflict, or invalid cursor/limit. Correct the request; do not retry unchanged invalid input. |
E_PATH |
Path is outside an allowed local folder/mount. Use the exact mount key from gram_projects; never substitute its display name. |
E_READ_ONLY |
Approval or mount is read-only. Reads may continue; a write requires an already-authorized writable scope. |
STALE_READ |
Document moved during historical read. Read again at current state. |
STALE_CURSOR |
Cursor is bound to another document/revision/section. Get a fresh page/read cursor. |
E_CURSOR |
Cursor malformed. Obtain a replacement from the corresponding listing/read. |
E_REQUEST_REUSE |
The same ID is bound to a different intent. Do not retry the changed request under that ID; retry the original exact intent only to replay it, or use a new ID for a new intent. |
COMMIT_UNKNOWN |
Replacement was published but durability is uncertain. Retry only the identical patch with the same request ID; inspect persisted state before claiming success. |
STORAGE_CONFLICT |
Cloud provider state conflicted. Re-read persisted state before composing a new write. |
PROVIDER_AUTH_REQUIRED |
Provider authorization is needed. No successful remote write is implied. |
E_STORAGE |
Storage commit failed. Inspect receipt and sync status, then re-read before retrying. |
E_INTEGRITY |
History sequence/hash audit failed. Core rejects writes to corrupt history; do not repair by editing the trailer. |
E_MIGRATION |
Legacy data cannot be converted by the requested path. Preserve source and use the supported migration contract. |
Other source-defined errors include E_CORE_UNAVAILABLE, E_TIMEOUT, E_CORE, E_INTERNAL, E_UNKNOWN_TOOL, E_CONTEXT_BUDGET, E_TOO_MANY_DOCUMENTS, E_TIME_NOT_RECORDED and E_REQUEST_ID. Read the returned code/details; codes are not interchangeable.
Safe CAS sequence
Section titled “Safe CAS sequence”- Read current document identity
{path,rev,hash}. - Prepare one intended patch with that revision/hash, a unique 1–128-character request ID, and nonempty operations.
- The public tools expose no receipt tool. For an uncertain
gram_patch, resend the exact same request_id and unchanged path, base_revision, expected_hash, and operations; Core replays the original receipt. - If Core reports stale/CAS conflict, reread and rebase the human intent on the new content; send a new request ID.
- On mounted cloud writes, verify returned
sync.state: synced; successful MCP completion alone is not the remote persistence check.
A request_id binds canonical intent, including document ID, operation, base_revision, expected_hash, operations, effective_at, and context. An A-to-B-to-A reversal has a different CAS base and is a different intent, so reusing the first ID returns E_REQUEST_REUSE.
Create and retry boundaries
Section titled “Create and retry boundaries”gram_create has no request_id. If its response is uncertain, read the target path before further action. Creating at an existing path returns STALE_REVISION with Create target already exists; do not treat it as a patch or overwrite.
Only retry gram_patch by resending the exact same request_id and complete intent. The public MCP API has no standalone receipt tool. The shortened displayed hash maps to a full artifact hash held by the caller's gateway; if a short hash is no longer resolvable, reread rather than guessing.
Local/cloud boundary
Section titled “Local/cloud boundary”Local document tools require the app's approved vault scope; profile and capabilities are available without document approval. Read-only approvals reject create/patch. Cloud tools open a caller-scoped workspace, use exact mount paths, and commit back to the provider. Cloud capability reports semantic search unavailable and auto uses lexical fallback; local semantic behavior is runtime-probed. Local mount sync may be pending; cloud successful writes report synced. No tool bypasses the caller's existing authority.
Exact source-backed error messages
Section titled “Exact source-backed error messages”| Surface | Code | Actual message | Sources |
|---|---|---|---|
| MCP tool result | E_ARGUMENT |
Unknown argument |
thegram-vault/internal/mcp/gateway.go#335359731a3724bb0bf7a02093e3d7e1bbd93ccda3bbdff143b6178eec98a436 |
| MCP tool result | E_CURSOR |
Invalid list cursor |
thegram-vault/internal/mcp/tools_common.go#f243590ff0ab46a241c752ae104c538e5064c869525209dfc7219572d6d5523c |
| MCP tool result | E_CURSOR |
Invalid section cursor |
thegram-vault/internal/mcp/memory.go#cf97b451501c97d5db3c43836171a65ce221b9105d1b3c75ae58ccefc93e72e1 |
| MCP tool result | E_CURSOR |
Invalid changes cursor |
thegram-vault/internal/mcp/memory.go#cf97b451501c97d5db3c43836171a65ce221b9105d1b3c75ae58ccefc93e72e1 |
| MCP tool result | E_CURSOR |
Invalid context cursor |
thegram-vault/internal/mcp/tools_entity.go#04d41ed2634d5904fa812be53c92c70a06403d78334890b9791c168b8f89c9f0 |
| MCP tool result | E_CURSOR |
Invalid state cursor |
thegram-vault/internal/mcp/tools_history.go#c2d2b98e94a1cebbc9aadae0e931500c109b61fe44e90ad2f9e1bc6b76e499c8 |
| desktop JSON-RPC -32000 | E_APP_NOT_RUNNING |
Thegram is not running. Open the Thegram app, then retry. |
thegram-desktop/Helper/ThegramMCP.swift#87b7fdb6a576da59e84d86ae32624e452f5da7e3c4138b6f539374437556e6dd |
| desktop JSON-RPC | JSON-RPC -32603 |
Thegram answered HTTP \(response.status) with no body |
thegram-desktop/Helper/ThegramMCP.swift#87b7fdb6a576da59e84d86ae32624e452f5da7e3c4138b6f539374437556e6dd |
| MCP tool result | STALE_READ |
The document changed while it was read; read again |
thegram-vault/internal/mcp/tools_common.go#f243590ff0ab46a241c752ae104c538e5064c869525209dfc7219572d6d5523c |
| MCP tool result | STALE_READ |
The document was replaced while it was read |
thegram-vault/internal/mcp/tools_history.go#c2d2b98e94a1cebbc9aadae0e931500c109b61fe44e90ad2f9e1bc6b76e499c8 |
| MCP tool result | STALE_CURSOR |
The documents changed since this cursor; list again |
thegram-vault/internal/mcp/tools_common.go#f243590ff0ab46a241c752ae104c538e5064c869525209dfc7219572d6d5523c |
| MCP tool result | STALE_CURSOR |
The documents changed since this cursor; ask again without cursor |
thegram-vault/internal/mcp/memory.go#cf97b451501c97d5db3c43836171a65ce221b9105d1b3c75ae58ccefc93e72e1 |
| MCP tool result | STALE_CURSOR |
Cursor belongs to another document or revision |
thegram-vault/internal/mcp/tools_history.go#c2d2b98e94a1cebbc9aadae0e931500c109b61fe44e90ad2f9e1bc6b76e499c8 |
| MCP tool result | STALE_CURSOR |
The cursor belongs to another document, revision or section |
thegram-vault/internal/mcp/memory.go#cf97b451501c97d5db3c43836171a65ce221b9105d1b3c75ae58ccefc93e72e1 |
| MCP tool result | E_REQUEST_REUSE |
request_id belongs to another intent |
thegram-format/native/api.rs#a7e13ec4b422ae4907c7d7eac481267103f9b4b86248e706a82251cc597a5e02 |
| MCP tool result | E_REQUEST_ID |
Nonempty request_id required |
thegram-format/native/api.rs#a7e13ec4b422ae4907c7d7eac481267103f9b4b86248e706a82251cc597a5e02 |
| MCP tool result | E_CAS_REQUIRED |
base_revision required |
thegram-format/native/api.rs#a7e13ec4b422ae4907c7d7eac481267103f9b4b86248e706a82251cc597a5e02 |
| MCP tool result | E_CAS_REQUIRED |
Create requires explicit null base_revision |
thegram-format/native/api.rs#a7e13ec4b422ae4907c7d7eac481267103f9b4b86248e706a82251cc597a5e02 |
| MCP tool result | STALE_REVISION |
Accepted revision or hash changed |
thegram-format/native/temporal.rs#a143cc67c4518c4599f96af9565ae765c1dcdc770d694b13a8fdc08a03c69c0e |
| Core import-source CAS | STALE_REVISION |
Accepted revision or hash changed; preserve both originals |
thegram-format/native/temporal.rs#a143cc67c4518c4599f96af9565ae765c1dcdc770d694b13a8fdc08a03c69c0e |
| MCP tool result | STALE_REVISION |
Artifact changed during transaction |
thegram-format/native/store.rs#3bd54253eeee764c2cdf1d3dc1e9c0f4f1d9f96fbd75c66171d96b19a342addc |
| MCP tool result | STALE_REVISION |
Create target already exists |
thegram-format/native/store.rs#3bd54253eeee764c2cdf1d3dc1e9c0f4f1d9f96fbd75c66171d96b19a342addc |
| MCP tool result | COMMIT_UNKNOWN |
Replacement published but durability is uncertain: {e} |
thegram-format/native/store.rs#3bd54253eeee764c2cdf1d3dc1e9c0f4f1d9f96fbd75c66171d96b19a342addc |
| MCP tool result | COMMIT_UNKNOWN |
Marker observed but durability not confirmed: {e} |
thegram-format/native/store.rs#3bd54253eeee764c2cdf1d3dc1e9c0f4f1d9f96fbd75c66171d96b19a342addc |
| MCP tool result | STORAGE_CONFLICT |
remote file changed since it was read |
thegram-vault/internal/mcp/workspace.go#3f383dbf85678f084aa1b5c039c72b75188c966c963d6ca534b24450fd2cc826 |
| MCP tool result | STORAGE_CONFLICT |
remote file changed and local restoration failed |
thegram-vault/internal/mcp/workspace.go#3f383dbf85678f084aa1b5c039c72b75188c966c963d6ca534b24450fd2cc826 |
| MCP tool result | E_STORAGE |
workspace storage is not configured |
thegram-vault/internal/mcp/workspace.go#3f383dbf85678f084aa1b5c039c72b75188c966c963d6ca534b24450fd2cc826 |
| MCP tool result | PROVIDER_AUTH_REQUIRED |
Google Drive must be reconnected |
thegram-vault/internal/mcp/workspace.go#3f383dbf85678f084aa1b5c039c72b75188c966c963d6ca534b24450fd2cc826 |
| MCP tool result | E_PATH |
Absolute paths are outside the approved folder |
thegram-vault/internal/mcp/paths.go#754797578ba9858e6db8707f17ca9ceed82914215e83e00e437a05e925bff936 |
| MCP tool result | E_PATH |
Path does not start with a mounted collection |
thegram-vault/internal/mcp/paths.go#754797578ba9858e6db8707f17ca9ceed82914215e83e00e437a05e925bff936 |
| MCP tool result | E_PATH |
Path is outside the approved folders |
thegram-vault/internal/mcp/paths.go#754797578ba9858e6db8707f17ca9ceed82914215e83e00e437a05e925bff936 |
| MCP tool result | E_PATH |
Path is outside an approved folder or hidden |
thegram-vault/internal/mcp/paths.go#754797578ba9858e6db8707f17ca9ceed82914215e83e00e437a05e925bff936 |
| MCP tool result | E_PATH |
Vault mounts support writes only to top-level documents |
thegram-vault/internal/mcp/paths.go#754797578ba9858e6db8707f17ca9ceed82914215e83e00e437a05e925bff936 |
| MCP tool result | E_READ_ONLY |
This mounted folder is read-only to agents |
thegram-vault/internal/mcp/paths.go#754797578ba9858e6db8707f17ca9ceed82914215e83e00e437a05e925bff936 |
Source
Section titled “Source”Source: .gram language specification
Reference: https://github.com/clab-one/thegram-format/blob/main/spec/language.md
Source: Current rich document specification
Reference: https://github.com/clab-one/thegram-format/blob/main/spec/rich-document.md
Source: Current History/6 specification
Reference: https://github.com/clab-one/thegram-format/blob/main/spec/source-history-render.md
Source and renderer evidence
- Canonical source SHA-256
45a707bff1690ed1aa1c1794f5be92831ad5428b82874117afdd19a45f822a86- Selected revision
r7 · sha256:fffc35266b4f8a9452117465b7f2e77359ff72dbf38a390bc7ec21c9e1710e87- Local renderer
configured local Thegram renderer · API thegram-web-render/1- Core source
git+https://github.com/clab-one/thegram-format.git?rev=b16489e1d0d77d38f82d2f61776524737aa31557#b16489e1d0d77d38f82d2f61776524737aa31557
Canonical source: mcp-errors.gram