MCP server

cilo's hosted MCP server lets your coding agent find blocks by what they do, read their source and add them to your project with the shadcn CLI. Connect it once with your access key for MCP; then ask in plain words.

Introduction

The Model Context Protocol is how a coding agent reaches tools and data while it works, instead of relying on what its model already knows. cilo's server, at https://mcp.cilo.com, gives it the real catalog: every free and pro block and every palette, with the names, the descriptions, the props a block takes and source where it is available.

Your agent can pick the tools from what you ask; a client with a tool inspector can also call them directly. Installation uses the registries named in your project’s components.json.

The server never writes to your project itself. It hands your agent the add command, and the agent runs it in your terminal, as you would.

Setup overview

Endpoint
https://mcp.cilo.com
Transport
Streamable HTTP. Use the full server URL in a client that supports this transport.
Authentication
Authorization: Bearer <MCP access key>. Tool calls require the MCP credential. The tool list and connection handshake alone do not confirm access. Use CILO_MCP_TOKEN for examples that read the key from your agent’s environment; CILO_TOKEN remains the separate pro-install credential.
Pro source
Pro items are discoverable. If source reading is unavailable, ask for an install command, install through @cilo-pro with your pro key, and read the installed files.

Most agents take an entry of this shape; your agent's page has its exact file and fields:

mcp.jsonJSON
{
"mcpServers": {
"cilo": {
"type": "http",
"url": "https://mcp.cilo.com",
"headers": {
"Authorization": "Bearer ${CILO_MCP_TOKEN}"
}
}
}
}

The agent also runs the shadcn CLI, so the project needs both registries in components.json and CILO_TOKEN in .env.local, as Installation shows. The MCP server offers no OAuth sign-in: configure the Bearer header instead.

What your agent can do

The server gives the agent eight tools, all read-only:

components_list
With no arguments, a map of the catalog: every family with its count, the topics, the palettes and the skill. Then narrow by family, kind, role or topic, or search in plain words, best match first.
component_install
The way to add items. Checks the names, resolves other names and suggests the right one on a typo, then returns one npx shadcn@latest add command with a dry run first, an import line per item and how to fill it.
component_get
Reads an item's source, file by file, with its packages, the stock components it uses, its colours and its dependencies, icons resolved for your style. For reading, not for installing.
component_dependencies
Lists what an item would bring, packages and items, without the file contents.
styles_list
The eight shadcn styles, nova first. A block is the same in all of them; source previews use the style’s default icon set.
variants_list
The component libraries. cilo is Base UI only.
tiers_list
How many items are free and how many pro.
documentation_get
These docs as Markdown, the same pages as on this site: with no arguments, the list of every page; a page whole, or one section of it. A plugin, or one of its parts, opens the section of its manual that documents it.

It also offers the cilo_init prompt, which hands a client that asks for it the whole workflow below. It publishes no MCP resources or resource templates. On connecting it tells the agent the rules: install with component_install, import from components/cilo, change a block in shadcn's order, never paste one into a page.

Tool arguments and examples

Pass arguments as JSON in your client’s tool inspector, or let your agent supply them.

components_list
Optional tier (public/pro), variant (base), type, kind (block/plugin/page/palette; component is reserved), role (page/section/panel/inline/overlay), topic, category (a section of the pro menu: ai, charts, forms, planning…), family, query and limit. With no arguments it returns the catalog map. A query, or a kind, role, topic, category or other type filter, returns 20 results by default (limit 1–100); tier, variant or type registry:block alone return the family map. A family alone lists that whole family.
component_get
Required name and variant: "base". Optional tier, style (default "nova") and includeDependencies (default true). Use a bare style such as "lyra", not "base-lyra". "raw" leaves icons unresolved.
component_dependencies
Required name and variant: "base"; optional tier. Returns packages and required items without file contents.
component_install
Required names (1–50 item names) and variant: "base"; optional tier and projectReady. Set projectReady to true after configuring the project and registries to omit one-time setup from the checklist.
styles_list, variants_list, tiers_list
No arguments. Read the supported styles, component library and current free/pro source availability.
documentation_get
Optional page, section and plugin. page is a page of these docs by its address or short name ("installation", "mcp", "agents/cursor", "plugins/stepper"); section is an id from the page’s contents ("api-indicator", # optional) or a section’s exact title; plugin is a plugin ("data-table", "stepper"), any of its parts, which opens the section documenting it, an alias, or "plugins" for the overview. With no arguments it returns every page with its sections and size. Blocks have no page: read them with component_get.

Without tier, an item lookup tries free then pro. A declared alias is accepted; use the resolved name in the answer. Query and filter values can be combined; call components_list without arguments for topic and family names.

components_list argumentsJSON
{
"query": "order tracking",
"kind": "block",
"limit": 5
}
component_dependencies argumentsJSON
{
"name": "b-data-table-1",
"variant": "base"
}
component_get argumentsJSON
{
"name": "b-data-table-1",
"variant": "base",
"style": "nova",
"includeDependencies": true
}
component_install argumentsJSON
{
"names": [
"b-data-table-1",
"pb-order-tracking-1"
],
"variant": "base",
"projectReady": true
}
styles_list / variants_list / tiers_list argumentsJSON
{}
documentation_get argumentsJSON
{
"page": "plugins/stepper",
"section": "api-indicator"
}

Answers are readable text. Source responses name file targets and packages and include required CSS variables. An install response is a command and checklist: your agent still has to run it and verify the files exist.

Limits and source access

  • Item names and aliases are at most 64 characters; queries at most 200 characters. Split installs larger than 50 names into several calls.
  • A source response includes up to about 60,000 characters of file text. It names omitted files. Install with the CLI to obtain the complete item.
  • A docs answer includes up to about 60,000 characters. A longer page comes as whole sections, and the answer names the ones left out; ask for each with section.
  • Calls normally time out after 30 seconds. Narrow a large request or retry after a transient failure.
  • If you receive HTTP 429, wait for the Retry-After interval before retrying. The default limit is 120 calls per minute per client address; calls in a batch count separately.
  • Pro source may not be readable through MCP. component_install still returns the pro install command; use the project’s pro licence key and read the local files. MCP access alone does not authorize a pro CLI download.

How a block gets in

Step 1: Find it

The agent calls components_list, by family, topic or plain words, and never guesses a name. Where it needs to know more, component_dependencies or component_get reads the item.

Step 2: Get one command

One component_install call for every item the job needs returns one command: a dry run first, then the install, and an import line per item.

Step 3: Run it and fill it

The agent runs the command in your project, checks the files are there, imports the blocks and gives them your content: a data prop or the top constants. Then it type-checks once and stops.

Add the agent skill

The server reaches the catalog; cilo's skill teaches the agent the habits around it (the install path, the item kinds, how to fill and change a block). Add it from the project's folder:

Terminal
npx shadcn@latest add @cilo/skill

It writes .claude/skills/cilo/SKILL.md, where Claude Code reads it. An agent that reads skills elsewhere takes the same SKILL.md from its own skills folder.

Pick your agent

Each page has the exact file, the command where there is one, and how to see the server connected.

Anatomy of a good prompt

A reliable ask answers five questions. Plain words are enough; the more you make explicit, the less the agent guesses.

Trigger
Is cilo named? “Using cilo, …” keeps the agent on this server rather than another.
Unit
One block or a shell for a whole screen? “a card”, “a table” against “a store admin shell”.
What
What it does, in your words: “an order tracker with the courier on a map”.
Content
Whose data? “filled with our orders from lib/orders.ts”, or leave the block's sample.
Where
Which file and where in it: “on app/orders/[id]/page.tsx, under the header”.
  • “Using cilo, add an order tracking card with the courier on a map to app/orders/[id]/page.tsx, under the header, filled with the order from lib/orders.ts.”

You never need item names such as pb-order-tracking-1. The agent looks them up; describe what you want instead. If you know the name, say it and the agent skips the search.

Blocks and pages

Block
One piece: a table, a chart, an approval, a composer, a sidebar shell. Free ones are @cilo/b-…, pro ones @cilo-pro/pb-…. Ask for one when you add a piece to a page you have.
Plugin
A component of cilo's own, core and parts: @cilo/<plugin> and @cilo/<plugin>-<part>, installed into components/cilo/<plugin>/. Each has its manual under Plugins. Ask for one when you build that kind of piece on your own data.
Page
Pro pages, @cilo-pro/pp-…, are not published for now. For a whole screen, ask for a shell and one block per region.
Palette
The colours of the whole project, @cilo/cilo and eleven more. Ask once, at the start.

When you want more than one region, ask for them together: the agent installs them in one command and writes the page once, which holds together better than pieces added one at a time.

Palettes and styles

The shape is your project's: the style in components.json (base-nova, base-lyra and the rest) styles the stock components every block is built on, so a block looks native in any of the eight, and the CLI uses your project’s chosen icon library.

The colours are a palette, one registry:theme item per project. cilo, the default, is neutral greys with a blue primary; ask for another by name, such as “use cilo's sage palette”. A block that needs colours beyond shadcn's tokens, such as success and warning, brings them itself.

Screens and layouts

This is where most asks go wrong. A whole screen described in one dense paragraph does not exist in the catalog as one item, so the agent has to invent the assembly. More adjectives do not help; a starting point does. Name a shell to start from, then describe the change.

Instead of one dense paragraph:

  • “Build a store admin with a sidebar, a date range, a table of orders with status and totals, a side panel for one order and an assistant on the right.”

start from a shell, and describe the delta:

  • “Using cilo, start from the store sidebar shell. Put the recent orders and one order's delivery tracking in it, filled from our API in lib/orders.ts, and leave out the agent column.”
  • Name a starting point: a shell, such as the pro sidebar that takes the page as children or the free sidebar demo.
  • List the changes as a delta: add, replace, remove, against that start.
  • State the constraints once: the palette, whose data, which route.

Not sure a fitting shell exists? Ask first: “which cilo shells fit a store admin?”. The agent lists the shells and picks one before it builds. cilo has no site footer, testimonials, logo cloud, call-to-action band or page header; the agent builds those from stock shadcn components.

Prompt recipes

Patterns for the common asks. Replace the bracketed parts.

  • “Using cilo, add a [what it does, e.g. date range picker] to [file], [where in it].”
  • “Using cilo, frame [route] in the [shell] and fill its data from [source].”
  • “Using cilo, start from the [shell] and [add / replace / remove …]. Keep [constraint].”
  • “Using cilo, build [screen] from [region], [region] and [region] in one install, then write the page once.”
  • “Using cilo, add the [name] palette to the project.”
  • “Using cilo, update [block] to the registry's version and show me the diff first.”

One job at a time: let the agent install and fill one block before the next ask, so each is checked before another is built on it.

Ask for blocks

A few things to try once it is connected:

  • “Show me what is in the cilo registry.”
  • “Using cilo, add an order tracking card with the courier on a map to the order page.”
  • “Using cilo, add a date range picker to the bookings filter.”
  • “Using cilo, add a trace waterfall of an agent run to the runs page.”
  • “Which cilo blocks ask a person to approve before the agent acts?”
  • “Using cilo, frame our store admin in a sidebar shell with our sections and their counts.”

Troubleshooting

“This MCP server needs your Cilo subscription key: send Authorization: Bearer <key>. / The subscription key sent in Authorization was not accepted; check it.”
Check the MCP client’s Authorization: Bearer header and MCP access key. If your config reads CILO_MCP_TOKEN, export it before starting the client. A visible tool list does not confirm tool access. A pro registry key is not necessarily the MCP key.
“Cilo has blocks for Base UI projects only”
The agent asked for a Radix or React Aria variant or style. cilo is Base UI only; the project needs a base- style in components.json.
“Registry "@cilo-pro" requires the following environment variables:”
The server answered, but the CLI the agent ran has no key. Put CILO_TOKEN in the project's .env.local; see Installation.
“License required for this item. / token_rejected”
The registry refused a pro item: a wrong key in .env.local, or a pb- name added under @cilo instead of @cilo-pro.
“The Cilo registry is unavailable right now; try again shortly.”
The server could not reach the registry. Try again in a minute.
“stopped after 30000 ms, its time limit; try again or narrow the request.”
A call ran out of time. Ask again, or for less at once: a family or a few names rather than the whole catalog.
“A service access or data error”
Contact Cilo support. This is not repaired by changing your project’s registry files or licence key.

If your agent answers from another registry, name cilo in the ask. If it does not list cilo's tools at all, check the connection as your agent's page shows, and that the URL is exactly https://mcp.cilo.com, with no /mcp or /sse after it.