outputSchema, so an assistant knows the shape of a result before calling it. Results come back as structuredContent, with a JSON text fallback for clients that ignore structured output.
Pod Management
list_pods
List pods belonging to the authenticated team, optionally narrowed. With no parameters it returns every pod; to look up a single pod whose exact name you already know, useget_pod instead.
Returns:
{ pods, count, total } — count is the number of matches, total the number of pods the team owns before filtering. Each pod carries name, status, preset, plan, region, domain, URL, and resource allocation.
Example prompt: “Show me all my pods” · “Which of my pods are stopped?“
get_pod
Get details of a specific pod by name.
Returns:
{ pod } with status, domain, URL, preset, plan, region, resource allocation, and a readiness object (below). Internal fields (container IP, SSH port, server/team identifiers) are not exposed over MCP.
Example prompt: “What’s the status of my-api?” or “Is my-api actually up?”
Readiness
status says whether the container is running. readiness.state says whether a visitor to the URL would actually see your application — the two are not the same, and a container can be up while the app inside it is not answering.
readiness.detail explains any state other than healthy, and readiness.port is the port inside the pod that the public URL is proxied to — what your app must listen on.
1-Click app pods are not continuously probed, so a running one reports
unknown rather than healthy. That is InstaPods declining to claim a check it does not run — it is not a sign the app is down.create_pod
Create a new pod on your InstaPods account, billed monthly to that account. The tool checks that your billing is in order (payment method, subscription) and opens your monthly billing cycle on a first pod — with one exception: if you have no payment method yet, a custom-code create through the connector may be granted a free trial pod instead of being refused. That pod is held in an InstaPods-owned trial account and is never billed. The response says so when it is. No payment is ever taken in the conversation. Payment methods, invoices and receipts are managed by you on instapods.com; no InstaPods MCP tool asks for card details or moves money. There are two ways to call it, and they answer different requests:app_type— deploy a ready-to-run application from the 1-Click App catalog. The app is pre-baked into the pod image, so it boots working at the pod’s URL and nothing is uploaded. The image carries its own runtime, so leavepresetempty.preset— create an empty pod on a runtime, then upload code to it withwrite_file. To ship code you already have,deploy_poddoes the whole thing in one call instead.
Each 1-Click App declares a minimum plan (n8n needs Build, for example). Omitting
plan deploys on that minimum; naming a plan below it is rejected, not silently upgraded — the error names the required plan and its monthly price so the assistant can check with you before anything is billed.
Returns: Created pod object. Its plan_slug is the plan the pod is actually billed on.
Example prompt: “Create a Python pod called data-api on the build plan” · “Deploy n8n for me”
deploy_pod
Deploy your own code to a live HTTPS URL in one call: creates the pod if it does not exist, uploads every file, installs dependencies, restarts the app, and checks the URL actually answers before reporting success. It is the tool to use when the assistant already has your code —create_pod + write_file + manage_pod is the same thing spread over four or more calls.
Idempotent on
name. Deploying twice to the same name updates that pod rather than creating a second one or failing, so an assistant can safely retry a call that timed out.
There is no preset parameter. The runtime is detected from the file names — package.json → nodejs, requirements.txt or a .py file → python, composer.json or a .php file → php, go.mod → go, index.html → static. If nothing matches, the call fails and names the options rather than guessing, since a wrong guess silently skips the install or build step. (A pod created with create_pod and an explicit preset can then be deployed to by name.)
Returns: { pod, url, public, reason, created, preset, plan, files_written, deps_installed, service_active, warning }.
public is the part that matters: it says whether an ordinary visitor’s request to url actually succeeded, checked from outside the container after the deploy. A pod can exist, be running, and still not be serving anything anyone can see — public: false with a reason is how you find that out instead of being told the site is live.
1-Click Apps are not deployed this way; they ship their own code, so use create_pod with app_type.
Example prompt: “Put this landing page live at demo.instapods.app” · “Deploy this Flask app for me” · “Push my change and tell me if it’s live”
manage_pod
Start, stop, restart, or reload a pod. Every action here is reversible and leaves your files alone — deleting is a separate tool,delete_pod, so an assistant can restart your app without stopping to ask permission each time.
Returns: Updated pod object, or reload status with health check.
The reload action is the most powerful — it:
- Auto-starts the pod if stopped
- Installs dependencies (
npm install,pip install,composer install) - Detects entry points and frameworks (gunicorn, Express, Laravel)
- Restarts application services
- Runs a health check and returns service status
delete_pod
Permanently delete a pod. The container, its files, and its database are destroyed and cannot be recovered, the URL stops working, and billing for it stops.
Returns: Deletion confirmation.
This is annotated as a destructive tool, so Claude asks you to confirm before it runs — every time, regardless of what you have approved before.
reason and note are the same optional exit survey the dashboard shows. Claude only passes them on if you have already said why — it will not hold up the deletion to ask, and a pod is never kept because the question went unanswered.
Example prompts: “Delete test-pod” · “Get rid of the staging pod, I’m done with it”
change_plan
Upgrade or downgrade a pod’s plan. Adjusts CPU, memory, and disk to the target plan’s limits.
A downgrade is rejected if the pod’s current disk usage would exceed the smaller plan’s quota — free up space first. Use
list_plans to see the limits and price of each plan.
This changes what your account is billed, prorated on its next monthly invoice. As with create_pod, no payment is taken in the conversation — cards and invoices stay on instapods.com.
Returns: Updated pod object with the new CPU, memory, and disk allocation.
Example prompts: “Upgrade my-api to the grow plan” · “Move data-api down to build”
File Operations
list_files
List files in a directory inside a pod.
Returns: Array of file entries with name, permissions, size, and
is_dir flag.
Example prompt: “Show me the files in my-api”
read_file
Read the contents of a file inside a pod.
Returns: File content as text.
Example prompt: “Show me the package.json in my-api” or “Read /home/instapod/app/index.js”
write_file
Write content to a file inside a pod. Creates the file and parent directories if they don’t exist.
Returns: Confirmation with saved path.
Example prompt: “Create an index.js in my-api that serves a hello world Express app”
Files are written as the
instapod user. Paths must be within /home/instapod, /var/www, or /tmp.Environment Variables
Use these instead of hand-editing.env with exec_command. They write the file your app actually reads (a 1-Click App’s own environment file where it has one), quote values so a multi-line key survives intact, keep the file readable only by the app, and restart the app so the values take effect.
list_env_names
List the names of a pod’s environment variables and the file they live in.
Returns: The variable names (sorted) and the file path. Never the values.
Example prompt: “Which environment variables are set on my-api?“
set_env
Set environment variables on a pod. Existing names are updated in place, new ones appended; names you do not pass are left alone.
Returns: How many variables were set, the names affected, the file path, and any warnings about names InstaPods manages itself.
Example prompt: “Set OPENAI_API_KEY on my-api” (your assistant will ask you for the value)
Names must match
[A-Za-z_][A-Za-z0-9_]*. A name InstaPods manages itself (such as PORT) can be overridden, but the response warns you — overriding one can take the pod offline.delete_env
Remove environment variables by name and restart the app.
Returns: How many were actually removed — a name that was not set is ignored.
Example prompt: “Remove STRIPE_TEST_KEY from my-api”
Command Execution
exec_command
Run a shell command inside a pod. Runs as theinstapod user (same as SSH access), from the pod’s app root unless cwd says otherwise.
Returns:
stdout and stderr separately, the command’s real exit_code, duration_ms, timed_out, and the cwd and timeout_seconds applied.
Example prompt: “Run ls -la in my-api” or “Install express in my-api with npm”
exit_code is the command’s own status — a non-zero value means the command failed even though the tool call succeeded. A command killed at the timeout returns exit_code: 124 with timed_out: true, and keeps whatever it had printed before the kill. Raise timeout_seconds for dependency installs and builds.Logs
get_logs
Get application logs from a pod via journalctl — either the tail, or a search across the whole journal.
Returns:
{ pod, service, grep, logs } — logs is the journalctl output,
and grep echoes the pattern back so it is clear the output is filtered.
With grep, matches print newest first (the opposite order to an unfiltered
read); an all-lowercase pattern matches case-insensitively while any uppercase
character makes it case-sensitive; and -- No entries -- means the search ran
and nothing matched.
Example prompt: “Show me the logs for my-api”, “Get the last 50 nginx logs from my-app”, or “Search my-api’s logs for ECONNREFUSED”
Feedback
The feedback widget is a pinned-comment overlay InstaPods injects into a pod’s served HTML. Turn it on, share the link with reviewers, then read and triage what they left — the same data the dashboard’s Feedback tab shows.list_feedback
List visitor feedback on a pod, plus whether collection is enabled and the link to share.
Returns:
{ pod, enabled, visibility, share_url, feedback[], counts, count }. Each comment carries id, name, email, comment, page_path, element_text, status and created_at. counts totals every status regardless of the filter.
Example prompt: “What feedback did people leave on my-site?” or “Show me the unresolved feedback on my-site”
manage_feedback
Turn the widget on or off, change who sees it, rotate the share token, or triage one comment.everyone shows the widget to every visitor of the pod URL. link hides it unless the visitor opens the returned share_url, which carries the token — use it to collect feedback from a named group without exposing the widget publicly. rotate_token mints a new token, so links already handed out stop working.
Enabling re-renders the pod’s nginx vhost to inject the widget, so the pod must be running. On a stopped pod the setting is stored and applies on the next start.
Returns: { action, status, pod, id?, enabled, visibility, share_url }.
Example prompt: “Turn on feedback for my-site and give me a link to share” or “Mark that feedback resolved”
Catalog
list_apps
List the 1-Click Apps that can be deployed ready-to-run — n8n, Uptime Kuma, Vaultwarden, Memos, Excalidraw and the rest of the catalog.
Returns:
{ apps, count }. Each app carries slug (what to pass to create_pod as app_type), name, description, category, replaces (the commercial SaaS it stands in for), min_plan and min_plan_price_monthly_cents, and required_env_vars for apps that need configuring after deploy.
Example prompt: “What self-hosted apps can I deploy?” · “Is there a self-hosted alternative to Zapier?“
list_presets
List available pod presets. Parameters: None
Example prompt: “What presets are available?“