MCP server
The GuideMark MCP server's endpoint, sign-in, and every tool.
Endpoint: https://guidemark.co/api/mcp, Streamable HTTP in its stateless form: one JSON-RPC message per POST, JSON responses, no SSE stream or session. Supported protocol versions: 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05.
Authentication: sign in with GuideMark (OAuth 2.1, see Connect) or an API key header. An unauthenticated request answers 401 with WWW-Authenticate: Bearer resource_metadata="https://guidemark.co/.well-known/oauth-protected-resource", which is how clients discover sign-in.
The server sends the model short instructions on connect: start with get_project, install the widget with get_install_snippet if it has never loaded, prefer stable selectors, create drafts, and call request_review once per finished draft.
Capabilities: tools, prompts and resources. Nothing is pushed, so there are no list-changed notifications or resource subscriptions. After initialize, send the negotiated version in the MCP-Protocol-Version header; an unsupported version answers 400, and a request without the header is treated as 2025-03-26.
Tools
The tools take the same fields as the REST API and follow the same permission rules. Refusals come back as tool results with isError: true and a sentence the model can pass on.
| Tool | Does |
|---|---|
get_project | Domain, publish policy, and whether this connection can publish |
get_install_snippet | The script tag for this project, where to put it in Next.js (App Router), React (Vite), Vue and plain HTML, and widget.lastSeenAt (null until a page with the snippet has loaded) |
list_tours | Every tour, drafts included, without steps |
get_tour | One tour with its steps (tourId) |
create_tour | Create a tour with all its steps (title, pageUrl, steps, optional publish) |
update_tour | Replace title, page and every step (tourId, title, pageUrl, steps) |
delete_tour | Delete a tour (tourId) |
set_tour_published | Put live or back to draft (tourId, published) |
list_beacons | Every beacon tooltip, drafts included |
create_beacon | Create a tooltip (title, content, targetSelector, optional pageUrl, trigger, delivery, publish) |
update_beacon | Change fields (beaconId, then any tooltip fields) |
delete_beacon | Delete (beaconId) |
set_beacon_published | Put live or back to draft (beaconId, published) |
request_review | Email the owner to review a finished draft (exactly one of tourId, beaconId) |
Structured results
From protocol version 2025-06-18, every tool lists an outputSchema and a successful call returns its result as structuredContent too. The same JSON is always in the text content, so older clients and protocol versions get the text alone. Errors are text only.
Prompts
Prompts are workflows you pick in your client, often as slash commands. Each walks the agent through the tools in order: read the project, check the widget is installed, read your code for stable selectors, create a draft, request a review.
| Prompt | Arguments | Does |
|---|---|---|
create_onboarding_tour | page (a path like /pricing), optional goal | A three-to-five-step draft tour for the page |
add_tooltips | page, optional elements | Draft beacon tooltips on the controls that need explaining |
install_widget | none | Adds the script tag to your codebase in the right place for its framework |
Resources
Every page of these docs is a resource, as Markdown (text/markdown), the same text as /docs/<page>.md. URIs follow the docs paths: guidemark://docs is the docs home and guidemark://docs/agents/connect is Connect. resources/list lists them all; an unknown URI answers -32002. Reading them still needs a signed-in connection or key.
Discovery documents
https://guidemark.co/.well-known/oauth-protected-resource(also at/.well-known/oauth-protected-resource/api/mcp)https://guidemark.co/.well-known/oauth-authorization-server
Clients register themselves at /api/oauth/register. PKCE S256 is required. Access tokens last an hour; refresh tokens rotate on every use and last 90 days.