AI assistants (MCP)

Guidely runs a Model Context Protocol server, so AI assistants such as Claude, ChatGPT, Cursor, VS Code and Claude Code can work with your Guidely data. Ask things like:

• "Which guides have the worst completion rate this month, and where do people drop off?"
• "What are users asking Scout about most this week, and which questions does it fail to answer?"
• "Summarise the open errors on the checkout page and find a replay of one."
• "Draft a help article about exporting invoices from this how-to."
• "Create a three-step tour for new admins on the invoices page, and publish it to staging."
• "Is new-billing on in production? Turn it on in staging."

The assistant acts as you: it sees the workspaces and projects you can see, with your role and permissions, and nothing more.

Connect

The server URL is shown in Settings → AI assistants. On Guidely Cloud it is:

https://guidelytech.com/api/mcp

Most assistants sign in with OAuth: add the URL, and the assistant opens Guidely in your browser, where you sign in and choose what it may do. You don't copy any keys.

Claude's connectors reach the server from Anthropic's cloud, so they need a public https URL. To try a local Guidely from Claude Desktop, add it to claude_desktop_config.json (Settings → Developer → Edit Config) through the mcp-remote bridge, then restart Claude:

{ "mcpServers": { "guidely-local": { "command": "npx", "args": ["-y", "mcp-remote", "http://localhost:3000/api/mcp"] } } }

Personal access tokens

For assistants that only take a header, create a token in Settings → AI assistants → Create token and send it on every request:

{
  "mcpServers": {
    "guidely": {
      "url": "https://guidelytech.com/api/mcp",
      "headers": { "Authorization": "Bearer gly_pat_…" }
    }
  }
}

Tokens start with gly_pat_, are shown once, and can expire after 30, 90 or 365 days or last until you revoke them. Treat them like passwords.

Read only, or read and change

When you connect, you choose:

• Read only (the default): the assistant gets viewer access everywhere, whatever your role, and only sees the tools that read. Session replays still need the View session replays permission.
• Read and make changes: the assistant can also use the tools that change things, within your role and permissions. Changes show up in Guidely as yours, in audit logs and histories.

Writes are kept deliberately small: creating, editing and publishing guides, resolving errors, drafting and editing help articles (edits to a published article become unpublished changes for your team to review), and turning feature flags on or off (production needs Change production flags, and environments that require approval get a change waiting for review instead). Assistants can't publish articles, delete anything, reply to your users, or change settings, members or keys.

Creating guides

Describe the guide in the conversation and the assistant builds it in Guidely:

Create a tour on /invoices for admins: a welcome modal, then a tooltip on the Export button saying how to download a CSV.

• create_guide saves it as an unpublished draft: steps (text in Markdown), checklist tasks or survey questions, when it starts (trigger), which pages (urlPatterns), who sees it (visibility and targeting rules) and how often (frequency). It can start from a template (list_guide_templates).
• Tooltips, popovers, spotlights and hotspots point at an element by CSS selector, visible text or data-guidely-id. The assistant can find real selectors with get_page_detail, which lists the most-clicked elements on a page. Otherwise it leaves the step without an element and links you to the visual editor to pick one.
• The result says what still blocks publishing and links to the guide in the editor, where you can preview it.
• update_guide changes the draft. Steps passed with their existing id keep anything the assistant didn't change, such as an element you picked in the editor.
• publish_guide makes the draft live in one environment, and unpublish_guide takes it down. These, and the tools that edit existing guides, articles and errors, are marked destructive, so assistants such as Claude ask you before running them. The usual rules apply: Edit guides to create and edit, Publish to dev & staging to publish there, and publishing to production only for members allowed to.

Tools

\* Changes data; only offered to connections that may make changes.

Analytics tools default to the production environment and the last 30 days; ask for another environment or period and the assistant passes env, from and to. Results link back to the dashboard. Reading a conversation through an assistant doesn't mark it read for your team.

Managing access

• Your connections: Settings → AI assistants lists the apps you approved and the tokens you created, with when each was last used. Disconnect stops one immediately.
• Workspace switch: admins can turn off Allow AI assistants for a workspace in the same tab. No one's assistant can reach it while it's off; list_projects says why.
• Sign-in rules still apply: a connection carries how you signed in when you made it. A workspace that requires GitHub or Google sign-in, or two-step verification, admits the connection only if that session would have been admitted.
• Each connection may make 240 requests a minute.

For client developers

• Transport: Streamable HTTP at POST /api/mcp, stateless, JSON responses (no SSE stream; GET returns 405). Protocol versions 2025-11-25, 2025-06-18, 2025-03-26 and 2024-11-05. Capabilities: tools.
• Authorization: OAuth 2.1 with PKCE (S256 only) and public clients.
  • A request without a valid token gets 401 with WWW-Authenticate: Bearer resource_metadata="<base>/.well-known/oauth-protected-resource/api/mcp".
  • Metadata: /.well-known/oauth-protected-resource (RFC 9728) and /.well-known/oauth-authorization-server (RFC 8414).
  • Dynamic client registration at POST /api/oauth/register (RFC 7591). Redirect URIs must be https, loopback http (any port), or an app's own scheme.
  • Authorization at /oauth/authorize; tokens at POST /api/oauth/token (authorization_code and refresh_token grants); revocation at POST /api/oauth/revoke (RFC 7009).
  • Scopes: read, write. The user's choice on the consent screen decides.
  • Access tokens (gly_oat_…) last an hour. Refresh tokens (gly_ort_…) last 30 days and rotate on every use.