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 initIt 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:
In the app, open Settings → Agent Bridge and generate an access token. Copy
it — it starts with xtr_ and is only shown once.
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 userCursor — add to ~/.cursor/mcp.json:
{
"mcpServers": {
"xtractly": {
"url": "https://www.xtractly.app/api/mcp",
"headers": { "Authorization": "Bearer xtr_your_token" }
}
}
}
Cline — open Cline → Settings → MCP Servers → Edit 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:
{
"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.
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
| Tool | What it does |
|---|---|
list_themes | Your design themes — extracted from real sites or hand-built. Returns name, source, font, and token count. |
get_theme | A 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_components | Every saved component across all projects — the /components library. Supports a title filter. |
get_fragment | One component's full file set, optionally re-shaped for the framework you're working in. |
list_projects | Your projects, most recently updated first. |
get_project | A project's details and history. File contents are summarised by default. |
get_extraction | The raw content captured for a project, before it became a component. |
get_guide | Step-by-step workflow for a task. |
What you just captured
| Tool | What it does |
|---|---|
get_latest_capture | The 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_captures | Your 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
| Tool | What it does |
|---|---|
get_project_context | Everything you clipped into a project from the browser (docs pages, selected errors and responses, components, screenshots, notes), newest first. |
get_clip | One clip in full. A screenshot comes back as an image. |
link_repo | The .xtractly.json and agent-instructions note that tie a repo to a project. |
save_clip / delete_clip | Add a note to a project's context, or remove a clip. |
See Project context for clipping and linking a repo.
Writing to your library
| Tool | What it does |
|---|---|
create_project | An empty project to save components into. A component always belongs to one, so a fresh account needs this first. |
create_fragment | Save a new component to a project — appears in history and the preview just like a capture. |
update_fragment | Patch 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.
| Tool | What it does |
|---|---|
get_selection | What 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_tree | Every element in a component with its address (loc), classes and text, for when nothing is selected. |
edit_element | Change one element's Tailwind classes and/or text — the same precise edit the canvas inspector makes, saved as a new version. |
create_variant | Duplicate 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.
| Tool | What it does |
|---|---|
list_requests | Open and in-progress requests: the prompt, the component, and the pinned elements' HTML. Reading them marks them working. |
wait_for_requests | Waits up to 50 seconds for a new request and returns it the moment you send it. Used to keep watching. |
update_request | Marks a request done with a short reply shown to you. |
get_design | The component's design document: the HTML the preview page shows and edits. |
edit_design | Find-and-replace edits to that document. All of them land or none do. |
write_design | Replaces the whole document, for big restructures. |
get_fragment
Returns one component's files.
| Parameter | Type | Default | Description |
|---|---|---|---|
fragmentId | string | — | The id, as list_components reported it |
componentFormat | html | jsx | vue | svelte | as captured | Shape to return the component in |
styleFormat | inline | tailwind | as captured | How styling is carried |
offset | integer | 0 | Byte offset to read from |
maxBytes | integer | 262144 | Bytes 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
| Parameter | Type | Default | Description |
|---|---|---|---|
projectId | string | — | The project id |
includeFiles | boolean | false | Inline every component's full file contents |
offset / maxBytes | integer | — | 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
| Parameter | Type | Description |
|---|---|---|
projectId | string | The project to add this component to |
title | string | Short title, e.g. Pricing Card |
summary | string | One-line description of what was built (optional) |
files | array | { path, content } objects — the whole component |
create_project
| Parameter | Type | Description |
|---|---|---|
prompt | string | What the project is for, stored as its opening message (optional) |
get_guide
| Parameter | Type | Description |
|---|---|---|
topic | token-usage | extension-sync | fragment-authoring | library-export | canvas-editing | Which 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 for | Served |
|---|---|
| The format it was captured in | Exactly what was stored |
html, vue or svelte | Rebuilt from the stored markup |
jsx, on a component captured as React | Exactly what was stored |
jsx, on anything else | The captured format, with a notice — HTML→JSX conversion runs in the extension, not on the server |
A different styleFormat | The 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:
[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 see | What it means | What 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 appear | The 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 all | The 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 maxBytes | maxBytes outside 1,024–262,144. | Pass a value in range, or omit it. |
A notice about the format | The component can't be served in the shape you asked for. | See Formats. |
| The component came back restructured | That'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/mcpand accepts bothGETandPOSTwithstreamable-httptransport (MCP spec 2025-03-26).