Norsk English (UK) English (US) Svenska Deutsch Français Español 中文 (简体)

// GUIDES

Isabyte MCP Server

Isabyte MCP Server

A self-contained Model Context Protocol server that turns any MCP-aware AI client into an Isabyte Power Tools expert.

The Isabyte MCP Server bakes the entire Isabyte Power Tools skill corpus into a lightweight Linux image (~50 MB) and exposes it over the Model Context Protocol's Streamable-HTTP transport. Connect Claude Desktop, Cline, Cursor, Continue, or any other MCP client and your AI assistant becomes an Isabyte specialist with grounded knowledge of every component, parameter, and pattern in the catalog.

One server, one catalog. The skill files describe the design system itself — the component catalog, parameters, and design tokens shared by every Isabyte Power Tools package — so the same server grounds your assistant whichever package you build with.

How to run

  1. Download the zip and extract it.
  2. Load the image into your local Docker engine: bash load.sh
  3. Start the server: docker run --rm -p 7180:7180 isabyte-mcp-server:<version>
  4. Verify it's healthy: curl http://localhost:7180/health returns {"status":"ok","skills":10}.
  5. Connect any MCP client to http://localhost:7180/mcp.

MCP client configuration

Every client has its own configuration format, and a wrong key makes a client ignore the entry or fall back to an older transport. Making the MCP server work below has the exact entry for each client. The most common shape is this one, which Cursor uses:

{
  "mcpServers": {
    "isabyte-expert": {
      "url": "http://localhost:7180/mcp"
    }
  }
}

Other clients differ: VS Code uses the key servers with "type": "http", Windsurf serverUrl, Gemini CLI httpUrl, Cline "type": "streamableHttp", and opencode an mcp key with "type": "remote". Claude Code and OpenAI Codex add the server with a command.

Once connected, your assistant can read every Isabyte skill as an MCP resource (isabyte-skill://) or through the MCP tools list_isabyte_skills and read_isabyte_skill, which return the same text for clients that support tools but not resources. The isabyte_expert_guidance prompt injects every skill as grounding context.

Security

By default the server binds to 0.0.0.0 with no auth — fine for a single local workstation. If the container is reachable beyond localhost:

  • Bind to localhost only: -p 127.0.0.1:7180:7180
  • Or require a bearer token: -e MCP_AUTH_TOKEN="$(openssl rand -hex 24)" and add "headers": { "Authorization": "Bearer YOUR_TOKEN" } to your client config.

Making the MCP server work

An AI coding agent needs two things before it uses the server well: a connection (the server in your client's MCP configuration) and an instruction file in your project that tells the agent when to use it. Without the instruction file the agent can see the server but does not know that it should read the Isabyte documentation before it writes Isabyte code, so it guesses instead.

The instruction file. Its content is the same for every client; only the file name and folder differ, so download it for your client below. It is in English on purpose: the agent reads it, not your team. A browser download cannot create folders, so move the file to the path shown for your client. If your project already has a file with that name, append the content to it instead of replacing it. The Cursor, Windsurf and Continue files start with a short header that makes the client load the file in every session; keep it at the very top of the file.

Before you start. The server must be running (see How to run). Every example below registers it under the name isabyte-expert at http://localhost:7180/mcp. If you started the server with MCP_AUTH_TOKEN, also add the Authorization: Bearer header from Security in the headers field of your client's configuration.

Resources or tools — it works either way. The server offers the Isabyte documentation twice, with the same text: as MCP resources (isabyte-skill://…) and through two MCP tools, list_isabyte_skills and read_isabyte_skill. Some clients read resources, and every client below can call tools, so the agent always has a way to read the documentation. The instruction file tells it to use the tool when its client cannot read resources.

A test prompt for every client. Once the client is connected, open a new session in your project and ask: "Add an Isabyte date picker to the sign-up form." The agent should read isabyte-skill://isabyte-controls.md, or call read_isabyte_skill for isabyte-controls, before it writes any code. If it writes Isabyte code without reading the Isabyte documentation first, the instruction file is not being loaded.

Claude Code

MCP configuration — this command writes .mcp.json at the project root, so everyone who opens the project gets the server:

claude mcp add --transport http --scope project isabyte-expert http://localhost:7180/mcp

Instruction file — CLAUDE.md at the project root. Download CLAUDE.md

Check that it works — run /mcp in a session: isabyte-expert should be listed as connected. Then try the test prompt.

Common problems — the first time Claude Code starts in the project it asks you to approve the servers in .mcp.json; if you declined, the server stays off. Claude Code reads AGENTS.md only when the project has no CLAUDE.md, so put the content in CLAUDE.md.

OpenAI Codex

MCP configuration — codex mcp add isabyte-expert --url http://localhost:7180/mcp, which adds this to ~/.codex/config.toml:

[mcp_servers.isabyte-expert]
url = "http://localhost:7180/mcp"

Instruction file — AGENTS.md at the project root. Download AGENTS.md

Check that it works — codex mcp list, or /mcp in the Codex terminal UI. Then try the test prompt.

If you started the server with MCP_AUTH_TOKEN, put the token in an environment variable and add bearer_token_env_var = "ISABYTE_TOKEN" (the variable's name) to the entry; Codex sends it as the Authorization: Bearer header.

Common problems — a project-level .codex/config.toml is read only in a project you have marked as trusted. Codex's documentation does not list MCP resources, so the agent reads the Isabyte documentation with the tools list_isabyte_skills and read_isabyte_skill. If a long tool result is cut short, raise output_token_limit for read_isabyte_skill in config.toml, or ask the agent to read the skill one section at a time.

GitHub Copilot

MCP configuration — in VS Code, .vscode/mcp.json:

{
  "servers": {
    "isabyte-expert": {
      "type": "http",
      "url": "http://localhost:7180/mcp"
    }
  }
}

Instruction file — .github/copilot-instructions.md. Download copilot-instructions.md

Check that it works — run MCP: List Servers from the Command Palette: isabyte-expert should be running, and MCP: Browse Resources lists its isabyte-skill:// resources. Try the test prompt in agent mode.

Common problems — this file uses the key servers, not mcpServers. The Copilot cloud agent on GitHub.com runs in the cloud, so it cannot reach a server on your localhost. It uses MCP tools only, not resources, so with a server it can reach it reads the documentation with list_isabyte_skills and read_isabyte_skill.

Cursor

MCP configuration — .cursor/mcp.json in the project:

{
  "mcpServers": {
    "isabyte-expert": {
      "url": "http://localhost:7180/mcp"
    }
  }
}

Instruction file — .cursor/rules/isabyte-mcp.mdc. Download isabyte-mcp.mdc

Check that it works — the MCP section of Cursor's settings should show isabyte-expert enabled; connection errors are in the Output panel under "MCP Logs". Then try the test prompt.

Common problems — a rule in .cursor/rules/ must end in .mdc; a plain .md file there is ignored. Cursor also reads an AGENTS.md at the project root, so if your project already has one you can append the content there instead.

Windsurf

MCP configuration — open the MCPs section from the "…" menu in Cascade and edit the raw configuration (mcp_config.json):

{
  "mcpServers": {
    "isabyte-expert": {
      "serverUrl": "http://localhost:7180/mcp"
    }
  }
}

Instruction file — .windsurf/rules/isabyte-mcp.md. Download isabyte-mcp.md

Check that it works — the MCPs section should list isabyte-expert with its tools and resources. Then try the test prompt in Cascade.

Common problems — Windsurf is now called Devin Desktop. It still reads .windsurf/rules/, but its default Devin Local agent reads MCP servers from .devin/mcp_config.json instead of the Cascade configuration; add the server there with devin mcp add -s project isabyte-expert http://localhost:7180/mcp. A rule file can hold at most 12,000 characters.

Gemini CLI

MCP configuration — this command writes .gemini/settings.json in the project:

gemini mcp add --transport http isabyte-expert http://localhost:7180/mcp

The entry it writes uses httpUrl:

{
  "mcpServers": {
    "isabyte-expert": {
      "httpUrl": "http://localhost:7180/mcp"
    }
  }
}

Instruction file — GEMINI.md at the project root. Download GEMINI.md

Check that it works — run /mcp: isabyte-expert should be connected, with its tools and resources listed. Then try the test prompt.

Common problems — in settings.json, httpUrl means Streamable HTTP, which this server speaks; url means the older SSE transport and does not connect. Gemini CLI reads AGENTS.md only if context.fileName in its settings lists it, so use GEMINI.md. Gemini CLI shortens tool results longer than 40,000 characters by default (tools.truncateToolOutputThreshold); the largest Isabyte skill is longer, so the agent should read it one section at a time (read_isabyte_skill takes a section).

Cline

MCP configuration — in the MCP Servers panel, choose Configure → "Configure MCP Servers" and add:

{
  "mcpServers": {
    "isabyte-expert": {
      "type": "streamableHttp",
      "url": "http://localhost:7180/mcp"
    }
  }
}

Instruction file — .clinerules/isabyte-mcp.md. Download isabyte-mcp.md

Check that it works — the MCP Servers panel should show isabyte-expert as connected, with the tools list_isabyte_skills and read_isabyte_skill. Then try the test prompt.

Common problems — without "type": "streamableHttp" Cline falls back to the older SSE transport and cannot connect. Cline's documentation mentions MCP resources only in passing, so the agent reads the Isabyte documentation with the tools.

Continue

MCP configuration — a file .continue/mcpServers/isabyte-expert.yaml:

name: Isabyte MCP server
version: 0.0.1
schema: v1
mcpServers:
  - name: isabyte-expert
    type: streamable-http
    url: http://localhost:7180/mcp

Instruction file — .continue/rules/isabyte-mcp.md. Download isabyte-mcp.md

Check that it works — in agent mode, type @: the isabyte-expert resources should appear among the context providers. Then try the test prompt.

Common problems — Continue uses MCP servers in agent mode only. The YAML file needs its name, version and schema lines, or it is not loaded. The Authorization header goes under requestOptions: → headers: in the server entry.

opencode

MCP configuration — opencode.json at the project root:

{
  "mcp": {
    "isabyte-expert": {
      "type": "remote",
      "url": "http://localhost:7180/mcp",
      "enabled": true
    }
  }
}

Instruction file — AGENTS.md at the project root, the same file OpenAI Codex reads. Download AGENTS.md

Check that it works — opencode mcp list shows whether isabyte-expert is connected. Then try the test prompt.

Common problems — opencode reads CLAUDE.md only when the project has no AGENTS.md. Its documentation describes MCP tools only, so the agent reads the Isabyte documentation with the tools list_isabyte_skills and read_isabyte_skill.

Claude Desktop

Claude Desktop has no project instruction file. In a Claude project, paste the content of any download above into the project instructions instead. Its custom connectors (Customize → Connectors → Add custom connector) connect from Anthropic's cloud, not from your computer, so they cannot reach a server on localhost: the server must be reachable over HTTPS from the internet.

If it still does not work

  • curl http://localhost:7180/health fails: the server is not running.
  • The address must end in /mcp.
  • The client reports 401: the server was started with MCP_AUTH_TOKEN, and the client sends no Authorization: Bearer header, or the wrong token.
  • The agent writes Isabyte code without reading the Isabyte documentation (a resource or read_isabyte_skill): the instruction file is not at the path shown for your client, or you have not started a new session since you added it.
  • After you change a client's MCP configuration, restart the client or start a new session.
An unhandled error has occurred. Reload 🗙

Rejoining the server...

Rejoin failed... trying again in seconds.

Failed to rejoin.
Please retry or reload the page.

The session has been paused by the server.

Failed to resume the session.
Please reload the page.