Connect an agent

Connect your agent to Bog, approve access with GitHub, and give your project a place to store data. Your personal workspace is created automatically; no repository access is requested.

GitHub sign-in, approval and the console use cloud.bog.new. The MCP address is mcp.bog.new/mcp; its discovery document directs clients to cloud.bog.new for authorization. Existing Fly-address connections remain supported. Follow the advertised authorization server rather than assuming it shares the MCP hostname.

One address for your client

https://mcp.bog.new/mcp

Use a remote HTTP MCP connection with OAuth. Approve bog:write to create Bogs and write records, or bog:read to inspect existing data. Write includes read access. Your client handles the credentials privately.

Codex CLI

Tested with Codex CLI 0.154.0: GitHub-backed approval, workspace discovery, creation and retry, record write/read, and change waiting. This temporary configuration leaves your saved server settings alone:

codex -c 'mcp_servers.bog_journey.url="https://mcp.bog.new/mcp"' mcp login bog_journey --scopes bog:write
codex -c 'mcp_servers.bog_journey.url="https://mcp.bog.new/mcp"'

Follow the browser approval, then use Bog's tools in the new client session. Existing GitHub sign-in may let you proceed directly to Bog's approval screen.

Claude Code

Tested with Claude Code 2.1.274 through the same approval and record workflow. In your project directory:

claude mcp add-json --scope local bog_journey '{"type":"http","url":"https://mcp.bog.new/mcp","oauth":{"scopes":"bog:write"}}'
claude mcp login bog_journey
claude

Approve the browser request, then ask Claude to use Bog. Both tested clients keep their connection credentials privately.

Your first useful request

Find my personal workspace and its allowance. Create a Bog for a reading list, save Dune with its reading status, and read it back. Use the same creation key if you retry. Keep credentials out of this conversation.

Choose a shared workspace explicitly. Agents can create Bogs and operate on shared records, but cannot manage membership or delete Bogs.

Install app access privately

Ask your agent to use prepare_app_access with the Bog ID, read/write scope and an app label. It returns a ten-minute nonsecret handoff reference, safe in tool results or conversation; the reference alone grants no access. An authorized agent may run the helper using its own authorization cache. Download the Python helper, inspect it, then run:

python3 bog-app-access.py --origin https://cloud.bog.new --handoff HANDOFF_ID --output ./bog-private.json

The helper saves a private JSON file with mode 600. It uses only its own authorization cache; it never extracts Codex or Claude credentials. If it has no authorization, the human must explicitly approve its separate device request. Alternatively, open the returned console link while signed in and explicitly download the configuration there. Both installation paths write the same JSON fields: BOG_CLOUD_URL (service origin), BOG_ID (Bog ID), BOG_CLOUD_TOKEN (private bearer credential), and credential_id (revocation reference). Load these exact, case-sensitive keys privately at app startup; never print the token or file contents. Keep either file outside source control and transcripts. Browser downloads may need their file permissions restricted after download.

Only the initiating account can redeem a handoff. It expires after ten minutes or a server restart and works once. If delivery fails after redemption, revoke the listed credential as a workspace owner, or ask an owner to revoke it, then prepare another handoff. The installed credential is restricted to its Bog and survives app restarts.

Reconnect or remove access

Connections expire after 30 days. Reconnect and approve again after expiry; refresh tokens are not supported. If access was revoked, reconnect only if you want to grant access again. A permission upgrade cannot restore removed workspace membership.

Revoke a connection under Agents in the console. Give deployed applications a credential for one Bog, rather than your agent's account access. Never paste a token into a prompt or URL.

Protocol and discovery

The tested protocol baseline is MCP 2025-11-25 over Streamable HTTP. We do not advertise the newer 2026-07-28 protocol. Requests authenticate independently; session IDs are not used. Schema and capability changes in the newer specification require a separate compatibility review.

MCP resource metadata · Authorization metadata · HTTP and authentication guide · API documentation