The Model Context Protocol (MCP) is an open standard that lets AI assistants and coding agents call tools provided by external servers. PageSugar runs a public MCP server so an agent can search the catalogue, inspect a component and retrieve its exact source for Svelte 5 and Tailwind CSS 4. Your coding agent integrates that source into your project. > [!TIP] > Setting up? The [MCP page](/mcp) has the steps for Claude Code, Codex, Cursor, VS Code and other clients, and a button that copies them as Markdown for your agent. This page is the reference. ## Endpoint ```text https://pagesugar.com/mcp ``` - **Transport:** Streamable HTTP. Requests are sent with `POST` to the single endpoint above. - **Access:** read-only catalogue data, intended for anonymous use. - The same URL serves two audiences. An MCP client sends `POST` requests and gets the protocol. A browser asking for HTML gets the [MCP page](/mcp) with setup steps. - A `GET` that asks for `text/event-stream` or JSON returns `405`. The server is stateless and offers no server-sent stream, as the transport allows. ## Client compatibility The [MCP page](/mcp) gives setup steps for each client. Those steps follow each client's own documentation and carry the date they were last checked against it. > [!IMPORTANT] > Following a client's documentation is not the same as testing that client against this server. Tested client versions and dates have not been published yet, and will be listed here when they are. In general, clients that support remote MCP servers over Streamable HTTP ask for a server URL. Use the endpoint above. Clients that only support local (stdio) servers can connect through a bridge such as `mcp-remote`. Clients that only support the older SSE transport cannot connect. ## What the server can do - List categories and browse published components with deterministic filters. - Search for components that match a natural-language description. - Return a component's versions, variants, props, usage, dependencies, services, license and integration limits. - Return the complete file manifest and, when it fits the response budget, the full text of every runtime file. - Return individual files, or explicit line ranges of large text files. - Return the ZIP bundle location, its checksum and the distribution receipt URL. ## What it cannot do - It does not modify your project, write files, run installers or execute code. Your agent applies changes locally, with your permissions. - It does not publish, edit or delete components, and it has no authoring or write operations. - It does not fetch arbitrary URLs, run shell commands or read anything outside published catalogue artifacts. - It does not include a language model. The agent you use does the reasoning. - It does not return draft components. ## Tools | Tool | Purpose | Returns source? | | --------------------- | ---------------------------------------------------------------------------------- | ----------------------- | | `list_categories` | Discover populated categories and the browsing taxonomy. | No | | `list_components` | Enumerate published components with filters, a sort and cursor pagination. | No | | `search_components` | Find best matches for a described need. | No | | `get_component` | Inspect one component's versions, variants, usage guide, dependencies and limits. | No full runtime files | | `get_component_files` | Get a release's complete file manifest and, when it fits, every runtime text file. | Optional complete text | | `get_component_file` | Read one file from the release manifest, or a stated line range of it. | Yes, one file or range | | `download_component` | Get the bundle URL, archive checksum, receipt URL and integration notes. | No, a download location | ### Limits and defaults | Setting | Value | | --------------------------- | ------------------------------ | | `list_components` page size | default 20, maximum 50 | | `search_components` results | default 8, maximum 20 | | Search query length | at most 500 characters | | Values per filter | at most 20 | | Source response budget | 128 KiB of application payload | ### Version and variant rules - `get_component` may omit `version` to inspect the current release. Every response states the exact version it resolved. - `get_component_files`, `get_component_file` and `download_component` require an exact `version`. - The current build serves only each component's current release. Older releases are not yet retained, so they return `VERSION_NOT_FOUND` once a newer release is published. - Artifact locations are content-addressed by `artifactDigest`. A receipt's `publishedInRevision` is currently the catalogue revision that produced the build, because release history is not yet retained. - `variantId` defaults to the release's default variant. The resolved id is always returned. An unknown variant is an error, never a substitution. ### What inspection and download return `get_component` includes the component's authored usage guide as `usageGuide` (Markdown, or `null` when the component has none) alongside the structured usage, props and customization data. When you pass a `version`, its `detailUrl` and `markdownUrl` keep that version. `download_component` returns locations, not bodies: the bundle URL with its size and SHA-256, and a `receiptUrl` you fetch to read the receipt. Its `markdownUrl` and `customizationUrl` keep the exact version and variant. ### Completeness `get_component_files` includes file contents by default. When all runtime text fits the budget the result says `contentStatus: "complete"`. When it does not, the result is the complete file manifest with `contentStatus: "manifest-only"` and a size warning, and the agent should fetch files individually or use the bundle. The server never returns a partial set of files described as complete. `get_component_file` reports `isPartial: false` for whole files. For a line range (`startLine` and `endLine`, inclusive and one-based) it reports `isPartial: true`, the total line count, and a checksum that is labelled as the full file's checksum. Binary files return metadata and download locations, not text. Search results are best matches and never exhaustive. Use `list_components` when you need every component that matches a filter. ## Errors Domain errors use the same codes as the [public API](/docs/api): | Code | Meaning | | ---------------------- | ------------------------------------------------------------------------------------------------ | | `INVALID_ARGUMENT` | An input is invalid. The error names the field and the accepted format or values. | | `NOT_FOUND` | No public component matches the identity. | | `VERSION_NOT_FOUND` | That release is not available. The latest release is never substituted. | | `UNKNOWN_VARIANT` | The variant does not exist for the release. Valid variant ids are included. | | `WITHDRAWN` | The release was withdrawn. A public reason and replacement guidance are included when available. | | `FILE_NOT_FOUND` | The path is not in the release's published file allowlist. | | `RESPONSE_TOO_LARGE` | The result exceeds the response budget. Size information and alternatives are included. | | `RATE_LIMITED` | Too many requests. Retry later, after the delay given when one is known. | | `SEARCH_UNAVAILABLE` | Search could not run and no fallback could answer. This is different from zero matches. | | `REVISION_EXPIRED` | A pagination cursor refers to a catalogue revision that is no longer retained. Restart browsing. | | `ARTIFACT_UNAVAILABLE` | A known artifact cannot be delivered right now. Different bytes are never returned instead. | ## Rate limits Rate limiting is not enforced yet. When it is introduced, limited requests will return `RATE_LIMITED` with retry guidance. Agents should still retry with backoff, avoid polling, and prefer the ZIP bundle over fetching many files one by one. ## Privacy - Send only what the tools need: a description of the component you want and public compatibility constraints such as "Svelte 5, no extra dependencies". - Do not send your project's source code, credentials, environment files or personal data. None of the tools need them. - Treat search queries as data sent to a public service. JSON-RPC batch requests (a JSON array of messages) are not supported and are rejected with HTTP 400 and error code `-32600`; send one message per request. Requests from web browsers are accepted only from allowed origins; requests without an `Origin` header, which is typical for desktop and command-line clients, are not subject to that check. ## Troubleshooting - **The client cannot connect.** Check that it supports remote servers over Streamable HTTP and that the URL is exactly `https://pagesugar.com/mcp`. Compare your configuration with the [setup steps](/mcp) for your client; the key that holds the URL differs between clients. - **Opening the endpoint in a browser shows a web page.** That is expected. Browsers get the MCP page; clients that `POST` get the protocol. - **A browser-based client is rejected.** Its origin is not on the server's allowlist. - **Results look out of date.** Results state the exact versions they resolved, and pagination cursors are bound to one catalogue revision. Restart browsing if you see `REVISION_EXPIRED`. - **Files are missing from a result.** Check `contentStatus`. `manifest-only` means you need `get_component_file` or the bundle. ## Machine-readable guides - Setup steps for every client, as Markdown for your agent: [/mcp.md](/mcp.md) - This page as Markdown: [/docs/mcp.md](/docs/mcp.md) - Agent navigation guide: [/llms.txt](/llms.txt) - The [agent workflow](/docs/agents) describes how an agent should use these tools end to end.