Quickstart · aidrop.it Docs

Describe what you are building, push the code, and get it running at an address you can open.

A Service is one deployable piece of a Project — a repository, a runtime, an address and the record of what was done to it — kept together so the work survives whoever, or whatever, did it last. The Project is the product the pieces make up.

This page starts from nothing and ends with an application answering at an address. Four steps, and you are not asked to choose an address or a stack from a menu you have no basis to judge — only the port your application listens on.

All you need is an MCP client. There is no API key to create and nothing to paste: aidrop.it is reached over MCP, and connecting is a browser consent screen your client opens for you.

1. Connect your agent

Sign up at aidrop.it (free) and name your Team on the first screen — then point your client at the server. The first call opens a consent screen where you approve service:read and service:write for your Team; nothing is copied by hand, and you revoke it from Management → Connected apps whenever you like.

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

Anything else that speaks MCP — Cursor, Claude, your own client:

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

Try it: a page on the internet, from one paragraph

If you connected an agent above, this is the whole product in five minutes. 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 — a hero with 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.

Then it hands you a URL. Open it and your page is there — on the internet, from a paragraph, with a repository and a Service record behind it that outlive the conversation.

What just happened

Your agent read the ask, proposed a shape and waited for your yes. On its word aidrop.it made a repository to push to; the agent pushed, then called service_build naming a Project, the Service’s name, that repository and the port the page is served on — the call that creates the Service — and polled service_get until the build succeeded: a static site, meaning no database, no values, nothing for you to fill in. 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 holds the Service, keeps the repository, reads what landed, judges whether it can run it, and runs it. That division is the point — the agent is replaceable and the Service is not.

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 reads your repository and writes the Dockerfile itself, and an inference is a guess about your repository that nothing has checked. For a static site the inferred image writes and chowns its paths under /var, which does not exist here: every container runs on a read-only root filesystem with three small scratch mounts and no capabilities. It 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. Once the first build has recorded the Service’s settings, the runtime_envelope in service_get carries the rules a container has to run under here and, for a named runtime kind, a Dockerfile written for them, ready to adjust for the next build.

The rest of this page is the same path, one step at a time.

2. Start a new 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, and nothing about the Service’s shape is decided yet.

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 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 4, 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: "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 reading 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 — created empty, no README, no scaffold, nothing to collide with your first push — and 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 has decided the shape yet, and nothing will read it 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 it will keep state it needs a database — ask shared_resources_list what your Project already runs before writing code that stores anything, because the runtime filesystem is read-only.

3. Create the repository and push your first commit

Decide how it builds before you push. With nothing passed, the build is inferred by nixpacks and your repository needs no Dockerfile; a Dockerfile of your own is used only when your agent names it — build_type: dockerfile with build_dockerfile_path — and is then built as-is, with nothing inferred. After the first build, the runtime_envelope in service_get carries the rules a container runs under here and, for a named runtime kind, a Dockerfile written for them, meant to be adjusted to your layout.

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 — it can still work with a repository you pushed to yourself.

4. Build it

Build it on aidrop.it.

One call — service_build — with the repository it should build from and the port your application listens on; the first call links the repository to the Service for good, records that port, a health path, the smallest size your plan includes and how the image is built, and keeps them for every build after. You are never asked for an address. The deploy reserves one itself, because the address is derived and asking you for a prefix would put a decision you have no basis to make between you and a running application.

The build is queued and takes minutes. Your agent polls service_get until it answers a running application, and reads service_logs if it does not — then 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; 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 is derived from the Service’s id, not from what you called the Service — deliberately, because a name gets edited and an address that moves when someone fixes a typo is worse than an opaque one. When you want a memorable address, ask your agent for one: 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.

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 first builds:

A missing runtime value. An application that reads DATABASE_URL and has none gets a URL to nothing. Values belong to the Project — the Project Secrets page in the dashboard is where they go, or project_secret_set — and each Service names the ones it reads in required_secret_names. service_build refuses until a named value is stored, before a build is spent.
Nothing listening on PORT. The runtime hands the container its port; an application bound to a literal 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 grant carries `service:read` but not `service:write` — reconnect and approve both
Plan limit reached	The plan’s Project slots are used up — app.aidrop.it/team/billing
Already builds from …	That Service already has a repository; a second one 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 of its own — see Bring a Service.

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

Next steps

Bring a Service — the import route, end to end.
Service lifecycle — the same cycle end to end, including what only a person can do.
Runtime templates — the shapes a Service can take, and what each one needs to run.
MCP server — the whole surface an agent gets, tool by tool, plus authentication and scopes.