Skip to content
PageSugar 4 components
Search components
Docs Site navigation
Documentation menu

MCP reference

Technical reference for the MCP server. Its endpoint, tools, limits, version rules, errors and privacy notes. Setup steps for each coding agent are on the MCP page.

View as Markdown

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.

Endpoint #

Plain 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 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 gives setup steps for each client. Those steps follow each client's own documentation and carry the date they were last checked against it.

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:

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 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
  • This page as Markdown: /docs/mcp.md
  • Agent navigation guide: /llms.txt
  • The agent workflow describes how an agent should use these tools end to end.

Search components

Describe a section or control, such as “FAQ accordion” or “newsletter signup”.

Browse all components