MCP Tools Reference

The shadcnio MCP server ships 15 tools, auto-discovered by every MCP client on tools/list. Each tool has a dedicated page with its signature, response shape, internal data source, example prompts, and manual curl invocations.

Typical flow

                      ┌─ search_items(q, type) ──┐
list_popular(type) ───┤                          ├─▶ get_item ──▶ get_item_details  (curated FAQ + related + opening)
                      │                          │           ╲
list_block_categories │                          │            ╲▶ get_item_source    (full TSX)
   └─ list_blocks_in_category ─▶ slug ───────────┤
                                                 │
                                                 └─▶ get_install_command ─▶ `shadcn add` runs with your token embedded
                                                 └─▶ get_preview_url     ─▶ live iframe + docs page URLs

search_icons ─▶ get_icon

Agents use get_item (lite) to browse candidates cheaply, then escalate to get_item_details (curated JSDoc) or get_item_source (full code) only for the winner. get_install_command is the final handoff — it emits a shadcn add URL with your registry token baked in, so the install runs with zero extra setup.

By category

Discovery

Retrieval

Icons

Utilities + Introspection

Manual invocation basics

Every tool can be driven by hand via JSON-RPC. The envelope is always the same:

curl -s -X POST "https://www.shadcn.io/api/mcp?token=YOUR_TOKEN" \
  -H "content-type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "<tool-name>",
      "arguments": { ... }
    }
  }'

• tools/list with no arguments returns the full schema for all 10 tools — use this to introspect from a new client.
• The Authorization: Bearer YOUR_TOKEN header works as a fallback to the query-param token.

Rate limits

• Unauthenticated (no/invalid token): 60 requests/min per IP.
• Authenticated Pro: 600 requests/min per token.

Both return 429 with Retry-After when exceeded. Agents that blast past 600/min are almost always stuck in a loop — review the prompt.

Error shape

Tool handlers that fail validation or can't resolve a resource return MCP-standard errors inside the tool result:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{ "type": "text", "text": "Registry item not found: nonexistent-slug" }],
    "isError": true
  }
}

Auth failures (missing token, expired Pro, rate limit) are HTTP-level errors with JSON bodies, not MCP tool errors — they never reach the tool handler.