all docsAgent Bridge (MCP)

docs / Integrations

Agent Bridge (MCP)

Connect Claude Code, Cursor, Cline, Lovable, or any MCP client to your design tokens and component library.

The Agent Bridge is an MCP server built into Xtractly. Your coding agent gets direct access to your design tokens, captured components, and library — and can write new components back — running on your agent subscription — Xtractly runs no AI of its own. It works with Lifetime or during your free trial, with no limits on reads or saves.

Connect

Every agent on your computer, in one go:

npx xtractly init

It signs you in in the browser (nothing to copy), finds Claude Code, Cursor, Codex, VS Code (Copilot), Windsurf and Gemini CLI and adds Xtractly to the ones you pick, and links the repo you're in to an Xtractly project. Run npx xtractly doctor any time to check the setup. Needs Node 18 or newer.

Claude (web, desktop or mobile): Settings → Connectors → Add custom connector, and paste https://www.xtractly.app/api/mcp. Claude sends you to Xtractly to sign in and approve — no token to copy. The same sign-in works for any MCP client that supports OAuth.

Cursor: Add to Cursor installs it in one click and signs you in the same way.

Apps connected this way are listed under Settings → Agent Bridge → Connected apps, where you can disconnect them.

For everything else, use a token:

1

In the app, open Settings → Agent Bridge and generate an access token. Copy it — it starts with xtr_ and is only shown once.

2

Add the server to your agent using the config for your tool:

Claude Code (run in terminal):

claude mcp add xtractly --transport http https://www.xtractly.app/api/mcp --header "Authorization: Bearer xtr_your_token" --scope user

Cursor — add to ~/.cursor/mcp.json:

json
{
  "mcpServers": {
    "xtractly": {
      "url": "https://www.xtractly.app/api/mcp",
      "headers": { "Authorization": "Bearer xtr_your_token" }
    }
  }
}

Cline — open Cline → Settings → MCP Servers → Edit JSON:

json
{
  "mcpServers": {
    "xtractly": {
      "url": "https://www.xtractly.app/api/mcp",
      "headers": { "Authorization": "Bearer xtr_your_token" },
      "type": "streamable-http"
    }
  }
}

Lovable — open Settings → Integrations → MCP Servers → Add server:

json
{
  "mcpServers": {
    "xtractly": {
      "url": "https://www.xtractly.app/api/mcp",
      "headers": { "Authorization": "Bearer xtr_your_token" },
      "type": "streamable-http"
    }
  }
}

Windsurf, Zed, or any other HTTP MCP client — add an HTTP MCP server at https://www.xtractly.app/api/mcp with Authorization: Bearer xtr_your_token.

3

Verify: check your client's tool list and ask the agent to "list my Xtractly projects" or "list my themes".

note

Bolt, v0, Replit, ChatGPT, and other tools without MCP support can still use your design tokens — open any theme in the app, click Copy :root to get all CSS variables, then paste them into the AI tool's system prompt or context window.

heads up

Each token has full read/write access to your projects. Treat it like a password, use a separate token per machine, and revoke unused ones from Settings → Agent Bridge.

Limits

None, on any plan or during your free trial: your agent can read your library and save to it as often as it likes. Once a trial ends without Lifetime, every tool except get_guide answers with a note saying so; your agent will pass it on rather than retry.

Tools

Reading your library

ToolWhat it does
list_themesYour design themes — extracted from real sites or hand-built. Returns name, source, font, and token count.
get_themeA theme's full token set (colors, radius, spacing, type) as grouped values and a ready-to-paste :root {} CSS block. Pass format for a file instead: tailwind-v4, tailwind-v3, shadcn, dtcg, figma-variables or design-md.
list_componentsEvery saved component across all projects — the /components library. Supports a title filter.
get_fragmentOne component's full file set, optionally re-shaped for the framework you're working in.
list_projectsYour projects, most recently updated first.
get_projectA project's details and history. File contents are summarised by default.
get_extractionThe raw content captured for a project, before it became a component.
get_guideStep-by-step workflow for a task.

What you just captured

ToolWhat it does
get_latest_captureThe element you last captured in the browser — its code, re-shaped for the framework you're in when possible. Pass a captureId for an earlier one.
list_recent_capturesYour captures from the last 24 hours, newest first (no code).

These need Send captures to my agent turned on in the extension's Settings (it's off by default). With it on, each capture is sent to your account; only the latest 12 are kept, for 24 hours, and turning it off deletes them.

What you clipped for this repo

ToolWhat it does
get_project_contextEverything you clipped into a project from the browser (docs pages, selected errors and responses, components, screenshots, notes), newest first.
get_clipOne clip in full. A screenshot comes back as an image.
link_repoThe .xtractly.json and agent-instructions note that tie a repo to a project.
save_clip / delete_clipAdd a note to a project's context, or remove a clip.

See Project context for clipping and linking a repo.

Writing to your library

ToolWhat it does
create_projectAn empty project to save components into. A component always belongs to one, so a fresh account needs this first.
create_fragmentSave a new component to a project — appears in history and the preview just like a capture.
update_fragmentPatch files on an existing component (merges with the current set).

The canvas

When a component is open in Xtractly, the app shares what you've selected on its canvas — so you can tell your agent "make this button bigger" and it knows what you mean. Edits land on the open canvas within about a second.

ToolWhat it does
get_selectionWhat you've selected right now: the frame (component or variant) and, if you picked one, the element — its source, classes and text — plus the component's other variants.
get_element_treeEvery element in a component with its address (loc), classes and text, for when nothing is selected.
edit_elementChange one element's Tailwind classes and/or text — the same precise edit the canvas inspector makes, saved as a new version.
create_variantDuplicate a component into a new frame beside it, optionally with changes — for trying an alternative without overwriting yours.

Requests from the canvas

On a component's preview page, click Comment, pick the elements you mean (they get numbered pins), and type what should change. Xtractly runs no AI, so the request waits for your agent, like a comment in a design tool. Run npx xtractly watch once and each request starts your agent (Claude Code by default) the moment you send it. Or tell an open agent "do my Xtractly requests", or "watch Xtractly" to have it pick each one up as you send it. Its edit shows on the page as soon as it's saved, and the request shows Waiting, Agent working… or Done along with the agent's reply.

ToolWhat it does
list_requestsOpen and in-progress requests: the prompt, the component, and the pinned elements' HTML. Reading them marks them working.
wait_for_requestsWaits up to 50 seconds for a new request and returns it the moment you send it. Used to keep watching.
update_requestMarks a request done with a short reply shown to you.
get_designThe component's design document: the HTML the preview page shows and edits.
edit_designFind-and-replace edits to that document. All of them land or none do.
write_designReplaces the whole document, for big restructures.

get_fragment

Returns one component's files.

ParameterTypeDefaultDescription
fragmentIdstring—The id, as list_components reported it
componentFormathtml | jsx | vue | svelteas capturedShape to return the component in
styleFormatinline | tailwindas capturedHow styling is carried
offsetinteger0Byte offset to read from
maxBytesinteger262144Bytes per piece, from 1,024 up to 262,144 (256 KB)

The reply names what it actually gave you in servedAs, and adds a notice when that isn't what you asked for. See Formats for why it sometimes can't be.

get_project

ParameterTypeDefaultDescription
projectIdstring—The project id
includeFilesbooleanfalseInline every component's full file contents
offset / maxBytesinteger—As above

By default each component's files are listed as paths and byte sizes rather than contents, and a long captured page is cut to its first 800 bytes. A real project runs to tens of kilobytes otherwise, nearly all of it things you didn't ask for. get_fragment and get_extraction return the full versions.

create_fragment

ParameterTypeDescription
projectIdstringThe project to add this component to
titlestringShort title, e.g. Pricing Card
summarystringOne-line description of what was built (optional)
filesarray{ path, content } objects — the whole component

create_project

ParameterTypeDescription
promptstringWhat the project is for, stored as its opening message (optional)

get_guide

ParameterTypeDescription
topictoken-usage | extension-sync | fragment-authoring | library-export | canvas-editingWhich workflow to explain

Formats

A component is captured in one shape — whichever framework and styling the extension was set to at the time — and that shape is what files holds. Components captured from September 2026 onwards also keep the original markup, which is what lets get_fragment hand the same component back as something else.

Asked forServed
The format it was captured inExactly what was stored
html, vue or svelteRebuilt from the stored markup
jsx, on a component captured as ReactExactly what was stored
jsx, on anything elseThe captured format, with a notice — HTML→JSX conversion runs in the extension, not on the server
A different styleFormatThe captured styling, with a notice

styleFormat can't be switched after the fact because the markup itself carries the styling: utility classes and style attributes are different markup, decided when the element was read off the page. To change either one, re-capture the element with the extension set the way you want it.

A component saved before the original capture was kept can only be served as saved. The notice says so.

Large results

A single reply is capped at 256 KB. Anything longer arrives as a piece plus a line telling you how to get the next one:

code
[412,880 bytes total; this piece is 0–262,144. Read the next piece with
get_fragment fragmentId: "k17…" offset: 262144. Reading in pieces costs nothing extra.]

Byte offsets, not characters, and a character split across a boundary reassembles when the next piece is read. Reading in pieces is free, however many pieces it takes.

Typical workflows

Build on-brand components using your theme

Ask the agent to list_themes to find your theme, then get_theme to pull the full token set. The response includes a :root {} block — tell the agent to use those CSS variables (var(--brand), var(--radius-md)) when writing any component instead of hardcoded colours. get_guide with token-usage explains the full flow.

Build what you just pointed at

Turn on Send captures to my agent in the extension's Settings. Capture an element on any site, then tell your agent "build the card I just captured as a component in this repo". It calls get_latest_capture in your project's framework, lands the code and swaps in your theme's tokens.

Keep a project on-brand for good

Ask the agent to call get_theme with format: "design-md" and save the result as DESIGN.md in your repo (or format: "tailwind-v4" into your CSS). Every later session — yours or the agent's — reads the same palette, type scale and radii without calling the Bridge again.

Pull a component into your repo

Ask the agent to list_components (optionally with a search), then get_fragment for the one you want — passing componentFormat if your project isn't React — and write the files under src/components/xtractly/<name>/, adjusting import aliases to match. get_guide with library-export spells this out step by step.

Rebuild an extension capture as code

Capture a page section with the extension so it lands in a project, then from your editor: get_extraction for that project → generate a clean component → create_fragment to save it back so it's in your library too.

Edit what you're looking at

Open a component in Xtractly, click Agent in its toolbar, pin the elements you mean and say what should change. Then tell your agent "do my Xtractly requests". It calls list_requests, changes the design with edit_design, and marks the request done with update_request — the page updates in front of you. Ask for "a dark version" instead and it uses create_variant, so yours stays untouched. get_guide with canvas-requests has the details.

Iterate from your editor

get_fragment to read the current files, make changes locally, update_fragment to push them back. If the component has been edited on its page, change its design with get_design and edit_design instead — that's what the page shows.

Troubleshooting

What you seeWhat it meansWhat to do
Unauthorized. Pass a valid Xtractly Bridge token as a Bearer token.No token reached the server, or it was revoked.Check the Authorization header in your client config. Generate a new token in Settings → Agent Bridge.
The server connects but no tools appearThe connection was refused before the tool list was sent — almost always the token.Same as above, then restart your client.
The server doesn't appear in your client at allThe config wasn't picked up.Restart the client. Check the file path and that the JSON parses.
Your Xtractly account doesn't have a plan…The account has no plan or trial running (never started, cancelled, or a renewal failed).Start a plan at xtractly.app/pricing; the Bridge works again straight away.
Project not found or not owned by this user.The id is wrong, or it belongs to another account.list_projects to get a current id. Everything is scoped to the account that owns the token.
Fragment not found or not owned by this user.Same, for a component.list_components to get a current id.
Input validation error: … at maxBytesmaxBytes outside 1,024–262,144.Pass a value in range, or omit it.
A notice about the formatThe component can't be served in the shape you asked for.See Formats.
The component came back restructuredThat's the agent, not Xtractly.Ask for it exactly as the tool returned it — the server tells every client to repair a capture, not rewrite it.

Notes

  • The server is stateless — a fresh connection per request. If tools stop responding, restart your agent session first.
  • Everything is scoped to the account that owns the token; the agent only ever sees your own projects, components, and themes.
  • The MCP endpoint is at /api/mcp and accepts both GET and POST with streamable-http transport (MCP spec 2025-03-26).

Still stuck? Write to dondotdev@outlook.com. We're happy to help.