pomerado/pomerado

Pomerado

Turn websites into MCP integrations your agent can rely on.

How it works · Get started · Create an integration · Use your integration · Open source and Cloud · Docs · Contributing

---

What Pomerado does

Pomerado builds MCP integrations for websites, including sites without an API.

• Our tool builds integrations with only a natural language description of the task. No HAR file or recording is needed
• Integrations are deterministic, making them much faster and more reliable than computer use
• Pomerado works on sites behind a login and two-factor authentication

How it works

┌──────────────────────────────────────────────────────────────────────────┐
│  explore the site → complete your example → generalize → agent calls it  │
└──────────────────────────────────────────────────────────────────────────┘

For more details, see How it works.

Get started

Prerequisites

• macOS or Linux
• Node 24.21 or a later Node 24 release, which you can check with node --version
• An OpenAI API key, since Pomerado uses OpenAI models to build and review integrations. Your agent can run on any model
• An MCP client that runs local servers, such as Claude Code, Codex, Cursor, VS Code, Claude Desktop or Gemini CLI

Install Pomerado and the Chromium build it drives.

npx -y -p pomerado pomerado-mcp --help
npx -y -p pomerado playwright install chromium

On Linux, add --with-deps after install if Chromium’s system libraries are missing.

Pomerado runs as a standard MCP stdio server. Clients that read an mcpServers file use this entry.

{
  "mcpServers": {
    "pomerado": {
      "command": "npx",
      "args": ["-y", "-p", "pomerado", "pomerado-mcp", "mint", "--root", "/absolute/path/to/pomerado-integrations"]
    }
  }
}

• --root sets the folder where Pomerado saves your integrations. Use an absolute path, because each client starts servers from its own working folder
• The server reads OPENAI_API_KEY from its environment, so the key never needs to appear in chat
• Starting the server and listing its tools costs nothing. It launches no browser and calls no model until you start a mint

Add Pomerado to your client with the command or file below.

Each client passes environment variables its own way. Client settings covers the key and the timeouts for every client above.

To confirm the setup, ask your agent which Pomerado tools it has. It should list mint, get_job, provide_input and cancel_job.

Let your agent set it up

If you’d rather not run these steps yourself, paste this into your agent.

Set up Pomerado for me by following https://raw.githubusercontent.com/Pomerado/pomerado/main/docs/agent-setup.md

Your agent checks your Node version, installs Chromium and adds Pomerado to the client it runs in. It asks before changing anything you didn’t mention, and it never asks for your API key in chat.

Create an integration

Ask your agent to create an integration with Pomerado. We call this minting. A good request names the site, describes the task in plain language and says whether the integration should only read or also make changes.

Use Pomerado to create an integration named example_reader that reads the main heading from https://example.com. Keep it read-only.

Your agent runs the mint with four tools.

• mint starts a job from a name, a URL, a task, an optional example input and read or write authority. It returns a job ID right away
• get_job waits up to 30 seconds for progress, a question or the result. Checking a job never restarts the work
• provide_input sends your answer when Pomerado asks a question. Pomerado checks the answer against the question’s format
• cancel_job stops the job and closes its browser. An action already sent to a website may still have taken effect

Authority decides what an integration is allowed to do, so choose it deliberately. Your agent picks one when it calls mint, and the tool tells it to ask you before choosing write.

• Use read when the task only looks at a website
• Use write only when the task changes something, such as submitting a form or making a booking
• A write mint performs the action once while it builds, then reviews the final source without repeating it
• A read mint that finds the task needs a change asks to switch to write, and your agent’s answer decides
• A run doesn’t check authority or intent, and edits to src/ or deployment.json aren’t reviewed. A run that signs in replays its sign-in only on the site and its sign-in origins. A served call takes them from deployment.json, and pomerado run --artifact from pomerado.json

Some sites sign in through a script that sends your login to another website, such as a hosted identity service. Pomerado then asks you once whether the site signs in through that address, when there are one to three such https addresses. Until your password or a code has been sent anywhere, it asks only when there’s one. Yes trusts it for signing in only and saves it with the integration. No stops the mint without saving anything. To trust it up front, or to trust one Pomerado doesn’t ask about, pass it in authenticationOrigins when you call mint.

Names start with a lowercase letter and use only lowercase letters, digits and underscores. The integration’s folder must not exist yet. Each mint gets 20 minutes of active work, and time spent waiting for your answers doesn’t count against it.

Use your integration

When minting finishes, Pomerado saves the integration as a folder of source code and returns its paths.

pomerado-integrations/example_reader/
├── src/                 Generated operation modules
├── pomerado.json        Entrypoint, input and output schemas, and the questions a run may ask
├── auth-fill.json       Sign-in screens a build that signed in recorded, with no value
├── deployment.json      Tool name, description, URL, task, authority and sign-in origins
├── mcp.mjs              Launcher for the shared Pomerado runtime
├── mcp.json             Standard MCP server entry, with no key
└── README.md            Add commands for each MCP client

1. Open the integration’s README.md. It has the add command for each major client with your paths already filled in
2. Add the server with that command. Skip the key setup. Running an integration makes no model request, so only minting needs OPENAI_API_KEY
3. Reload your client and ask your agent to use the integration

Use example_reader to read the page heading.

Each integration appears to your agent as its own MCP server.

• It has one tool named after the integration, with its arguments under input
• It also has get_job, provide_input and cancel_job for calls that need an answer or more time
• A call returns output that matches the schema in pomerado.json, or a job ID to follow up on
• A failed call returns a job with a code, write_status, possible_commit and retry. Read the site back before calling again when possible_commit is true
• An integration whose build signed in signs in on each call. It asks for the login, and any code or answer the site needs, and saves none of them
• The integration runs on the Pomerado installation that minted it. For a stable path, install globally with npm install -g pomerado and use pomerado-mcp in place of npx -y -p pomerado pomerado-mcp

Open source and Pomerado Cloud

This repository is the complete Pomerado core, released under the MIT license. Everything you need to mint integrations and run them yourself is here, with no Pomerado account required.

• The minter, which builds integrations in a real Chromium browser
• The minting harness and prompts
• Guardian, which reviews each browser action and the finished source while minting
• The standalone host, which serves each integration as an MCP server on your own machine
• The integrations themselves, saved as source code in your folder that you own

Pomerado Cloud runs this same core as a managed service. It adds the operations that production use needs.

• Hosting for your integrations and their jobs
• OAuth brokerage and saved logins
• Access control over who can use each integration
• A managed browser fleet that handles bot protection
• Breakage detection that notices when a site changes and repairs the integration automatically

Documentation for humans and agents

• docs.pomerado.ai has the full Pomerado docs, including Pomerado Cloud’s API and hosted MCP.
• Getting started covers install, client settings, a first integration and troubleshooting.
• Agent setup gives an AI agent the steps to install Pomerado for you.
• How it works covers the minter, Guardian, the runtime, jobs and the library.
• AGENTS.md tells coding agents how to change this repository.
• CONTRIBUTING.md covers building from source and how changes land.
• RELEASING.md covers how npm releases are built and verified.

Repository guide

How it works lists each module under typescript/src/.

Contributing

• Issues and pull requests are welcome.
• Pomerado is agent friendly. AGENTS.md gives your coding agent the setup and the rules.
• Alan or Akshay reviews every pull request before it merges.
• Everyone follows our code of conduct.
• Security problems go privately through Report a vulnerability on the Security tab.
• CONTRIBUTING.md has the steps to build, test and open a pull request.

License

Copyright © 2026 Pomerado AI, Inc. Licensed under the MIT License (MIT). See LICENSE.

Versions 0.1.2 and earlier were published under the GNU Affero General Public License version 3 only (AGPL-3.0-only).

Third-party code keeps its own license. The Guardian policy in typescript/src/guardian/upstream-policy.md is adapted from OpenAI Codex under the Apache License 2.0. Its license and notice are in third-party/codex/ and ship with the npm package.