# 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](/docs/agents/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](/docs/reference/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](/docs/agents/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.