MCP tools reference
The StyleRef MCP server exposes 14 tools. Five are anonymous and read-only; nine require a connected StyleRef account and a scope. This page documents each with its parameters and behavior.
Account-scoped tools gate on a scope (styles:read, styles:write, or extract). An anonymous call to one returns a sign-in message, not an error — see Authentication & scopes.
Anonymous tools
No login. These read and apply public styles.
search_styles
Search the public gallery. The entry point for finding a style.
| Parameter | Type | Notes |
|---|---|---|
query | string | Free-text: aesthetic, mood, discipline, keywords. Optional. |
category | string | Discipline/category filter. Optional. |
sort | popular | recent | Ordering. Defaults to recent. |
limit | integer 1–10 | Max results. Defaults to 8. |
Returns compact cards — name, slug, @handle, essence, URL, hero image, and up to six palette hex colors so a client can show swatches without a second call. Feed a slug to get_style or apply_style_to_prompt.
get_style
Fetch a style compiled into a ready-to-use spec.
| Parameter | Type | Notes |
|---|---|---|
ref | string | Required. A style reference — a share slug, a /share URL, or (connected) your own style’s id or /styles/{id} URL. |
format | default | flux | midjourney | diffusion | stylemd | json | Output dialect. Defaults to default. |
sections | string[] | Return only these sections (for example ["colors","typography"]) to cut tokens. |
compact | boolean | Strip boilerplate and collapse whitespace to save tokens. |
Every response carries the canonical StyleRef URL. json and stylemd return their own structure; other formats get a metadata header and attribution footer.
The image dialects (flux, midjourney, diffusion) leave out writing-voice items — formality, emoji and hashtag usage, tone of copy — which only add noise to an image prompt. default and stylemd keep them.
Your own styles compile from your last generation. get_style, get_style_md and apply_style_to_prompt serve what you last generated on styleref.io, not your live unsaved edits — the same rule the REST API follows, so every surface hands out the same thing. Gallery styles are already frozen published snapshots and are unaffected. A style you have never generated returns this, verbatim, as the tool’s output for you to relay:
This StyleRef hasn’t been generated yet — open it on styleref.io and Generate it first.
apply_style_to_prompt
Wrap a request in a style and return one ready-to-paste prompt for a target tool. No AI call, no credits.
| Parameter | Type | Notes |
|---|---|---|
prompt | string | Required. The raw user request to style. |
ref | string | Required. The style to apply. |
target | chatgpt | claude | gemini | midjourney | flux | dalle | stable-diffusion | generic | Required. Sets the dialect and how the style is placed relative to the request. |
get_style_md
Return a complete STYLE.md body for a style, ready to write into a repo.
| Parameter | Type | Notes |
|---|---|---|
ref | string | Required. The style to export. |
validate_style_md
Lint a STYLE.md document. Read-only.
| Parameter | Type | Notes |
|---|---|---|
text | string | Required. The STYLE.md document to check. |
Returns valid, errors, warnings, and parsed meta. See Validate & lint.
Account-scoped tools
These require a connected StyleRef account. The scope is listed per tool.
list_my_styles · styles:read
List the styles in the connected user’s library — name, visibility, last update, link.
| Parameter | Type | Notes |
|---|---|---|
limit | integer 1–50 | Max styles. Defaults to 20. |
save_style · styles:write
Save (like) a public gallery style to the user’s library. Idempotent.
| Parameter | Type | Notes |
|---|---|---|
ref | string | Required. The gallery style to save. |
fork_style · styles:write
Remix a public style into the user’s library as a private, editable copy with lineage back to the original.
| Parameter | Type | Notes |
|---|---|---|
ref | string | Required. The gallery style to remix. |
create_style · styles:write
Author a style from structured blocks, or duplicate one with from_ref (a plain copy, no lineage). You can pass both to duplicate-then-tweak. Read the styleref://schema resource first for valid block types.
| Parameter | Type | Notes |
|---|---|---|
name | string | Style name. Optional when duplicating. |
description | string | One-paragraph description. Optional. |
blocks | array | Style blocks per the schema. Required unless from_ref is given. |
from_ref | string | Duplicate this style’s blocks. |
Each block is { type, value } where type is a schema block type and value matches the shape the schema defines.
update_style · styles:write
Rename a style and/or add or replace blocks (a supplied block replaces the existing block of the same type). Blocks cannot be deleted through MCP.
| Parameter | Type | Notes |
|---|---|---|
ref | string | Required. One of your styles — its share slug or id. list_my_styles returns a ready-to-use ref. |
name | string | New name. Optional. |
set_blocks | array | Blocks to add or replace, matched by type. Optional. |
extract_style · extract
Run AI extraction to derive a structured style from any combination of sources. Async — returns an id to poll. Spends extraction credits on the Free plan (see Plans & limits).
| Parameter | Type | Notes |
|---|---|---|
text | string | A description or brand brief. |
reference | string | A named aesthetic to emulate (for example “Bauhaus”). |
image_url | string (https) | A public image URL. |
document_url | string (https) | A public PDF or text file URL. |
Provide at least one source; multiple are fused into one style. Poll check_extraction_status for the result.
check_extraction_status · extract
Poll an extraction started by extract_style.
| Parameter | Type | Notes |
|---|---|---|
extraction_id | string | Required. The id returned by extract_style. |
save_as_draft | boolean | On completion, save the result as a draft style in your library. |
name | string | Name for the draft. Defaults to the AI-suggested title. |
Saving is idempotent — polling twice with save_as_draft returns the same style rather than creating a duplicate. When the extraction came from an image, that image is attached to the draft as an inspiration image, the same as in the app.
On the free plan an extraction is capped to the top style items by rank. When items are withheld, the result says so on its own line (“Free plan: the top 10 style items were returned and 12 more are locked — Pro unlocks the full extraction”) instead of returning a silently shortened list. Relay that line to the user.
publish_style · styles:write
Publish one of your styles through the moderation pipeline: public lists it in the gallery, unlisted activates a shareable link only. Both run an automated safety and metadata review.
| Parameter | Type | Notes |
|---|---|---|
ref | string | Required. One of your styles. |
visibility | public | unlisted | Defaults to public. |
confirm_rights | boolean | Must be true — confirms you have the rights to publish. |
Publishing to public requires a minimum number of style items.
set_style_visibility · styles:write
Lightweight visibility control: private revokes the share link; unlisted removes a listed style from the gallery while keeping its link. Activating a link for the first time must go through publish_style (it needs moderation).
| Parameter | Type | Notes |
|---|---|---|
ref | string | Required. One of your styles. |
visibility | private | unlisted | Required. |
Next steps
- Resources & prompts — browseable data and reusable prompts.
- Authentication & scopes — connect an account for write tools.
- Connect your client — set up the server.