---
title: Connect Coding Agents to Thegram with an API Key · r14
description: One Cloud MCP plugin for Claude Code, Codex, OpenCode and OMP, using a privately entered scoped API key instead of a desktop app. Archived revision r14 (2026-10-16) of /guides/local-setup/.
url: https://docs.thegram.one/guides/local-setup/revisions/14/
lang: en
tier: legacy
source: https://docs.thegram.one/sources/local-setup/revisions/14.gram
revision_of: https://docs.thegram.one/guides/local-setup/
revision: 14
date_published: "2026-10-16T01:26:30.010Z"
evidence:
  Canonical source SHA-256: 66c7a825c24ce4cc25fac497fd4bf326e95e0771ae237ebf3b330dc7a713df11
  Selected revision: r14 · sha256:8aa7b9b295477e5e1fc72f8cdc0e83550337d879f7b76ef89b8d7ef92abaca4c
  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
---

# Connect Coding Agents to Thegram with an API Key · r14

> Archived revision r14, recorded 2026-10-16T01:26:30.010Z by portal-product-quickstarts. Current page: [Connect Coding Agents to Thegram with an API Key](/guides/local-setup/).

<div class="gram-doc-anchor" id="e0-d_127b30e9a5c64e2aa472db36e7214a3d"></div>

## Connect coding agents with an API key {#h0-1}

Claude Code, Codex, OpenCode and OMP use the same coding plugin and Cloud MCP endpoint. No desktop app, DMG, Agent Access switch or local socket is required.

### Prerequisites {#h0-3}

- Node.js 22+ on PATH and coding plugin 3.0.0 or later.
- A Thegram account and explicit access to the intended Cloud vault or connected Drive account.
- A person-issued API key with only the required resource scopes. Provider install and hook trust prompts remain the person’s decision.

### Install the shared plugin {#h0-5}

Run only the canonical block for the selected host. Each block installs the same public clab-one/thegram-mcp package; it does not create a separate desktop connection.

Claude Code:

```sh
claude mcp remove --scope user thegram >/dev/null 2>&1 || true
claude plugin marketplace add clab-one/thegram-mcp || claude plugin marketplace update thegram-memory
claude plugin install thegram-memory@thegram-memory
claude plugin update thegram-memory@thegram-memory || true
```

Codex:

```sh
codex mcp remove thegram >/dev/null 2>&1 || true
codex plugin remove thegram@thegram-local >/dev/null 2>&1 || true
codex features enable hooks
codex plugin marketplace add clab-one/thegram-mcp || codex plugin marketplace upgrade
codex plugin add thegram-memory@thegram-memory
```

OpenCode:

```sh
opencode plugin add github:clab-one/thegram-mcp
```

OMP:

```sh
omp plugin marketplace add clab-one/thegram-mcp || true
omp plugin install thegram-memory@thegram-memory
omp plugin upgrade thegram-memory || true
```

### Issue and connect an API key {#h0-15}

1. Sign in at https://vault.thegram.one/v3/ and open Settings → Agents → API keys.
2. Give the key a name, select only the required vaults and Drive accounts, choose read or write access where offered, and set an expiry no more than 90 days away.
3. Copy the one-time secret. Do not paste it into a chat, source file, command argument or shell history.
4. From the installed coding plugin directory, run the command below and enter the key at its hidden prompt. If more than one vault is authorized, follow the canonical guide to choose the exact mount.

```sh
node dist/thegram-memory.mjs connect
node dist/thegram-memory.mjs doctor
```

The CLI stores the connection privately; on POSIX the credential file is mode 0600. The saved key is bound to its endpoint. Start a new agent session after connecting. Connecting and doctor do not create a memory document.

### Project memory and storage {#h0-19}

All current agent connections use Thegram Cloud. Local-only files are not uploaded or exposed automatically. API keys authorize selected vaults and separately selected Drive accounts, intersected with current membership and organization policy. A vault grant is not a document-only sandbox.

Each repository uses its configured Cloud memory document, shared by worktrees. With write access the first agent session can initialize an empty project memory; read-only sessions do not create or modify it. Existing local-only memories require an explicit user-directed migration.

### Verify without writing {#h0-22}

```js
gram_capabilities({})
gram_projects({})
gram_brief({ "folder": "<project folder or mount key returned by gram_projects>" })
gram_read({ "path": "<exact document path in gram_brief docs>" })
gram_read({ "path": "<same document path>", "section": "<heading returned by gram_read outline>" })
```

Expected: the selected authorized mount is visible. Read an existing document if one is listed; an empty vault is not a connection failure.

### Troubleshooting {#h0-25}

- E_AUTH before any request: no local API key is configured. Run connect and enter a person-issued key privately; redeploying the UI does not enroll a local CLI.
- HTTP 401: the key is invalid, expired or revoked. Issue a replacement in Settings and reconnect; do not reuse another person’s key.
- E_FORBIDDEN or AGENT_SCOPE_DENIED: inspect the key scopes, vault role and organization policy. A key cannot widen them.
- E_CONNECT or key_service_unavailable: check the configured endpoint and service readiness. Do not fall back to a desktop socket or a different storage location.
- To revoke server access, delete the key in Settings. CLI disconnect only removes the local credential.

### Optional first save and search {#h0-27}

Keep installation and the checks above read-only. Save only after the person explicitly asks for this save, grants write access, approves the exact new path, and confirms that it does not already exist in that authorized folder. Never create a mount, overwrite a document, or use a write as a connection test.

Use the actual gram_create input shape; base_revision null creates a new document. Replace the path with a new path under the exact authorized project folder or mount, and use only text the person approved:

```js
gram_create({
  "path": "<authorized-folder>/setup-notes.gram",
  "title": "Setup notes",
  "base_revision": null,
  "content": "# Setup notes"
})
```

Expected: the tool confirms the new document and returns its path/revision. Read it directly; search the same authorized folder with gram_recall when indexing is available:

```js
gram_read({ "path": "<exact path returned by gram_create>" })
gram_recall({
  "query": "setup notes",
  "folder": "<same authorized folder or mount key>",
  "top_k": 5
})
```

Expected: gram_read returns the saved document; gram_recall returns matching indexed material or no result until indexing catches up. Both retrieval calls are read-only.

Canonical installation and mount selection: https://thegram.one/install/agents.md