Your agent, in your workspace.
Baselumen runs an MCP server with 32 tools. Point the agent you already use at it, sign in, and it can search the library, build your own components, pin them to Stacklumen Terminal sites and edit designs. No AI key is stored here: your agent runs on your own plan.
Sign in from your agent. Nothing to paste.
Add the endpoint to your agent as a remote MCP server or connector. The first time it connects, it is sent to sign in with your Stacklumen account, where you allow access. No token to copy and nothing to paste.
-
Your agent calls the server
With no credential yet, the answer is 401, and its WWW-Authenticate header says where to sign in and which scopes to ask for: components:read components:write clients:read account:read account:write.
-
It reads the server's metadata
GET /.well-known/oauth-protected-resource/app/api/mcp names the suite's one sign-in as the place tokens come from. One sign-in serves every Stacklumen app.
-
You sign in and allow access
With your Stacklumen account, in your browser. Your agent gets a token for Baselumen's scopes only, so it opens nothing in another app.
-
Your agent works
Each call is checked: you still own the workspace, it is not suspended or locked, and the tool's scope was allowed.
- Endpoint
- https://baselumen.com/app/api/mcp
- Transport
- MCP over HTTP, JSON responses; every request is authenticated afresh
- Who
- The workspace owner. The connection is tied to the workspace you own when it first connects
- Metadata
- https://baselumen.com/.well-known/oauth-protected-resource/app/api/mcp
Or give it a token. Only the doors it needs.
An agent that cannot sign in, a build job and the CLI use a bl_ token instead, sent as a bearer Authorization header. The workspace owner makes them under Agents & MCP, and each one is shown once.
- Name. Who holds it, so the table and the activity say which agent did what.
- Reach. The whole workspace, or one client: a client token sees only that client.
- Scopes. Everything, including tools added later, or any of the 7 scopes.
- Expires. Never, in 30 days, in 90 days or in a year.
- Stored. As a hash; the table shows the last four characters. Revoke it, and every agent holding it loses access on its next request.
New token
7 scopes. Each with its tools.
A scope is what a credential may do. Every tool spends one, and a call without it is refused with a sentence naming the scope, so your agent can tell you what to grant. whoami needs none.
32 tools, listed where you make the token.
The Tools panel on Agents & MCP and the server's own tool list are drawn from the same definition, so the page cannot promise a tool the server does not offer. 11 of them change your workspace; the rest only read.
Components and templates
Search the library, fetch a component in the build you use, and fetch whole templates.
- search_components components:read
Search the Baselumen component catalog by name, slug, description or category. Returns slug, name, category, status, the surfaces each component ships as (html, react, vue, svelte), `free` for the components every plan can fetch, and, for a premium component, its `price` and whether this workspace `owned` it. Fetch source with get_component.
- get_component components:read
One component's source for a surface. 'html' returns the canonical HTML plus CSS pair; 'vue' and 'svelte' are generated from that same pair; 'react' is the typed React build. A fetch through this tool IS a copy, recorded exactly as copying from the app is. On the Free plan only components marked `free` in search_components can be fetched; Pro and Agency include every component except premium ones, which any plan fetches once the workspace has bought them (owned: true).
- list_templates components:read
The site templates — whole multi-page Astro sites, as opposed to the single components search_components lists. Returns each template's slug, name, tagline, description, accent colour, light/dark tone, its price, whether this workspace owns it, its pages, and how many files and bytes it carries. Templates are sold once per workspace in the Baselumen marketplace; browsing is open to everyone, get_template is the fetch.
- get_template components:read
One template's complete source tree — every .astro page, the components, the stylesheet, the public SVGs and the project files — as a list of {path, content}, ready to write into a folder. The paths are relative to the template root, so writing them under a directory named for the slug reproduces the project exactly. A fetch through this tool IS a copy, recorded exactly as downloading the zip from the app is. Only templates this workspace owns (owned: true in list_templates) can be fetched, on every plan; the rest are bought once per workspace in the Baselumen marketplace.
- list_design_tokens components:read
The design system's CSS custom properties — colour, type, radius, shadow, motion — read from the canonical stylesheet (src/styles/sl-design-system.css). Baselumen has no separate token API; this stylesheet is the source the whole app draws from, so these values cannot drift from what components render with.
Component Studio
The workspace's own custom components: read them, write new ones, edit them, or fork one from the library.
- list_custom_components components:read
The workspace's own custom components — id, componentId (custom:<uuid>, what pins use), name, category, the library component it was forked from, preview tone and dates. No source; fetch one with get_custom_component.
- get_custom_component components:read
One custom component with its full markup and css, ready to edit with update_custom_component.
- create_custom_component components:write
Save a new custom component to the workspace. Markup and css are sanitised on the way in; 256 KB each, 500 components per workspace.
- update_custom_component components:write
Edit a custom component. Pass any of name, category, previewTone, markup, css to replace them whole, and/or `replacements` for targeted edits: each {in: 'markup'|'css', find, replace} replaces every exact occurrence of `find` and fails if it is absent.
- fork_component components:write
Save a library component as a new custom component (its HTML and CSS, rendered from the library), ready to edit with update_custom_component. It follows the plan as get_component does: the Free plan can fork the free set, and a premium component must be bought first. A fork is not recorded as a copy.
Sites and pins
Put components on a Stacklumen Terminal site's designer shelf, ready to drop onto its pages.
- list_sites components:read
The workspace's Terminal sites — id and name — that components can be pinned to.
- get_site_pins components:read
The components pinned to a Terminal site's designer shelf.
- pin_components components:write
Push components to a Terminal site: pins them to that site's designer shelf, where the designer can drop them onto pages. Adds to what is already pinned. Accepts library slugs and custom componentIds (custom:<uuid>).
- unpin_components components:write
Remove components from a Terminal site's designer shelf. Pages that already use them keep them.
Designs
The design library and the designer's own drawing operations, and pushing artwork to a Terminal site.
- list_designs components:read
The workspace's design library, most recently touched first: id, name, client, trim size in mm, status and when it changed. No artwork; fetch one with get_design.
- get_design components:read
One design: its full document (artboard in mm, trim and bleed, every shape) and, unless svg is false, its artwork as SVG. Shape ids here are what edit_design operations name.
- list_design_operations components:read
The designer's drawing operations — add_shape, update_shape, set_paint, set_type, arrange and the rest — with each one's input schema. edit_design applies a batch of them.
- list_presets components:read
The artboard sizes (business cards, letterhead, logos, social, A-sizes) and the templates a new design can start from.
- create_design components:write
Start a new design on a preset artboard (blank) or from a template, save it to the library, and return its document. Draw on it with edit_design.
- edit_design components:write
Apply a batch of the designer's operations to a design and save it as one revision — the same edits the designer makes, in the same order. Operations: add_shape, update_shape, set_paint, set_effects, group_shapes, arrange_shapes, combine_shapes, path_command, transform_shapes, set_type, delete_shape, reorder_shape, set_artboard, set_document (schemas from list_design_operations). The batch stops at the first operation that fails, and nothing is saved then. An open designer tab picks the change up when it next loads the design.
- push_design components:write
Send a design's artwork to a Terminal site's assets. propose (the default) records what would happen and changes nothing; execute writes it.
- list_pushes components:read
The push log — what was sent where, proposed or executed, and how it went — newest first.
- list_assets components:read
The workspace's uploaded assets — images and SVGs the designer can place — with their URLs.
Account and clients
What the credential may do, your profile and settings, the workspace, its members and its clients.
- whoami no scope
The workspace this token belongs to, the token name, its scopes, and its reach (whole workspace or one client). Call this first to learn what the credential may do.
- get_profile account:read
Your profile in the suite — name, handle, headline, bio, job title, location, links, skills and whether it is public.
- update_profile account:write
Update your profile. Pass only the fields to change: fullName, handle, headline, bio, jobTitle, location, pronouns, timezone, links, skills, isPublic. links is merged into the links you have: give a network an address to set it, an empty string to remove it, and leave the rest out to keep them. skills replaces the whole list.
- get_settings account:read
Your settings — theme, density and which emails you receive.
- update_settings account:write
Update your settings. Pass only what changes: theme, compactDensity, emailActivity, emailSupport, emailProduct.
- get_workspace account:read
The workspace — name, kind, industry, size, description — and its members with their roles.
- update_workspace account:write
Update the workspace's details. Pass only what changes: name, industry, companySize, description.
- list_members account:read
The workspace's members and pending invitations, with roles.
- list_clients clients:read
The workspace's clients — id, name, slug, website, status, industry. A client-scoped token sees only its own client.
The star in the app bar. Connect from any screen.
The star beside search opens the Agent panel on every screen. It does not hold a conversation and never asks for a key: it shows the server URL and the three steps to connect, and links to the token page and the docs. The conversation happens in your agent; what it changes shows up here.
- Stays open while you work, so the steps are on screen as you follow them.
- Closes with the star, its close button or Escape.
- The same panel in Stacklumen's Hub and Terminal, pointed at each app's own server.
The baselumen CLI. The same server, from your terminal.
Log in once with a token, then search, add components as files you own, and scaffold whole templates. Every command takes --json.
- login, whoami
- Store a token after checking it, and say what it may do
- list, search
- The catalogue, with --category to narrow it
- add
- A component into ./components: react by default, or --surface html, vue or svelte
- templates, template
- List the templates, or write one into its own folder
- tokens, clients
- The design tokens and the client list
- mcp
- A local MCP server for your agent, with one more tool that writes a component into the project
- init
- Brief a coding agent working in the folder on these commands
In active development. The CLI is not released yet. More about the CLI.
Agents edit designs with the designer's own tools.
edit_design applies a batch of the same 14 drawing operations the designer uses, in order, and saves the result as one revision with the agent's note. If any operation fails, nothing is saved.
- list_design_operations gives the agent each operation and its inputs.
- Up to 200 operations in one batch.
- The revision is marked as an agent's in History, and Restore brings back any earlier one.
- push_design proposes first and writes to a Terminal site only when asked to.
The same rules as the app. Agents work as you.
An agent works as you, within what you granted, under the limits the app keeps.
- Owners
- Only the workspace owner's tokens and sign-ins are accepted. A token stops working if its maker is no longer the owner
- Copies
- get_component and get_template are recorded as copies, exactly as copying or downloading in the app is
- Plans
- Fetching follows the plan: Free fetches the free set, Pro and Agency fetch everything; bought items open on any plan
- Limits
- 60 requests a minute from one address, and 120 a minute per workspace, shared by all its tokens
- Locked
- A suspended workspace, or one locked for billing, refuses an agent's changes as it does yours
- Keys
- No AI key is stored for any workspace; your agent runs on your own plan
The smaller pieces. Each one says what happened.
-
The star, pressed
The only time the star takes the brand colour is while its panel is open.
-
The sign-in challenge
A call with no credential gets a 401 that names the metadata and the scopes to ask for.
-
whoami
Any live credential may ask what it is: the workspace, its name, its scopes and its reach.
-
A refusal that says why
A missing scope comes back as the tool's answer, naming the scope to ask the owner for.
-
Propose, then push
push_design records what it would do and changes nothing until it is called with execute.
-
Revoke
One confirmation, and every agent holding the token is out on its next request.
How it connects. One catalogue, every door.
- Agentic building Where this is going: the goals behind the library, the designer and hosting, for agents.
- Components The catalogue search_components and get_component read, in every build.
- Templates Whole sites list_templates and get_template hand over.
- Design The design library and designer the design tools draw in.
- CLI The baselumen command, its options and its local MCP server.
Connect your agent. Sign in, or make a token.
Copy the endpoint into your agent and sign in, or make a token for the CLI.