Connect an AI assistant

Copy the hosted MCP URL from Workspace settings → AI connections. The examples below use https://api.example.com/mcp as a placeholder: replace it with that exact URL, including /mcp. Do not copy a dashboard URL, SDK write key, or server API token into your assistant's configuration.

Before you connect

Your workspace must be enabled for MCP. Hosted OAuth, client compatibility, and approval behavior still require acceptance testing for each deployed environment. These instructions were checked against vendor documentation on September 8, 2026; client menus and organization policies can differ.

ChatGPT

On the web, enable Developer mode under Settings → Security and login. Open ChatGPT Plugins, use the plus control to create a developer-mode app, enter the MCP URL, and choose OAuth. Complete UserGist sign-in and consent, then select the app from the conversation's Developer mode tools. Availability is subject to your account and organization policy. Official ChatGPT instructions

ChatGPT's write-tool confirmations are separate from UserGist proposals. A confirmation can appear even for the first, preview-only call to a write tool. Remembering a client approval does not change the connection's UserGist execution mode.

Claude

For an individual account, open Customize → Connectors, choose Add custom connector, enter the MCP URL, and connect. For Team or Enterprise, an owner first adds the connector under organization settings; each member then authenticates individually. Enable the connector in the conversation. Claude's remote connector reaches your server from Anthropic's infrastructure, so a private localhost URL is not sufficient. Official Claude instructions

Claude Code

claude mcp add --transport http usergist https://api.example.com/mcp

In Claude Code, run /mcp, select UserGist, and complete OAuth sign-in. No local proxy or copied bearer token is needed. Existing client tool permissions remain in force. Official Claude Code instructions

Cursor

Merge this entry into your project .cursor/mcp.json, preserving any existing servers:

{
  "mcpServers": {
    "usergist": {
      "url": "https://api.example.com/mcp"
    }
  }
}

Enable UserGist in Cursor's MCP configuration and complete the OAuth connection. Review tool arguments when Cursor asks for approval. Do not add an Authorization header containing a UserGist server token. Official Cursor instructions

Codex

Add UserGist to the active Codex host and authenticate:

codex mcp add usergist --url https://api.example.com/mcp
codex mcp login usergist

Use /mcp in Codex to check the connection. For manual configuration, merge this table into the host's existing config.toml:

[mcp_servers.usergist]
url = "https://api.example.com/mcp"

Keep the host's existing approval policy. CLI and IDE clients on the same Codex host share MCP configuration; registering a server locally does not establish hosted ChatGPT compatibility. Official Codex instructions

Choose one workspace, confirm the selected apps, and give the connection a recognizable name. Read capabilities and common authoring capabilities start selected; publication, push sending, integrations, and administrative changes require explicit opt-in. Your current workspace role remains the ceiling.

Keep Approve changes for an interactive workflow. After the one-time browser sign-in, product work and approvals stay in the AI conversation. Native forms are used only when supported by the negotiated client capabilities; otherwise the client must request confirmation before executing a proposal. UserGist cannot independently verify a human confirmed the fallback flow.

Verify the connection without changing content

Ask:

Use UserGist to call get_context and list_apps. Tell me which workspace, apps, capabilities, and execution mode this connection has. Do not change anything.

Then choose an app explicitly and read an existing request or experience. If a tool is missing, check grants, your workspace role, rollout flags, and the client's own tool settings. Refresh the client's tool discovery after changing permissions.

Troubleshooting

Symptom	What to check
AI connections is not enabled	The workspace has not entered the rollout, or the server flag is disabled.
OAuth succeeds but MCP returns unauthorized	Ask the operator to verify the exact resource audience, Connect issuer, and consent binding. Do not substitute a dashboard token.
The authorization link expired	Start a new connection from the AI client; do not reuse the old consent URL.
Reads work but a change is unavailable	Check read-only mode, manage/publish/send grants, your current role, and the server write flag.
A live edit needs another capability	Active experience edits require publication privilege; active or scheduled push edits require sending privilege.
A call times out	Read `get_operation` if an operation ID was returned. Never use a new idempotency key merely to resend an uncertain action.
A client cannot reach the server	Use the hosted HTTPS endpoint and check network policy and allowed origins with the operator. Do not weaken OAuth or allow every origin.

Manage or revoke your connection in AI connections. Owners and admins can revoke workspace connections, but cannot expand another member's grants. See permissions and approvals for revocation effects and safe retries.