MCP server

Overview

The Vamos UI MCP server lets an AI assistant work with the kit the way its docs describe it: find the right component or block, read its real API, plan a screen, give you the install command and check the code it writes against the kit's rules. It reads the public registry at https://ui.vamos.ist/r, which currently lists 150+ components and 150+ blocks (dashboards, lists, detail pages, settings, sign-in screens and 59 website pages).

Claude (claude.ai, Desktop, mobile)

1. Open connector settings

   In Claude, open Settings → Connectors and choose Add custom connector.

2. Paste the URL

   Name it Vamos UI, paste https://mcp.vamos.ist/mcp and add it. There is no sign-in step.

3. Use it in a chat

   Enable the connector for the conversation (the tools menu in the message box) and ask for a screen or a component. Connectors added on the web are available in the Desktop and mobile apps too.

On Team and Enterprise plans an owner may need to add the connector for the organisation first.

ChatGPT

Custom MCP servers are added in developer mode: Settings → Apps & Connectors → Advanced settings → Developer mode, then Create a connector with the URL https://mcp.vamos.ist/mcp and authentication No authentication. Select it from the tools menu in a chat. Menu names can differ by plan and app version.

Claude Code, Cursor, VS Code and other editors

One command writes the config for the client your project uses and runs the server locally, with full project access:

npx vamos-ui mcp add                       # detect the clients this project uses
npx vamos-ui mcp add --client claude       # or: cursor, vscode, windsurf, codex, gemini
npx vamos-ui mcp add --client claude --print   # show the config, write nothing

Use the hosted server instead

claude mcp add --transport http vamos-ui https://mcp.vamos.ist/mcp

// .cursor/mcp.json
{
  "mcpServers": {
    "vamos-ui": { "url": "https://mcp.vamos.ist/mcp" }
  }
}

// .vscode/mcp.json
{
  "servers": {
    "vamos-ui": { "type": "http", "url": "https://mcp.vamos.ist/mcp" }
  }
}

Config for Claude Desktop (local), Codex, Windsurf, Gemini CLI, Zed and others is in the packages/mcp README.

Tools

Every tool is marked read-only (readOnlyHint: true): none of them changes anything on your machine, in an account or on the server. audit_site is also marked open-world (openWorldHint: true) because it requests the site you name.

• get_rulesDesign rules· read-only

  The rules every Vamos UI screen follows: tokens only, accent use, density, kit components over hand-rolled markup, accessibility. Called once at the start of a UI task.

• get_themingTheming guide· read-only

  The six theme axes (dark, material, accent, density, font, corners) and what the corner setting covers, the semantic Tailwind classes and, optionally, the full CSS token table.

• list_itemsList registry items· read-only

  Browses components, blocks, lib and style items by docs group, block category or tag.

• searchSearch components and blocks· read-only

  Ranked search over names, descriptions, tags and usage guidance, in English or Turkish.

• get_itemGet a component or item· read-only

  Usage snippet, props, examples, when to use or avoid it, dependencies and file list of one item; source on request.

• get_blockGet a block (whole screen)· read-only

  Full source of a block such as dashboard-05 or login-02, the kit components it uses and how to adapt it.

• plan_screenPlan a screen· read-only

  Turns a screen description into a plan: the block to start from, alternatives, extra components with reasons, the install command and a checklist.

• verify_codeVerify UI code· read-only

  Lints one file against the kit rules: raw colours, dark: variants, hard-coded fonts, missing alt text, click handlers on non-interactive elements, hand-rolled overlays.

• install_commandInstall command· read-only

  Validates item names and returns the exact npx vamos-ui add … command.

• import_design_systemImport a design system from a website· read-only

  Reads page HTML (and optional CSS) and drafts a vamos.brand.json: accent, fonts, logo candidates, with the evidence for each value. Writes nothing.

• propose_accentPropose a brand accent· read-only

  Turns one brand colour into the four accent variables (OKLCH) and checks WCAG contrast for each text pair.

• verify_designVerify the design system· read-only

  Lints a file against the kit rules and the brand. On the hosted server it takes code + filename; project-wide checks need the local server.

• audit_siteAudit a live website· read-only

  Checks a public website over HTTP, built with the kit or not: metadata, Open Graph, JSON-LD, robots.txt and AI crawlers, sitemap, placeholder content, legal links, broken internal links and heavy images, as a scored report. Up to 30 pages; only GET and HEAD requests.

The local server adds three tools that need your project folder: get_brand (reads vamos.brand.json), apply_design_system (writes only with write: true, only inside projectDir) and update_design (reports what npx vamos-ui update would change). It also exposes the prompts build-screen and review-ui, which the hosted server offers as well.

Example prompts

• “Plan a store admin dashboard with KPI cards, a revenue chart and the latest orders using Vamos UI.”
• “Which Vamos UI component should I use to pick a date range? Show me how to use it.”
• “Check this component against the Vamos UI rules and fix what it finds.” (paste the code)
• “Our brand colour is #E4572E. Make it a Vamos UI accent and check the contrast.”
• “Give me the install command for the data table and the login-02 block.”
• “Ürün listesi için hangi Vamos UI blokunu kullanmalıyım?” (search understands Turkish)

Hosted server limits

• No access to your files. The hosted server only sees what your AI client puts in a tool call. Project tools (get_brand, apply_design_system, update_design) are not offered, and verify_design with projectDir returns an error; pass one file as code + filename instead.
• Only public sites, only for audits. import_design_system does not fetch url on the hosted server: paste the page HTML (and CSS) instead, or use the local server or npx vamos-ui brand import <url>. audit_site fetches the site you name with GET and HEAD requests, up to 30 pages and 45 seconds, and refuses private, loopback, link-local, CGNAT and cloud-metadata addresses on every redirect. For a local or private site, or more pages, run npx vamos-ui audit <url>.
• It does not install or run code. It returns source, plans and the npx vamos-ui add command; you or your coding agent run it.
• Best effort. The hosted server is free and has no uptime guarantee. See the terms.

Run your own

npx -y @vamos-ui/mcp --http --port 3333          # Streamable HTTP at http://127.0.0.1:3333/mcp
npx -y @vamos-ui/mcp --registry https://ui.example.com/r   # point at your own registry

It binds to 127.0.0.1 by default and has no authentication: put it behind your own reverse proxy and sign-in before exposing it. More in Security.

Privacy

The hosted server has no accounts and keeps no state. It processes tool arguments in memory to answer and does not store them; audit_site requests the pages of the site you name and keeps nothing from them; the web server logs IP address, time and URL for 30 days. Details in the privacy policy. Don't send secrets or personal data in code you ask it to check.

Support

• Questions, bugs and feature requests: GitHub issues.
• Security problems: report privately, as described in Security.