albato-builder
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
albato-builder-mcp
Albato is a no-code integration platform: users connect apps into automations (bundles) without writing code. The Albato Builder is where developers add their own apps to the platform: connections, triggers, actions and lists, built on top of the app's API.
This is an MCP server for the Albato Builder API. Connect it to Claude Code, Claude Desktop or another MCP client, and the model can work with your Albato Builder apps directly. It can read a whole version, create and edit actions, triggers, lists and connections, test-run requests against the partner API, and check a version against the publication rules before it goes to moderation.
The server is built so the model cannot break anything by accident:
It writes only to the private version. It never touches the public version, a version shared by link, or a version under moderation.
Every write supports
dryRun. The server validates the body and shows it without sending it to the API.Deletions and request test runs need your confirmation in the chat. Fixes from a review are applied only to the items you pick.
Tokens never appear in tool responses or in the log. Secrets in
test_requestoutput are masked too.
Contents
Related MCP server: Apper MCP
Requirements
Node.js 20 or newer (
node --version)An Albato account token (JWT). See Get a token
An MCP client: Claude Code, Claude Desktop or any client that supports stdio servers. A Streamable HTTP mode is also available
Quick start
1. Install
git clone https://github.com/ermigut/albato-builder-mcp.git
cd albato-builder-mcp
npm install2. Get a token
The token is an Albato user JWT. The
POST /user/auth method
trades your email and password for a token. The token is in data.authToken of the response, and its
expiry is in data.authTokenExpirationDateTime.
macOS, Linux, Git Bash:
curl -s -X POST https://api.albato.com/user/auth \
-H "Content-Type: application/json" \
-d '{"email": "you@example.com", "password": "<password>"}'PowerShell (prints only the token):
$body = @{ email = "you@example.com"; password = "<password>" } | ConvertTo-Json
(Invoke-RestMethod -Method Post -Uri https://api.albato.com/user/auth -ContentType "application/json" -Body $body).data.authTokenYour shell history keeps a command that contains a password, so clear it afterwards. Tokens expire.
When npm run check reports a token problem, get a new one.
3. Add the token to .env
Copy the template to .env in the repository root:
cp .env.example .env # macOS, Linux, Git BashCopy-Item .env.example .env # PowerShellPut the token after ALBATO_TOKEN=. .env is listed in .gitignore. Never put a token in code or in
.env.example.
4. Check the setup
npm run checkThe check starts the server the way an MCP client does, lists its tools, prompts and rules catalog, and makes one read-only API call. It creates and changes nothing. A healthy run looks like this:
ok server responds: {"name":"albato-builder","version":"0.1.0"}
ok tools available: 34
ok apps in the account: 3
Result: everything is in place. The server is ready to be connected to an MCP client.Any problem is printed on a line that starts with FAIL, together with a hint (see
Troubleshooting). The script exits with code 1 when something fails, so you can
run it in CI.
5. Connect a client
You need the absolute path to src/server.mjs. The server reads the token from .env by itself,
so the client config doesn't need it.
Claude Code:
claude mcp add --scope user albato-builder -- node "/absolute/path/albato-builder-mcp/src/server.mjs"--scope user makes the server available in every project. Without it, the server is available only
in the current folder. Run claude mcp list to confirm the server is registered. If you use
--scope project, Claude Code writes the path to .mcp.json, which is listed in .gitignore.
Claude Desktop and other clients: add the server to the client config. For Claude Desktop, the
file is claude_desktop_config.json. It is in %APPDATA%\Claude\ on Windows and in
~/Library/Application Support/Claude/ on macOS.
{
"mcpServers": {
"albato-builder": {
"command": "node",
"args": ["/absolute/path/albato-builder-mcp/src/server.mjs"]
}
}
}On Windows, write the path with forward slashes, for example
C:/Users/me/albato-builder-mcp/src/server.mjs. Restart the client after you edit the config.
To keep the token in the client config instead, add an "env": { "ALBATO_TOKEN": "..." } block next
to args. It takes precedence over .env.
6. Try it
Example requests:
"Show my Albato apps"
"Go through app 12345: what's in it and what looks broken"
"Build a 'Create deal' action from this API documentation: ..." (the model shows the body with
dryRunfirst, then writes it)"Test-run the request of the 'Create deal' action" (the model asks first, because the request goes to the partner API through a live connection)
For reviews, use the review commands.
HTTP mode
Experimental. The HTTP mode works, but it's newer than the stdio mode and may change.
The same tools are also available over Streamable HTTP. This mode doesn't read tokens from .env.
Each user sends their own Albato token in Authorization: Bearer. The server identifies the user
through /user/profile and acts on their behalf.
npm run start:http # http://127.0.0.1:8787/mcpclaude mcp add --transport http albato-builder-http http://127.0.0.1:8787/mcp --header "Authorization: Bearer <token>"Each connection gets its own MCP session, with its own write log, review runs, plans and fix history. One user's
reviewIdorplanIdreturns "not found" for another user.Finding dismissals are shared per app. The audit log records who made each change (
user-<id>).The
apply_fixesconfirmation (elicitation) comes back in the tool call response, so it works with clients that don't open a separate GET stream. The server waits up to 10 minutes for an answer.OAuth isn't supported yet. The mode works with clients that let you set request headers yourself.
To listen on any address other than localhost, you must also set
MCP_ALLOWED_HOSTS, which protects against DNS rebinding. The server doesn't terminate TLS: put it behind a reverse proxy.
Configuration
You can set any variable in .env at the repository root, in the environment, or in the env block
of the client config. Values from the environment and the client config take precedence over the
file. .env.example lists every variable.
Variable | Required | Purpose |
| yes (stdio) | Token of the main account |
| no | API address without |
| no | Tokens of additional accounts (see below) |
| no | API address for that token, if it differs |
| no | Path to |
| no | Path to |
| no | Path to |
| no | Where dismissed findings and the fix audit log are stored. Default: |
| no | HTTP mode: address to listen on. Default: |
| no | HTTP mode: port. Default: |
| no | HTTP mode: comma-separated host names that clients use. Required when the server listens on anything other than localhost |
Use absolute paths. The server resolves a relative path from the folder the client started it in.
Multiple accounts. Each account needs its own token:
ALBATO_TOKEN=<main account>
ALBATO_TOKEN_PARTNER=<second account>When more than one token is set, every tool takes a token parameter with the lowercase name (here,
partner). The name in .env can use any case. Without the parameter, the server uses
ALBATO_TOKEN. A token can access only its own account, and tool responses and logs show only the
token's name.
Tools
The Builder exposes about 22 resources. Flat tools for each resource and operation would add up to
roughly 150, which is too many to fit in the model's context. Instead, the generic tools take a
resource parameter and validate the body against that resource's schema from the contract. Call
describe_resource before the first write to a resource.
Group | Tools |
Apps and versions |
|
Read |
|
Write |
|
Schema |
|
Testing |
|
Connections |
|
Review |
|
Publication |
|
The server also provides four MCP prompts (see Review commands) and the resource
albato://rules/publication, which holds the full rules catalog.
Built-in behavior
Confirmations.
delete_entityandtest_requestdo nothing withoutconfirmed: true. Without it,delete_entityshows what would be deleted, including child lists, wizard steps and fields that would lose their list. Deletion is permanent for entities created in the current version. Triggers and actions that also exist in earlier versions are only markeddeprecated.Editable version. Before each write, including a
dryRun, the server checks the version's status. If the version is closed, the error tells you what to do next: use the private version, or callensure_editable_version. That tool creates a new version only with your consent and with the name you give it. A new version copies the latest version in full, and its entity IDs match.Batches. For more than two reads, creates or edits, use the batch tools. They validate every operation before the first write and take one version lock. You can roll back a batch with
revert_fixes. There's deliberately no batch delete.Helpful validation. A validation error names the correct value instead of just saying "invalid". The server also catches mistakes the API accepts without complaint, for example:
a list request without pagination, or pagination that never changes the page
a webhook trigger without a Webhook connection field, a subscription without the URL, or a subscription without an unsubscribe request
a
{{systemVar.…}}substitution with no matching variablestatus handlers that overlap
wizard steps in the wrong order
broken field key syntax
async and migration setups that will never start
Nested arrays. When you send a nested array in an edit, the backend replaces the whole array. An element without an
idis created again, and an element missing from the array is deleted. The validator warns about this. To change one part, send only that part, for example{requests: [{id, response: {id, cfsMappings}}]}.Existing errors. An edit is rejected only for problems the edit itself introduces. A problem that existed before the edit produces a warning instead.
Test runs.
test_requestmasks authorization headers and parameters (Bearer <hidden: 82 chars>).It returns
responseAudit, which lists the response fields that have no mapping.It suggests a ready-made error handler built from the partner's real error response.
On a paginated request, it explains how to read the result: a bundle fetches every page, but you see only the last one.
Subscriptions are never recreated. Running bundles depend on a specific webhook subscription. The server rejects deleting a subscription that a trigger still uses and rejects replacing a trigger's
dataStarterId. Editing the subscription in place is allowed.Lists are fetched in full. The API returns 20 records per page, so the server pages through the rest for you.
Workspaces. The client sets the
WorkspaceIdheader itself, based on the app in the request.
Version review
A review checks the version as it currently exists in the account, not what was said in the chat. A version an agent built five minutes ago and one a partner built in the UI months ago are checked the same way. The same engine handles four scenarios:
self-check after a build (
scope: "session")publication readiness (
scope: "all")changes since the public version (
diff_versions,scope: "changed")a comparison with the task description
Rules
The rules are data, stored in rules/publication.yaml (73 rules). Each rule has a level (blocker,
warning, info), a class and a wording. The rule families are:
Prefix | Covers |
| Publication rules: naming, descriptions, fields, ordering, categories, item creators, variables, migration |
| Updating a public version. Users' bundles move to the new version automatically, so a breaking change is a blocker |
| Technical checks: async, pagination, webhooks, wizard, nesting, keys, variables, status handlers, migration |
| Hygiene |
Classes.
autoandheuristicrules are checked by the server. A heuristic finding always includeswhy.judgmentrules are not decided by the server, which never calls a model. Instead, it returns a question and a data packet (include: ["packet"]), and the host model makes the call by following thereview-publicationprompt.
Verdict. The server's verdict is either
blockedorno_auto_blockers. It never says a version is "ready".Response budget. If one rule has more than 10 findings, the extra ones are collapsed into
truncated, and blockers come first.App text is data. Names, hints and scripts from the app are marked as user content, and the server never follows instructions found in them. Secrets in reports are masked.
Apps in several languages
A version's languages come from the version itself (languages), and every name and hint check runs
for each of them: a name missing in one language, a lowercase name, a translation copied from the
English one. titleEn is always required; the other languages follow the app.
Review, plan, apply
A review is read-only. Fixes go through a separate chain:
review_versionreturns findings and areviewId.plan_fixesturns them into numbered items. Each item shows "before → after", a risk level and a kind.You answer, and
apply_fixesapplies only the items you picked.Items marked
breakingordestructiveare left out of "all". They are applied only when you name their numbers explicitly (named).If an entity changed after the plan was made, its item is skipped.
An edit that would replace a whole array of objects isn't applied.
When the client supports elicitation, the server asks for consent in a client dialog, without going through the model.
After applying,
recheckreports which findings were closed, which remain and which are new.revert_fixesrestores the "before" state.
Every applied fix is written to .state/audit.jsonl.
False positives. You can dismiss a finding with dismiss_finding and a reason. A dismissal
applies to one rule, entity and field, and it's lifted automatically when the entity changes.
Dismissals are stored in .state/dismissals.json.
Self-check. The server's instructions tell the model to run review_version with
scope: "session" before it reports a build as done. You don't need to ask for it.
Publication
submit_for_moderation. Withoutconfirmed, the tool only assembles the moderation form and shows it.Missing fields are filled from the app's previous submission, the account profile and
info. Anything that can't be found is listed inmissing.The test password is masked.
The whole version is reviewed first. A version with blockers isn't submitted without a
reason. A recent full review is reused if the server hasn't written to the version since.Skipping the review (
skipReview+reason) is written to the audit log.
share_version. This gives access by link and doesn't need a review. Withoutconfirmed, it returns the link and explains what will happen. An app has one permanent link. Sharing makes the version final.list_categories. This returns the catalog categories. The server checks the categories you write toinfoagainst this list.
After you submit or share a version, it can no longer be edited.
Review commands
The server provides four MCP prompts. In Claude Code they work as slash commands: type / and the
start of the name. The full name is /mcp__albato-builder__<prompt>. Each prompt adds a ready-made
workflow to the conversation: which tools to call, which rules to apply, and what the report should
look like. None of them fixes anything on its own.
Command | Arguments | Use it to | You get |
|
| check a version before moderation | A verdict, blockers per entity (server findings and the model's judgment kept apart), warnings, and what couldn't be checked |
|
| compare what was built with the task | A "requirement – ✅/⚠️/❌ – where" table, extras beyond the task, and rule findings |
|
| see what users will get | Breaking changes first, then an "added / changed / fixed" changelog |
|
| reply to the developer after a review | Per-entity text on what's wrong and how to fix it, without internal IDs or JSON |
? marks an optional argument. Without versionId, the latest version is used. apiDocs can be a
link to the partner's API docs, an OpenAPI spec or plain text. Without it, rules such as "covers as
many fields as the API has" are reported as "not checked" instead of "ok".
How it works
The server doesn't hard-code the API. It reads machine-readable API contracts that ship with the
repository in contracts/:
builder-api.jsoncovers the Builder resources.credentials-api.jsoncovers account connections.bundle-api.jsoncovers the bundle wizard, whichrun_credential_wizarduses.
At startup, the server derives resources and their JSON schemas from the endpoint paths and nested models, so there is no hand-written code per resource. The contracts are updated together with the repository when the API changes; don't edit them by hand.
contracts/builder-api.json ─> contract.mjs ─> tools.mjs ─> mcp-server.mjs ─> server.mjs (stdio)
registry, tool tools, prompts, http.mjs (HTTP)
schemas registry rules resource
│
└─> validate.mjs, rules.mjs, nesting.mjs, async.mjs, migration.mjs,
variables.mjs, keys.mjs, handler-order.mjs, versions.mjs ...
checks applied before every write
rules/publication.yaml ─> catalog.mjs ─> review-tools.mjs ─> snapshot.mjs, review.mjs,
tech.mjs, checks.mjs, diff.mjs, state.mjsValidation runs in two layers. The contract schema checks the shape and the allowed codes. Semantic rules in
src/*.mjscatch the cases the API accepts silently but that fail later in a live bundle. TheTECH-*review rules reuse the same code, so a warning on write matches the review finding word for word.Connections. Each app defines its own connection form, so the contract doesn't describe the body. The tools read the form from
metaat runtime and build the internal field names themselves. The model works with field codes.Testing is per request. The server test-runs one request at a time, and only with your confirmation. It doesn't run whole bundles, on purpose. A hook trigger needs a real event, an API trigger needs existing data, and an action creates real records in someone's account. The model can't set up any of that on its own. So the loop is: build with the tools, test each request with
test_request, then hand the result to the user.
Project layout
src/
server.mjs stdio entry point: tokens from .env, state in .state/
http.mjs HTTP entry point (Streamable HTTP, see remote.mjs)
mcp-server.mjs the server without a transport: tools, prompts, rules resource, elicitation
tools.mjs generic and specialized tools (no SDK dependency, tested offline)
review-tools.mjs review_version, diff_versions, dismiss_finding, plan/apply/revert_fixes
contract.mjs loads contracts, derives resources and schemas
client.mjs HTTP client: Bearer auth, response envelope, timeouts, custom verbs
env.mjs, access.mjs .env loading and token resolution
... validation, review and domain modules
rules/publication.yaml review rules catalog
contracts/ API contracts (builder, credentials, bundle)
scripts/check.mjs npm run check
scripts/measure.mjs npm run measure
test/ offline tests
.env.example settings template
.state/ local state: dismissals, audit log (gitignored)Development
Run everything from the repository root.
npm install
npm test # offline tests: no network or token needed
npm run check # client → server → API chain, read-only
npm start # stdio server (normally the MCP client starts it)
npm run start:http # HTTP server on http://127.0.0.1:8787/mcp
npm run measure -- <appId> [versionId] [--token=<name>] [--json]npm run measure walks a typical review path against a real app and reports the time and response
size (≈tokens) of each tool call. It's read-only. Run it before and after a change to compare how much
context the tools use.
When you change rules/publication.yaml, keep in mind that the tests won't accept an auto or
heuristic rule unless it comes with a case that violates it.
Troubleshooting
Start with npm run check. It tells a token problem apart from a network problem and from a missing
contract.
Symptom | Cause | Fix |
| The server didn't find a token | Make sure the file is named exactly |
| The API returned 401 or 403 | Get a new token (see Get a token) |
| Network error or timeout | Check |
| Missing dependencies, an old Node.js version, or contracts not found | Run |
No | The client didn't start the server | Make sure the path in the config is absolute and points to |
"The app version is not editable" | The target version is public, shared or under moderation | Use the private version, or ask the model to call |
Known limitations
Requests are tested one at a time. The API can't run a whole trigger or bundle. Requests in
receivingRequestsrun when a connection is saved, so a token-retrieval request can't be tested on its own withtest_request.Apps can't be deleted through the API. The
appsresource supports only list, get and create.Status handler order. Version-level status handlers can't be reordered through the API.
responseDatafrom a test run holds a single element, even when the request returns a list andpathToArrayis set.expand: "rowSections"returns row sections without their fields. Useexpand: "rowSections.fields".No OAuth in HTTP mode yet. You pass the Bearer token in a header.
License
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Related MCP Connectors
Manage Meta apps: creation, configuration, webhooks, permissions, compliance, and App Review.
Set up and check AppBox apps: setup status, builds, devices, guides, tester-only test pushes.
Manage brainCloud apps, cloud code, hooks and servers; API lookups to help generate client code.
Governed MCP gateway for business apps: roles, previews, approvals and one audit log.
Related MCP Servers
AlicenseNot gradedqualityCmaintenanceEnables MCP clients such as Claude Desktop and Cursor to read tracked app keywords, opportunities, account apps, and action plans; generate or translate listing copy; review results; and apply accepted title, subtitle, keywords, or short-description fields to an editable draft without publishing to Apple or Google.38 npmMIT- AlicenseNot gradedqualityNot gradedmaintenanceEnables AI assistants to build and update complete applications, including creating, updating, publishing, previewing, and configuring databases, security, permissions, and server-side integrations.Apache 2.0
- AlicenseNot gradedqualityBmaintenanceExposes 20 read/write tools that let IDE and agent users search the interface catalog, build and validate flow-model JSON, import OpenAPI specs, run ETL tasks, and plan or revoke service permissions on RestCloud-compatible integration platforms. Writes default to dry-run and every call is written to a desensitized jsonl audit trail.MIT
- AlicenseBqualityBmaintenanceEnables managing a Google Play Console app directly from an MCP client: inspecting and shipping releases and staged rollouts, uploading bundles and deobfuscation files, reading Android vitals and anomalies against Google's thresholds, handling reviews and replies, editing store listings and images, managing testers, and checking Digital Asset Links for Trusted Web Activities. Writes are enabled but guarded with dry runs, validate-only edits, and explicit production confirmation.411MIT