Skip to main content
Glama

albato-builder-mcp

License: MIT Node.js 20+ 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_request output 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 install

2. 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.authToken

Your 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 Bash
Copy-Item .env.example .env     # PowerShell

Put 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 check

The 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 dryRun first, 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/mcp
claude 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 reviewId or planId returns "not found" for another user.

  • Finding dismissals are shared per app. The audit log records who made each change (user-<id>).

  • The apply_fixes confirmation (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

ALBATO_TOKEN

yes (stdio)

Token of the main account

ALBATO_BASE_URL

no

API address without /v1. Default: https://api.albato.com.

ALBATO_TOKEN_<NAME>

no

Tokens of additional accounts (see below)

ALBATO_BASE_URL_<NAME>

no

API address for that token, if it differs

ALBATO_CONTRACT

no

Path to builder-api.json. Default: contracts/builder-api.json

ALBATO_CREDENTIALS_CONTRACT

no

Path to credentials-api.json. Default: contracts/credentials-api.json

ALBATO_BUNDLE_CONTRACT

no

Path to bundle-api.json. Default: contracts/bundle-api.json

ALBATO_STATE_DIR

no

Where dismissed findings and the fix audit log are stored. Default: .state

MCP_HTTP_HOST

no

HTTP mode: address to listen on. Default: 127.0.0.1

MCP_HTTP_PORT

no

HTTP mode: port. Default: 8787

MCP_ALLOWED_HOSTS

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

list_apps (with name search), get_app_tree (a whole version, with technical checks), ensure_editable_version

Read

list_entities (a projection by default, plus full, expand and pick), get_entity, get_entities (batch read)

Write

create_entity, create_entities (batch, where "$N" refers to entities created earlier in the same batch), update_entity, update_entities (batch), sort_entities, copy_entity, restore_entity, delete_entity

Schema

describe_resource: fields, allowed codes and notes the contract doesn't cover

Testing

test_request (runs one request through a live connection), check_response_mapping (compares the mapping with a sample response, offline), run_credential_wizard (runs the multi-step connection wizard the way a bundle does)

Connections

list_credentials, describe_credential, create_credential, update_credential, refresh_credential, test_credential, delete_credential

Review

review_version, diff_versions, dismiss_finding, plan_fixes, apply_fixes, revert_fixes

Publication

submit_for_moderation, share_version, list_categories

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_entity and test_request do nothing without confirmed: true. Without it, delete_entity shows 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 marked deprecated.

  • 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 call ensure_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 variable

    • status 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 id is 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_request masks 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 WorkspaceId header 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

PUB-GEN, PUB-NAME, PUB-FLD, PUB-ACT, PUB-TRG, PUB-ENUM, PUB-SORT, PUB-CAT, PUB-CRT, PUB-VAR, PUB-MIG

Publication rules: naming, descriptions, fields, ordering, categories, item creators, variables, migration

PUB-UPD

Updating a public version. Users' bundles move to the new version automatically, so a breaking change is a blocker

TECH-*

Technical checks: async, pagination, webhooks, wizard, nesting, keys, variables, status handlers, migration

HYG-*

Hygiene

  • Classes.

    • auto and heuristic rules are checked by the server. A heuristic finding always includes why.

    • judgment rules 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 the review-publication prompt.

  • Verdict. The server's verdict is either blocked or no_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:

  1. review_version returns findings and a reviewId.

  2. plan_fixes turns them into numbered items. Each item shows "before → after", a risk level and a kind.

  3. You answer, and apply_fixes applies only the items you picked.

    • Items marked breaking or destructive are 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.

  4. After applying, recheck reports which findings were closed, which remain and which are new.

  5. revert_fixes restores 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. Without confirmed, 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 in missing.

    • 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. Without confirmed, 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 to info against 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

review-publication

appId, versionId?, apiDocs?

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

review-against-task

appId, task, versionId?

compare what was built with the task

A "requirement – ✅/⚠️/❌ – where" table, extras beyond the task, and rule findings

changes-since-public

appId

see what users will get

Breaking changes first, then an "added / changed / fixed" changelog

moderation-reply

appId, versionId?

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.json covers the Builder resources.

  • credentials-api.json covers account connections.

  • bundle-api.json covers the bundle wizard, which run_credential_wizard uses.

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.mjs
  • Validation runs in two layers. The contract schema checks the shape and the allowed codes. Semantic rules in src/*.mjs catch the cases the API accepts silently but that fail later in a live bundle. The TECH-* 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 meta at 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

ALBATO_TOKEN is not set

The server didn't find a token

Make sure the file is named exactly .env (not .env.txt), is in the repository root, and has a non-empty ALBATO_TOKEN= line

looks like a token problem

The API returned 401 or 403

Get a new token (see Get a token)

environment is unreachable from this machine

Network error or timeout

Check ALBATO_BASE_URL: no typos and no /v1 at the end

server did not start

Missing dependencies, an old Node.js version, or contracts not found

Run npm install, check node --version, and make sure contracts/ is in place or that the ALBATO_*_CONTRACT paths are correct

No albato-builder tools in the client

The client didn't start the server

Make sure the path in the config is absolute and points to src/server.mjs, then restart the client

"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 ensure_editable_version

Known limitations

  • Requests are tested one at a time. The API can't run a whole trigger or bundle. Requests in receivingRequests run when a connection is saved, so a token-retrieval request can't be tested on its own with test_request.

  • Apps can't be deleted through the API. The apps resource supports only list, get and create.

  • Status handler order. Version-level status handlers can't be reordered through the API.

  • responseData from a test run holds a single element, even when the request returns a list and pathToArray is set.

  • expand: "rowSections" returns row sections without their fields. Use expand: "rowSections.fields".

  • No OAuth in HTTP mode yet. You pass the Bearer token in a header.

License

MIT

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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 npm
      MIT
    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables 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
    • A
      license
      Not graded
      quality
      B
      maintenance
      Exposes 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
    • A
      license
      B
      quality
      B
      maintenance
      Enables 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.
      41
      1
      MIT