# Connect a cloud agent to Thegram

For agents that run on a vendor's servers: Meta Muse, OpenAI dots, xAI Grok and agents built on Cloudflare. They reach the same Thegram Cloud memory as ChatGPT, Claude and coding agents through the remote MCP server `https://vault.thegram.one/mcp` (Streamable HTTP). Nothing is installed on the person's computer. Google CC is not supported yet; its connection guide is coming soon.

Thegram API keys are sent only as `Authorization: Bearer <key>`. OAuth uses published client ID metadata documents or the pre-registered public client shown below for Grok; dynamic client registration is not offered.

You are the agent. Do the steps you can do yourself. Ask the person only for sign-in, permission choices and secret entry. Never ask them to paste an API key into a chat, and never echo, log or store a key outside your platform's secure credential store.

## Muse (Custom Connector + API key)

Official guide: https://www.meta.com/help/artificial-intelligence/1687253048996149/ (How Muse works with Connectors). Meta does not review custom connectors.

1. Ask the person to open https://vault.thegram.one/, go to **Settings → Agents → API keys** and create a key named `Muse`. They select only the vaults Muse needs: **Read**, or **Read and write** if Muse should record memory. The secret is shown once. A key cannot be edited later; a different scope needs a new key.
2. Create a Custom Connector for Thegram:
   - Server: remote MCP, Streamable HTTP, `https://vault.thegram.one/mcp`
   - Authentication: API key sent on every request as `Authorization: Bearer <key>`
   - Send the key only to `vault.thegram.one`. Do not follow redirects with it.
3. Collect the key through the Secure Credentials Store prompt, never in the conversation.
4. Verify with `gram_projects` (empty arguments): it lists the accessible mounts. Report the vault names and access level to the person. Do not create test documents to prove the connection.

Errors: HTTP 401 means the key is missing, malformed (no `Bearer ` prefix), expired or revoked; the person issues a replacement. Access denied or a missing vault means the key's scope does not include it; the person issues a new key with that scope and revokes the old one. To disconnect, the person removes the connector in Muse **Settings → Connectors** and revokes the key in Thegram Settings → Agents; removing the connector alone does not revoke the key.

## dots (Thegram ChatGPT plugin + OAuth)

Official guide: https://help.openai.com/en/articles/20001530-getting-started-with-your-dot (Getting started with your dot).

A dot uses the plugins connected to the person's ChatGPT account. ChatGPT plugins do not accept API keys; do not request a Thegram API key for a dot.

1. The person installs the official Thegram plugin: https://chatgpt.com/plugins/plugin_asdk_app_6acc810ccabc8191acd3f457dc498d43, selects **Install plugin**, signs in to Thegram and approves the intended vaults.
2. In the dot's profile, the person opens **Customize → Plugins**, selects Thegram, reviews its permissions and connects it.
3. Verify with `gram_projects`, then answer "What does Thegram remember about my projects?" from `gram_brief`.
4. Document chat: when the person asks you to handle their Thegram document chat, subscribe to the MCP event `chat.task.created` (no arguments). For each event call `chat_task_get {task_id}`, read with `chat_doc_read`, and finish with one `chat_task_submit {task_id, reply, operations?}`. These tools take no path; a request may change only the document it came from. The person sees the subscription in Thegram Settings → Document chat.

If Thegram is not listed, the plugin must be installed and connected to the same ChatGPT account and workspace as the dot; OpenAI notes that the apps available to a dot may differ. Per-vault access for ChatGPT is set in Thegram Settings → Agents.

## Grok (custom MCP connector + OAuth)

Official guides: https://docs.x.ai/grok/connectors and https://docs.x.ai/grok/connectors/custom-mcp-tunneling. Grok web connector setup uses OAuth; its form does not offer API-key or custom-header authentication.

OAuth scopes are not vault permissions. The person manages Thegram Grok’s vault and Google Drive access in Thegram **Settings → Agents** and should enable only the data and actions they want Grok to use.

1. The person opens https://grok.com/connectors, selects **New Connector → Custom**, names it `Thegram`, and enters server URL `https://vault.thegram.one/mcp`. On Grok Business or Enterprise, a team admin first adds it at https://console.x.ai/ under **Grok Business → Connectors → Add Connector → Other**.
2. Fill the OAuth form in this order:

   | Field | Value |
   |---|---|
   | Client ID | `p13ez96egczgttbo5s090` |
   | Client secret | Leave empty |
   | Authorization endpoint | `https://auth.thegram.one/oidc/auth` |
   | Token endpoint | `https://auth.thegram.one/oidc/token` |
   | Scopes | Remove `profile` and `email`; keep only `openid` and `offline_access` |
   | Token auth method | None (PKCE only, recommended) |

   The client ID is public, not an API key or secret. No separate app registration is needed. Do not enter `Grok` or an API key as the client ID.
3. Click **Save and connect**, sign in to the person's own Thegram account, then click **Authorize**. Back in Grok, Thegram should appear under **Connected** with its tools listed.
4. For other vaults or Google Drive, the person opens Thegram **Settings → Agents → Thegram Grok** and selects the access to allow. Do not broaden it automatically.

OAuth connection and `tools/list` discovery were verified. Data tool calls and token refresh have not yet been verified.

### Separate route: xAI API remote MCP

xAI API backends use a scoped Thegram API key, not the Grok web OAuth flow. The person creates it in Thegram **Settings → Agents → API keys**, selects the required vaults and starts with **Read**. See https://docs.x.ai/developers/tools/remote-mcp; add this to `POST https://api.x.ai/v1/responses`:

```json
{"type": "mcp", "server_url": "https://vault.thegram.one/mcp", "server_label": "thegram", "allowed_tools": ["gram_projects", "gram_brief", "gram_read", "gram_recall", "gram_context"], "authorization": "<THEGRAM_API_KEY>"}
```

The xAI Python SDK helper is `xai_sdk.tools.mcp(...)` with `allowed_tool_names` and `extra_headers`. If a valid key is rejected with HTTP 401, send `"headers": {"Authorization": "Bearer <THEGRAM_API_KEY>"}` instead of `authorization`. Keep both API keys in server-side environment variables.

To disconnect the Grok web connector, the person removes it in Grok and disconnects **Thegram Grok** in Thegram Settings → Agents.

## Cloudflare (Agents SDK or MCP server portal + API key)

Agents SDK (https://developers.cloudflare.com/agents/model-context-protocol/apis/client-api/):

1. Store a Thegram API key as a Worker secret: `npx wrangler secret put THEGRAM_API_KEY`. Never put it in source or `wrangler` configuration.
2. Connect:

```ts
await this.addMcpServer("thegram", "https://vault.thegram.one/mcp", {
  transport: {
    headers: { Authorization: `Bearer ${this.env.THEGRAM_API_KEY}` },
  },
});
```

3. Pass `this.mcp.getAITools()` to the model. `addMcpServer` returns `ready` when tools are discovered; `authenticating` means the header did not arrive and Thegram offered OAuth.

MCP server portal (https://developers.cloudflare.com/cloudflare-one/access-controls/ai-controls/mcp-portals/): the dashboard form uses OAuth dynamic client registration, which Thegram does not offer. Create the server with the API instead: `POST https://api.cloudflare.com/client/v4/accounts/{account_id}/access/ai-controls/mcp/servers` with `{"name": "Thegram", "hostname": "https://vault.thegram.one/mcp", "auth_type": "bearer", "auth_credentials": "<THEGRAM_API_KEY>"}`. The portal sends it as `Authorization: Bearer <key>`. Every user the portal admits shares that key, so scope it narrowly and prefer read access.

## Recording memory

Record only durable outcomes the person asked for or authorized: decisions, events, tasks, risks and measured values. Read the target document with `gram_brief` before a write. A write succeeded only when the response's `sync.state` is `synced`.

Help: support@thegram.one · Human guide: https://thegram.one/install/#muse, https://thegram.one/install/#dot, https://thegram.one/install/#grok and https://thegram.one/install/#cloudflare