Agent Rules and MCP

[deebov]

Problem or use case

Warning

This is an ongoing task and isn't expected to work as expected.

Currently, when trying to build UIs using Untitled UI React components via AI agents such as Cursor or Claude Code you might run into a problem where these agents just go off the track and start pulling random components or design styles. This is quite frustrating because it discourages the usage of AI agents with Untitled UI React.

This thread is meant for building out the first working versions of our new agent rules and MCP. All feedback is very welcome 🤗.

(The MCP server is currently under private beta and will be moved into public beta soon)

Proposed solution

Copy the raw content of this gist into your CLAUDE.md / .cursor/rules/untitledui.mdc file. Feel free to make any suggestions 🤗.

https://gist.github.com/deebov/307cf9d9124e1cf98e80bda84fef2b9d

[sbilde]

This is great to see! I actually built a community MCP server for UntitledUI while waiting for an official solution:
https://github.com/sbilde/untitledui-mcp

What it currently does:

• Component discovery (search_components, list_components)
• Fetches components with automatic base dependency resolution (get_component_with_deps)
• Full page template fetching (get_example)
• Token estimates for large responses
• Works with Pro license (auto-detects from ~/.untitledui/config.json)

Happy to:

1. Share any learnings from building it
2. Contribute to the official MCP if helpful
3. Deprecate mine once the official one goes public

Feedback on the agent rules:
The gist looks solid! One thing I found useful was instructing the AI to always use the starter kits as a base — it avoids a lot of
friction with missing Tailwind tokens and providers.

Looking forward to the public beta!

[sbilde]

Thanks Dilshod! Great to hear from the team.

On the token waste issue:

Yes, ran into this as well. My approach has been:

1. Token estimates in every response — Each response includes estimatedTokens and a per-file fileList with token
   counts. This lets the AI decide upfront whether to use the full response or fall back to individual files.

2. get_component_file tool — When a component is too large (>25K tokens), the AI can fetch individual files instead of
   the whole component. So it gets the file list first, then fetches only the files it needs.

The key insight is giving the AI the metadata to make smart decisions before it fetches the full content.

On the variant selection issue:

Haven't solved this one yet, but I think the problem is that list_components returns too many options without enough context
for the AI to differentiate.

A few ideas:

• Return a short description/preview per variant so the AI can make an informed choice
• Group variants by category (size, style, layout) so the AI understands the taxonomy
• Let the AI ask the user to pick from a curated shortlist instead of choosing on its own

Would love to collaborate on solving these problems — happy to contribute to the official MCP if that's useful, or keep
iterating on the community version. Either way, these are the right problems to solve.

[deebov]

Awesome! Though, the first issue is why I still haven't released because it can easily burn through users tokens, which happened many times while I was developing it. This might make a lot of people angry once they find out we burned their monthly tokens.

Is your MCP using bash command to write files or is it occasionally reading the whole fetched content?

[deebov]

Hey @sbilde, just a heads up — I'm going a bit different route of not returning the file content in the MCP response but rather a CLI command which install those files. I cannot find a guaranteed way that all those files will count towards the token usage so it's safe to install everything via CLI.

[deebov]

Hey @sbilde, thanks again for your contribution. We've just rolled out our MCP server with improved flow. Now instead of sending the full file content, which would quickly burn through your token, we send an npx comaand to install those files which is both faster and cheap. Additionally, we've implemented OAuth so that you can authenticate our MCP via browser.

Let us know if you have any suggestions, would love to hear them!

https://www.untitledui.com/react/integrations/mcp

[sbilde]

Hey @deebov! Just checked out the official MCP — really nice work!

I love the approach of sending CLI commands instead of piping the full code through the AI. That's a much cleaner solution to the token waste problem than my token
estimates + file-level fallback approach. Smart move.

A few things I noticed that might be worth considering:

1. get_component_with_deps vs get_component_bundle — In my version, the MCP automatically parses @/components/base/* imports and fetches all base dependencies
   without the AI needing to know what they are. Could be useful for the official version too, so the AI doesn't have to guess which base components are needed.

2. list_component_types — I have a tool that returns the top-level categories (base, application, marketing, etc.) before drilling into a specific one. Small thing,
   but it helps the AI orient itself.

Glad the discussion around token handling was useful. Happy to deprecate my community version now that the official one is live — or keep it around as an alternative for
anyone who prefers the "code in context" approach over CLI installation.

Either way, great to see this ship. Congrats to the team!

[deebov]

And here's our CLAUDE.md and GEMINI.md instructions.

For generic AGENT.md please see https://www.untitledui.com/react/AGENT.md