Skip to content
Docs

Deploying with an agent

Let Claude Code, Codex, Cursor or any agent deploy, share and fix your Apps for you, with one line of setup and your own sign-in.

Basemodo is built to be driven by agents. Every command answers in JSON, every error names the exact fix, and the basemodo command serves itself to your agent as an MCP server (the local MCP), so the agent calls Basemodo's commands as tools instead of guessing at a terminal.

Set it up

  1. Sign in once, yourself, in a terminal: basemodo login (see Getting started). The agent uses this sign-in; it never sees a password.

  2. Add Basemodo to your agent:

    Claude Code

    Terminal window
    claude mcp add --scope user basemodo -- basemodo mcp

    Codex

    Terminal window
    codex mcp add basemodo -- basemodo mcp

    Cursor: add this to ~/.cursor/mcp.json:

    {"mcpServers": {"basemodo": {"command": "basemodo", "args": ["mcp"]}}}

    Any other agent that speaks MCP: run the command basemodo mcp as a stdio server.

  3. Ask it. For example:

    • "Deploy this folder to Basemodo and give me the link."
    • "Share it with ana@example.com and ben@example.com."
    • "The App is broken: read its logs and fix it."
    • "Add a done column to the tasks table of the App's database."
    • "Set the Stripe key as a Secret; here it is: ..."

An agent in the cloud: the remote MCP

An agent that runs somewhere without the basemodo command (a web app like claude.ai, a hosted coding agent) connects to Basemodo's MCP over the internet instead, at https://mcp.basemodo.com, and signs in as you in your browser:

Claude Code

Terminal window
claude mcp add --transport http --scope user basemodo https://mcp.basemodo.com

then /mcp in a session to sign in.

Codex

Terminal window
codex mcp add basemodo --url https://mcp.basemodo.com
codex mcp login basemodo

Cursor: in ~/.cursor/mcp.json:

{"mcpServers": {"basemodo": {"url": "https://mcp.basemodo.com"}}}

Any other client that speaks MCP over HTTP with OAuth works the same way: it finds Basemodo's sign-in from the MCP's answer, registers itself, and sends you to basemodo.com to approve it, naming itself and where it returns. Approve only an agent you just connected. It then acts as you until you revoke it on the Devices page, where it is listed under Agents.

Its tools are the same as the local MCP's, with two differences, since it has no folder of yours: tools that act on an App take the App's name (app), and deploy takes a GitHub repository (repository, as owner/repo, with branch and subdir if needed) instead of a path. The App is linked to the repository, its latest commit deployed, and every later push deploys too, as in Deploying from GitHub; Basemodo's GitHub App must be able to read the repository, and when it cannot, the error's fix is the link to install it.

What the agent can do

Each command of the CLI is a tool of the same name (env set is env_set), with the same arguments, answering what the command prints with --json. The CLI lists them all and says which ones only read (clients may run those without asking you) and which change things. A few stay in the terminal, like basemodo login, which needs you at your browser: the agent asks you to run it.

The MCP also serves a guide, the resource basemodo://guide: the commands, the manifest and the identity headers in one page, written for agents. The agent reads it once and knows how to use Basemodo without searching the web. For more, the tool docs reads any page of this documentation.

An agent without MCP

An agent that only runs terminal commands uses the same CLI: tell it to add --json to every command. To teach it the rules, give it basemodo docs, or point it at /llms.txt: the whole documentation in one Markdown file, the same text as these pages.

The rules an agent follows

  • The CLI. basemodo <command>. Every command takes --json: the result is one JSON document on stdout, an error is {"error": {"code", "message", "fix", "docs"}} on stdout with a non-zero exit, and a command that takes a while reports progress as JSON lines on stderr ({"event": "progress", "stage", "message"}). The fix names the exact command or basemodo.toml line that fixes the error, and docs the page that explains it.
  • The local MCP. basemodo mcp serves the guide (the resource basemodo://guide) and one tool per command, signed in with the CLI's login. A tool's name is the command's words joined by _ (env set is env_set); its arguments are the command's, named as the guide and the docs name them; its result is exactly what the command prints with --json, and a failure is an error result carrying the same {"error": ...}. A Deploy's stages arrive as MCP progress. Add it with claude mcp add --scope user basemodo -- basemodo mcp (Claude Code), codex mcp add basemodo -- basemodo mcp (Codex), or {"mcpServers": {"basemodo": {"command": "basemodo", "args": ["mcp"]}}} in ~/.cursor/mcp.json (Cursor).
  • Signing in. basemodo login, run by the person in a terminal, signs the CLI and the local MCP in. When a tool answers not_signed_in, ask the person to run it.
  • Which App. Commands that act on an App take app (--app); without it, the App named after the current folder, as deploy names it. A name means the person's own App of that name, else the one other App of that name they work on (a Workspace's, or one they are an Editor of); an App's slug (the label in its URL) names it when the name is ambiguous.
  • Owners and Editors. The person signed in may work on their own Apps and on the Apps whose Owner made them an Editor: deploy, logs, Secrets (env), status and rollback, backup and backups work the same on both. Only the Owner changes who can reach an App (share), restores a Backup (restore, which overwrites its data), downloads its data or deletes it; an Editor gets owner_only. Each App's role says which it is.
  • Workspaces. An App is owned by a person or by a Workspace (a team). Every Admin of a Workspace manages all of its Apps (deploy, Logs, Secrets, sharing) and the App hears them as owner; its other Members do not manage them, unless made Editors. deploy --workspace <name> deploys to that Workspace's App, created the first time (only an Admin can). People, company domains and moving a person's App into a Workspace (which an Admin accepts; whoever moved it stays its Editor) are managed on basemodo.com, not here.
  • The documentation. Everything here and more, with examples: the tool docs (basemodo docs, one page with a topic: basemodo docs manifest), or https://basemodo.com/llms.txt.

Staying in control

The agent acts as you, with your sign-in: it can do what you can do. You see every device signed in as you on the Devices page of basemodo.com, and revoking the CLI's sign-in (or, for an agent using the remote MCP, the agent) there stops the agent at once. Tools that change things carry no "read only" mark, so a careful client asks you before running them.