aidrop.it MCP server

aidrop.it runs a remote MCP server at https://aidrop.it/mcp that lets Claude Code, Codex or Cursor create, build and deploy your Services. MCP (Model Context Protocol) is the standard way an AI agent calls tools on another service. If the term is new to you, what an MCP server is, in plain words explains it before you read this reference.

https://aidrop.it/mcp

Any MCP-capable client can connect, including Claude and ChatGPT. What it can do depends on whether it has a shell:

• Claude Code, Codex and Cursor have a local shell and git, so they can write code, push it into a repository, build it, run it and open it to the internet.
• A chat-only client reads the record and can build code that is already in a repository, but cannot put new code in.

This is the whole programmable surface. There is no REST API beside it. Tools are added and retired as the product changes, and a test fails the build when the tool reference below and the tools the server answers with disagree. If a tool is not in that table, it does not exist.

The dashboard and the agent split the work:

• The dashboard administers the Team: its members and their roles (admin, developer, viewer). No tool does that.
• The agent creates and removes Projects and Services. project_create, project_delete, service_build, service_update and service_delete are the only way. A Service is created by its first service_build, not by a call of its own.

Access is settled once, on the Team: everyone in it can reach every Project, and what they may do there is their role.

For the whole path an agent follows to build a product with a frontend, a backend and a database, read Build a Project. To see the same tools put a working assistant online, step by step, follow put your AI agent online.

Every tool publishes an outputSchema in tools/list and answers the same JSON document twice: as text, and as structuredContent in the shape that schema promises. A client that reads the schema knows what service_get will answer before it calls; one that only reads text loses nothing.

Authentication

OAuth, with dynamic client registration. OAuth is the standard sign-in where you approve access in a browser window instead of copying a key. Clients that speak MCP OAuth (Claude Code, Codex, Cursor, Claude) open that window and walk you through consent. There is nothing to pre-register and nothing to copy. A client that cannot complete this sign-in cannot connect: there are no API keys.

On the consent screen you approve your Team and the scopes, the permissions the connection gets over it. The connection then reaches every Project in the Team, and what it may do in each is your role. You revoke it from Management → Connected apps in the dashboard, which lists every connection that holds access.

There are two scopes:

• service:read: open a Service and its safe snapshot.
• service:write: create, prepare and operate a Service.

A connection made before these scopes existed must reconnect once to receive them. Its older context:* or memory:* scopes are still accepted and allow nothing.

Glossary: Team, Project, Service and repository

A Team is the membership and billing boundary. An agent authorizes against one Team and, according to the member’s role, can discover that Team’s Projects. It is not the boundary for a database connection or a secret value.

A Project is the customer’s product, the thing they name, and its operational boundary. It owns its Services, its backing services and its secret values. A plan counts Projects. Use the current project_id for every resource, connection string and secret: a backing service or value from another Project cannot be attached and is not delivered at deploy.

A Service is one deployable application inside a Project, for example a web app, an API or a worker. It has its own build, runtime settings, address and lifecycle. It draws on the plan’s memory and CPU and never counts as a Project. It does not own a database or a secret: it receives only the named Project values and the backing services attached to it.

A backing service is a managed PostgreSQL database, Valkey cache or Valkey queue. It is not an application Service. It is the Project’s, and it may be attached only to that Project’s Services.

A repository is the Team’s, not a Service’s. It exists before any Service builds from it and outlives the Services that do. One repository may back several Services: a monorepo whose API and web app deploy separately is two Services over one repository.

repositories_list shows the Team’s repositories, on its own aidrop.it Git service and on GitHub through the aidrop.it GitHub App, with the Services each backs. A Service is created without a repository; the first service_build links one, for good.

projects_list and services_list are where every session starts. service_build takes a project_id from the first and a name for the deployable, and makes the Service on its first call, so the first deploy still happens in one session.

The build loop

The Service lifecycle follows this loop step by step, including the steps only a person can do.

Code reaches a repository from your shell and nowhere else. Where it goes is decided by one field: repositories_list answers github_accounts, the GitHub accounts the aidrop.it GitHub App is connected to for the Team.

• GitHub connected. The code lives on GitHub. Push it to a repository under one of those accounts, usually the local origin, and pass owner/repository to service_build. A new repository is visible only when the App can reach it: if the App was given selected repositories, a person adds the new one to its repository access on GitHub.
• GitHub not connected. repository_create makes an empty repository on the Team’s aidrop.it Git service and answers its clone URL and a push credential. Your own git push puts the code there. repository_get answers the same credential again for a repository that already exists.

Then the loop, which is the whole of deploying:

1. service_build builds the newest commit of the tracked branch and, when the build succeeds, deploys the image to the Service’s address. That address is open to the internet from this first deploy. The build is queued and takes minutes.
   • The first call links the repository: pass repository_ref, from repositories_list or repository_create. Later calls need no repository_ref.
   • The first call also records the runtime settings. container_port is the one value nothing can default. health_path, resource_class, runtime_kind, build_type and required_secret_names have defaults that are defaults, not guesses.
   • Nothing is read out of the code to fill them in. The image is built with nixpacks, an open-source builder that needs no Dockerfile, unless build_type: dockerfile and build_dockerfile_path name one to build instead.
   • Every later call keeps the settings unless one is passed again. Pass branch to build, and from then on follow, another branch.
2. service_get says how far it got: the repository and commit, the build’s stage and status, the deployment, the address, the settings, and a next_step naming the one call that follows. Poll it; do not narrate the wait. deployment is the latest attempt. application separately names the active deployment, commit and tag serving the address, which can be an earlier version when a later attempt failed.
3. service_logs is the latest build’s log, with credentials hidden and its length bounded. When the build failed, read it, fix the code, push, and call service_build again.

Every successful build keeps its image under a tag: the first twelve characters of the commit it was built from, named in service_build’s answer. service_tags_list lists the images a Service has, newest first. service_start with a tag starts that image without rebuilding it. A rollback is that call with an older tag, and returning to the newest version is the same call with the newest tag. Without a tag, service_start resumes the current image after service_stop paused it.

service_update renames a Service and restates what it is for. Nothing else is settable there: the address is open from the first deploy, so there is no lock to take off.

service_build refuses up front with the same sentences a build would stop on, such as a secret value nobody has stored, a size the plan does not include, or hosting paused. It does not record a run that stops at checked.

Secret values

Secret values, such as API keys, belong to the Project, not to one Service. project_secret_set stores one under a name and project_secret_delete removes it. Both take a project_id, and neither ever answers a value back.

Each Service picks which of the Project’s values it gets, in service_build through required_secret_names. Exactly the names listed there are put into that application’s environment. A Project value a Service does not name never reaches it.

Only an agent stores a value. The dashboard’s Project Secrets page lists the names a Project holds and when each was written, never the values, and nothing on it sets or changes one. Ask the customer for a value when the code needs it, store it at once, and never repeat it back, write it into code, a commit or a log, or ask for it again once it is stored.

The runtime envelope

service_get returns the runtime_envelope: the limits and rules the code you are about to write has to fit. Read it before choosing a stack, not after a build fails. Its keys:

• resources: the CPU and memory the application runs under, its size, its port and its health path, once the first build has recorded them.
• storage: that there is no persistent disk, which scratch paths are writable (/tmp, /run, /var/tmp) and how large they are.
• database and backing_services: what this Service can reach and under which environment variable; see below.
• branch: which branch is built, and why that one.
• build_rules: how an image is built. That is nixpacks by default, your own Dockerfile only when build_type: dockerfile names it, and which language versions nixpacks picks when the repository declares none.
• runtime_rules: a read-only root filesystem, exactly one replica, no published port and no host mount. Every Linux capability is dropped except binding a privileged port, and the rules say why an image that switches user at start-up serves nothing.
• egress_rules: outbound traffic leaves through the proxy only, on ports 80 and 443.
• dockerfile: the plainest Dockerfile of this Service’s runtime kind, binding the PORT the platform sets and built and run under those rules. It is null for the default kind container and before the first build.
• available_resource_classes, environment and secrets: the sizes that exist, the one environment there is, and how values reach the application.

Databases, caches and queues

backing_services is the part most worth reading before choosing a stack. It lists what this Service can actually reach: a PostgreSQL database, a Valkey cache, a Valkey queue. Each comes with the environment variable its connection string arrives under, and whether it survives a restart. An agent that assumes only a database is available writes its own cache into process memory and its own queue into a table. Neither is right here, and neither is guessable.

Two more things it tells you, and both change what you should do:

• The cache is not durable. It has no volume, so a restart empties it. Anything that must survive belongs in the database.
• A backing service is the Project’s, one per kind. Every Service in the Project that attaches it reads it under the same variable. Nothing in the code needs to know whether another Service uses it too, so do not write logic that branches on it.

available_on_this_plan says which kinds the Team’s plan includes. The sizes and the plans are listed in Runtime settings, sizes and plans.

You can attach one the Project already runs, and create one it does not.

• shared_resources_list shows what exists, which Services use it and where its data lives.
• shared_resource_update attaches one to a Service or detaches it.
• shared_resource_create runs a new one and attaches it in the same call. Pass size for a PostgreSQL instance from Pro. Pass parent_resource_id to make one more database inside an instance the Project already runs, which keeps two Services’ data apart at no extra cost against the plan.

Choose the database shape before creating anything:

1. Call shared_resources_list for the current Project.
2. If it lists a PostgreSQL instance, create the new database inside that instance with shared_resource_create and its parent_resource_id. Do not create a second instance.
3. If the Project has no PostgreSQL instance, create one with kind: "postgres" when the plan includes it and the user confirms the billed service. That holds even when another Project in the same Team already runs PostgreSQL.

Backing services never cross the Project boundary. An instance in another Project cannot be attached or used as this Project’s database.

Store the connection string yourself. When a database is attached, the tool returns its connection string and the environment-variable name for the application to use. Attaching does not store that value:

1. Save it with project_secret_set for the same Project.
2. Include exactly that name in the Service’s required_secret_names on service_build.

A deploy reads only its own Project’s named values; a value from another Project is not supplied.

shared_resource_resize moves a running PostgreSQL instance to another size the plan includes, or back to the cluster’s default. It restarts under the new limits and clients reconnect; the data and every attached Service stay. A size that does not fit the pot, the plan’s shared memory and CPU, is refused with the numbers.

shared_resource_delete removes a service and everything in it. It is explicitly confirmed and has no MCP undo operation. aidrop.it takes daily snapshots; take an independent export before deleting data you need: export your code and database shows how.

shared_resource_inspect looks inside a cache or a queue: memory against its limit, how many keys, whether it has evicted anything, the hit rate, and each key with its type and length.

• The lengths are the point. A queue’s depth is the length of the key your application writes to, not a server statistic, so this is what answers “is the queue draining”.
• A cache that evicts is a cache working. A queue that evicts is full and has thrown away work nobody did. The reply says which of the two you are looking at.

shared_resource_purge empties a cache or a queue, or removes one named key. It is confirmed and not recoverable: a cache refills itself, but a queue holds work that has not been done yet. There is no delete-by-pattern, on purpose. It would mean scanning and then deleting what matched, and a key your application wrote in between would go with it.

shared_database_query runs one SQL statement against a PostgreSQL instance, or against one database inside it, and hands back what it printed as CSV.

• It is the only way to reach that database from outside a deployed application. The instance sits on a private network with no published port, so without it, checking whether a migration landed would mean deploying something that checks it.
• It runs any statement the database accepts: a SELECT to look, a CREATE TABLE or INSERT to change. It is your data, and your agent already writes its schema through the application it builds.
• A statement is stopped after 30 seconds and the answer is cut at 64 KB. The reply says when that happens.

Three things bound creating a backing service:

• The plan decides which kinds may exist and refuses the rest by name.
• One per kind per Project is the shape, so a second request is refused with the name of the first rather than quietly running another container.
• It takes an explicit confirmed, because the service is billed to the customer for as long as it exists. That is their decision to make, not their agent’s.

A newly attached service reaches the application on its next build, not immediately.

Outbound traffic

Bringing a repository that may already be here

When bringing a repository that might already be in aidrop.it, read repositories_list first. It says which Services already build from it, so the agent offers the existing Service rather than creating a duplicate, or a second Service on the same repository when that is what the product needs.

service_build checks the repository itself when it links it: that it exists and that the GitHub App can read it. It refuses by name when it cannot. The user must install the aidrop.it GitHub App in the browser before a GitHub repository can be linked. The agent never asks for GitHub credentials or writes source code to GitHub.

A chat-only client has no local git to hand a push credential to. aidrop.it accepts no uploaded archive and never commits on your behalf, so a chat-only session reads the record and builds what is already pushed. Code enters a Service from a shell or from a connected GitHub repository.

Creating and deleting Projects and Services

A Project is the product and a Service is one deployed piece of it. Which pieces a product needs is settled while it is being built, so the agent creates, renames and removes them with project_create, project_delete, service_build (the first call makes the Service), service_update and service_delete. The dashboard lists what is running and operates it.

Confirm a delete with the customer before calling it: their application comes off the cluster and its address stops answering. project_delete refuses until it is called again with confirmed, but service_delete asks nothing and takes effect at once, for an admin only, so the question is yours to ask before the call. Their code does not move. The repository stays in the Team’s Git service and can still be cloned.

A Service is created with a name and a description, and nothing else decides what it is. How it builds and runs is what the agent passes to service_build, because the agent wrote or read the code and aidrop.it did not. The repository layout rule still holds and is enforced by the runtime: one deployable, because a Service runs one container on one port.

Connecting

aidrop.it is not listed in any client’s connector directory yet. Claude Code, Codex and the ChatGPT desktop app install it as a plugin from the aidrop.it plugin marketplace. Every other client is set up as a custom connector: you give it the server address once, and the consent screen it opens on the first call does the rest.

There is no key to paste and no skill or workflow to install: the connector carries what the agent needs. These are the same steps as on the aidrop.it install page.

https://aidrop.it/mcp

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

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

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

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

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

Every connection you make shows up under Management → Connected apps in the dashboard, and is revoked from there.

Try it

Verify the connection before relying on it:

• Claude Code: open /mcp in a session — aidropit should show as connected, and the same screen lets you re-authenticate.
• Any client: ask the assistant to call services_list. You should see the Services your Team member account can open. If the tool is missing, the connection is older than these scopes: reconnect so it carries service:read and service:write.

What the runtime gives your code

The full list of settings, sizes and plan limits is in Runtime settings, sizes and plans. The rules your code meets first:

• PORT is set in the environment, to the port the route points at. Bind it rather than a literal: an application that hard-codes 3000 while its profile says 8000 is running and unreachable, which reads as a broken app.
• One container, one port, one replica. A Service deploys a single service. If a product genuinely needs two independently deployable services, that is two Services, and worth saying to the owner rather than laying one repository out as though both will run in one container.
• Your own Dockerfile is the universal path. It is what makes Java, PHP, Ruby, Rust and .NET work here: pass build_type: dockerfile and build_dockerfile_path to service_build, and aidrop.it builds that file as-is and infers nothing.
• active means a container is running and answering. A deployment whose container does not stay running is failed and carries the task’s own error. One that runs but answers nothing on its port, or answers 5xx on its health_path for longer than a start-up takes, is failed too, with the reason: bind the PORT aidrop.it sets, and make the health path answer.
• Application files are not durable. The root filesystem is read-only and scratch is cleared on restart. Put records in PostgreSQL and uploads/media in object storage — the runtime gives a Service no data volume, so a local path is not a place to keep anything.

Tools

The product and its pieces

Repositories

The build loop

Run it, open it

Your own domain

The values an application reads

Backing services