Quickstart: deploy from Claude Code

Deploy from Claude Code, Codex or Cursor in one session: connect the aidrop.it MCP server, push your code and get a live HTTPS address in minutes.

aidrop.it runs the apps your AI coding agent builds. Connect Claude Code, Codex or Cursor to https://aidrop.it/mcp, ask it to build, and it pushes the code and gives you a public HTTPS address in the same session.

You need an aidrop.it account: start free with a 7-day trial and no card. The trial covers one app and one PostgreSQL database.

1. Connect your agent

Sign up and name your Team on the first screen. Then add aidrop.it to your agent with the lines below. There is no API key to create or paste. The agent’s first call opens a consent screen in your browser, where you allow it to read and change your Services (the permissions, or scopes, are called service:read and service:write). You can revoke that access any time from Management → Connected apps.

Claude Code:

claude plugin marketplace add aidropit/plugins
claude plugin install aidropit@aidropit

Then start claude, run /mcp, pick aidropit and sign in.

Codex CLI (the desktop app and Codex in ChatGPT read the same configuration):

codex plugin marketplace add aidropit/plugins --sparse .agents/plugins
codex plugin add aidropit@aidropit

Cursor, Claude, or any other client that speaks MCP:

{ "mcpServers": { "aidrop": { "url": "https://aidrop.it/mcp" } } }

New to the term? What an MCP server is explains in plain words how an agent connects to a service like this one.

2. Ask for your first page

This is the fastest way to see the whole product. Copy this into Claude Code, Codex or Cursor and send it:

Build me an aidrop.it Service called "Bean Counter": a one-page launch site for a coffee subscription, with a hero showing the name and a line about the product, three subscription tiers as cards, and an email field that does not post anywhere yet. Write a Dockerfile for it, push it, build it on aidrop.it, and tell me when it is running.

Your agent hands you a URL. Open it and your page is there, on the internet, with a repository and a Service record behind it that outlive the conversation. For a longer walk-through of this exact case, read put a landing page online.

What just happened

Your agent read the request, proposed a shape and waited for your yes. aidrop.it then made a repository for the code, and the agent pushed to it. Next the agent called service_build with a Project, the Service’s name, that repository and the port the page is served on. That call creates the Service. The agent polled service_get until the build succeeded. A static site needs no database and no secrets, so the agent had no key to ask you for. Then it read you the address.

Your agent wrote the HTML, the CSS and the Dockerfile on your machine and pushed them with git. aidrop.it never writes source code. It keeps the repository, builds what was pushed and runs it. That split is the point: you can swap the agent, and the Service stays.

Decide how it builds. “Write a Dockerfile” is the one instruction in that paragraph that is not obvious, and skipping it is the most likely way for this to fail. With nothing said, the build is inferred: nixpacks, an open-source build tool, reads your repository and writes a Dockerfile itself. That is a guess nothing has checked. For a static site the inferred image writes to paths under /var, which cannot be written here: every container runs on a read-only filesystem with three small scratch folders. The image exits before serving anything, so the build goes green and the deploy still fails.

To build your own Dockerfile instead, commit it and have your agent pass build_type: dockerfile and build_dockerfile_path to service_build. A Dockerfile nobody named is never opened. After the first build, service_get returns a runtime_envelope: the rules every container runs under here and, for a named runtime kind, a Dockerfile written to follow them, ready to adjust.

Steps 3 to 5 are the same path one step at a time, for an app of your own. To plan something larger, with a frontend, a backend and a database, follow the checklist to build and deploy a full app with an AI agent.

3. Describe your own Service

There is no create call. A Service is made by its first service_build: named with a project_id and a name, that call creates the Service the first time and builds the same one every time after. Repeating it never leaves a second Service behind, and once you hold a service_id you pass that instead. The Project is the product the Service belongs to: projects_list finds one your Team already has, and project_create makes one for a new product.

So this step is a sentence to your agent. Nothing is written until the first build. Replace the description with your own before you send it.

Create an aidrop.it Service called "Support portal": an internal web app where support staff look up a customer and leave notes. Python API, React front end.

It reads that back to you and waits for your yes. Describe the product in your own words: the description is recorded on the Service, and it is what the next person or the next assistant reads to learn what this is.

The call your agent makes for it comes in step 5, once the code is in a repository. It names the Project, the Service, the repository and the port:

service_build(
  project_id: "5c1d…",
  name: "Support portal",
  repository_ref: "acme/support-portal",
  container_port: 8000
)

What comes back is the Service, created by this call, with its first build queued:

{
  "service_id": "8b3e…",
  "service_name": "Support portal",
  "build": { "id": "…", "tag": "3f9c1a2b4d5e", "commit_sha": "3f9c…", "stage": "created", "status": "running" },
  "tag": "3f9c1a2b4d5e",
  "repository": { "provider": "aidrop_git", "repository_ref": "acme/support-portal", "branch": "main" },
  "runtime_settings": { "container_port": 8000, "health_path": "/", "resource_class": "micro", "build_type": "nixpacks" },
  "next_step": "The build is queued and takes minutes. Poll service_get until its build status is succeeded or stopped …"
}

Two things worth knowing before you move on.

No repository comes with a Service. Repositories are your Team’s, not the Service’s. repository_create makes one in your Team’s own Git service. It starts empty, with no README or scaffold to collide with your first push, and it answers the HTTPS credential your agent pushes with. repository_get answers the same credential again later. The first service_build links the repository to the Service for good.

Nothing reads the shape out of your code. A Service is a name and a description. How it builds and runs is what your agent passes to service_build. If the app will keep data, it needs a database: ask shared_resources_list what your Project already runs before writing code that stores anything, because the app’s own disk is read-only.

4. Create the repository and push your first commit

Create a repository for it on aidrop.it and push what you wrote.

An agent with a shell and git does this itself: repository_create answers the repository and its credential, and the agent pushes. A chat-only client has no shell and cannot push. It can still build a repository you pushed to yourself.

If you did not ask for a Dockerfile, the build is inferred by nixpacks and the repository needs none. A Dockerfile of your own is used only when your agent names it with build_type: dockerfile and build_dockerfile_path, and it is then built as-is.

5. Build it

Build it on aidrop.it.

One call, service_build, with the repository to build from and the port your application listens on. The first call links the repository to the Service and records that port, a health path, a size (the memory and CPU the app gets, the smallest your plan includes unless the agent asks for more) and how the image is built. Every later build keeps them. You are never asked for an address. The deploy reserves one itself.

The build is queued and takes minutes. Your agent polls service_get until it reports a running application, and reads service_logs if it does not. Then it fixes the code, pushes, and builds again. That loop is the whole of deploying here.

{
  "build": { "stage": "deploy", "status": "succeeded", "commit_sha": "3f9c…" },
  "address": { "url": "https://app-36195f33.cbb.aidrop.cloud", "status": "active" },
  "application": { "running": true },
  "next_step": "Running at https://app-36195f33.cbb.aidrop.cloud — the address is open to anyone …"
}

What you get

An address like app-36195f33.cbb.aidrop.cloud, open to the internet from this first deploy. Anyone you give it to can open it, and nobody needs an aidrop.it account. service_get answers it, and it is on the Project’s page in the dashboard.

The name in it comes from the Service’s id, not from what you called the Service, so fixing a typo in the name never moves the address. When you want a memorable address, ask your agent for your own domain: service_domain_add answers the single DNS record to create, and service_domain_verify starts serving the name once it resolves. There is no screen for it. A custom domain needs the Pro plan ($20/month) or higher; see aidrop.it pricing.

If it does not build

Your agent reads the log with service_logs, and service_get says which stage stopped and why. Two things account for most failed first builds:

A missing secret. An application that reads DATABASE_URL and has none gets a URL to nothing. Secrets belong to the Project, and your agent stores them with project_secret_set after asking you for each value. The Project Secrets page in the dashboard lists their names, never the values. Each Service names the ones it reads in required_secret_names, and service_build refuses until every named secret is stored, before a build is spent.
Nothing listening on PORT. aidrop.it hands the container its port. An application bound to a fixed number is running and unreachable. A Dockerfile at the repository root is always the build path that works.

Push to the tracked branch again and build again.

Troubleshooting

A tool that refuses says why in a sentence your agent will read back to you. The ones you meet first:

Refusal	Usual cause
Not authenticated	The connection lapsed or was revoked. Reconnect from your client (`/mcp` in Claude Code)
Missing a scope	The connection was granted `service:read` but not `service:write`. Reconnect and approve both
Plan limit reached	Your plan already has as many Projects as it includes. Upgrade at app.aidrop.it/team/billing
Already builds from …	That Service already has a repository; a second repository is another Service
No repository yet	The first `service_build` needs `repository_ref`, from `repositories_list` or `repository_create`
No runtime settings yet	The first `service_build` needs `container_port`

Connecting a repository that already exists has two more refusals of its own, covered in deploy an existing GitHub repository.

Every answer carries a next_step saying what to do next, including the refusals. Following it is usually faster than reading this page twice.

What to build next

Each playbook is a paragraph to give your agent plus what to expect. Good next ones: a Telegram bot with Claude Code that answers 24/7 with your laptop closed, put your AI agent online with memory and a spending cap, or a landing page with its own domain and email signup. The rest are in all playbooks.

Next steps

Deploy an existing GitHub repository: the route for code you already have.
Build and deploy a full app with an AI agent: frontend, backend and database, decision by decision.
Service lifecycle: every build, rollback and stop, including what only a person can do.
Runtime templates: the shapes a Service can take, and what each one needs to run.
MCP server: every tool an agent gets, plus authentication and permissions.