MCP server
Simplewala exposes your account over the Model Context Protocol, so an AI assistant can list your servers, read your billing position and deploy resources without you pasting output into a chat window. Any MCP client works — Claude Code, Claude Desktop, Cursor, or your own code using an MCP SDK.
Seventeen tools are available: seven that read, five that run your infrastructure (restart, stop, start, redeploy, reboot), three that create or deploy a resource, and two that create an identity. A key can be created read-only, in which case only the seven reading tools are offered.
Which tools exist at all is also up to whoever runs your Simplewala platform — see what your administrator controls. The two identity tools are off by default.
Every interaction is logged. Each authentication, session and tool call — the refused ones included — is written to a tamper-evident audit trail you can read on the API & MCP access page. See the audit trail.
Endpoint and transport
https://simplewala.cloud/api/v1/mcp The transport is Streamable HTTP, in stateful mode. It is the only transport offered; the deprecated HTTP+SSE transport is not implemented, and every current client speaks Streamable HTTP. In practice your client handles all of this — the detail matters only if you are writing your own:
-
POSTwith a JSON body carries JSON-RPC. The first call must beinitialize; the response carries anmcp-session-idheader. -
Send that
mcp-session-idon every subsequent request. A POST with no session id that is not aninitializeis rejected with400. GETopens the SSE stream for an existing session.DELETEends the session. Idle sessions are closed after 30 minutes.-
Content-Type: application/jsonis required on POST.
The endpoint for your own account is shown, ready to copy, on Portal → Account → API & MCP access — use the value on that page rather than the one above if you reach the platform on a different hostname.
Authentication
Every request — POST, GET and DELETE alike — needs an
account API key as a bearer token:
Authorization: Bearer sw_dt_xxxxxxxxxxxxxxxx
Create one under Portal → Account → API & MCP access. Keys begin
sw_dt_ and are shown once, when they are created — the platform stores only a hash,
so a key that is lost has to be rotated rather than recovered.
Your call is refused, with the reason, when any of the following is true:
- The key is revoked or past its expiry date.
401. - The key is scoped to a single app.
403. Deploy credentials created from a Git app's CI/CD tab are scoped to that app and authorise its deploy routes only. The MCP tools are account-wide, so MCP requires an account key — the kind the API & MCP access page creates. - The key has an IP allowlist and you are not on it.
403. The same allowlist that applies on the Deploy API applies here. - The account is pending, suspended or cancelled, or its email address
is unverified.
403. - The wallet is frozen, or the credit balance is zero or below.
402for the balance. This applies to read-only calls too. - The session id belongs to a different key.
403. A session belongs to the key that opened it.
The key is re-checked on every call rather than once when the session opens, so revoking a key stops an agent that is already connected — at its next request, not at its next restart. Basic-auth deploy credentials are not accepted here; they work on the Deploy API only.
Read-only keys
When you create a key you choose its access level. Read-only is the default on the page, and it is the right choice for anything you are not supervising closely:
- A read-only key gets the seven reading tools. Everything that changes anything is not registered for it, so those tools never appear in the agent's tool list and cannot be called. An agent holding one cannot spend money, restart or stop a service, or create an account or a login.
- A full key gets every tool your administrator has enabled. It carries the same power as your account for the operations below.
The level is fixed when the key is created. To change it, create a new key and revoke the old one. Rotating a key keeps its access level and its name, and only replaces the secret.
What your administrator controls
Whoever operates your Simplewala platform has a switch for the MCP endpoint and a switch for every individual tool, under Admin → Feature Flags. Two consequences worth knowing:
- The endpoint can be turned off entirely. Every request is then refused with a
503, whatever keys exist. Your keys keep working for the REST API. - Individual tools can be withheld. A disabled tool is not registered, so it simply does not appear in your agent's tool list — there is no error to read, because the agent never sees the tool. The API & MCP access page marks any tool that is switched off platform-wide, so you can tell that apart from a key that is merely read-only.
The two gates only ever subtract. An administrator enabling a tool does not give a read-only key access to it, and a full key does not reach a tool the administrator has switched off.
The two identity tools are off by default. create_account and
invite_org_member have to be switched on deliberately — their effect lands on other
people rather than on your own infrastructure, so they are not something to discover by
accident. Everything that reads or runs your own resources is on by default.
Changing a switch takes effect for new sessions. An agent already connected keeps the tool list it was given until it reconnects, so a tool does not vanish halfway through a task.
The audit trail
An agent acts on your infrastructure without you watching every call, so the product has to be able to answer "what did it actually do". Every MCP interaction is recorded:
- Authentication — every success, and every refusal with its cause.
- Sessions — opened, used, refused, closed, expired.
- Every tool call — which tool, its arguments, whether it succeeded, how long it took, and which key and IP address it came from.
Read it under Portal → Account → API & MCP access, newest first.
What is never recorded
The log is append-only, so anything written to it is written permanently. Arguments therefore go
through an allow-list: known identifiers — a server slug, an engine type, a container
port, a domain id — are kept in full, and everything else is reduced to a type marker
like <string:21>. So a row records that an argument was supplied without
recording what it was.
Consequently the log never contains a password, a token, an API key or a vault value. API keys appear only as the 12-character prefix the access page already shows. Email addresses are stored as a short one-way fingerprint, not in the clear.
Why it can be trusted
Each entry commits to the one before it with a SHA-256 hash of its contents chained to its predecessor. Editing or deleting an entry breaks the chain from that point on, and the access page shows whether yours still verifies. A log that can be quietly rewritten is worth nothing in the one situation you need it.
Failed authentication attempts are chained too, under a separate partition — a request carrying an unknown token has no account to attribute, and those attempts are a large part of what the log is for.
Creating accounts and logins
Three tools create an identity rather than a resource. All three need a full key, and none of them can be used to get around the account and authentication model.
create_managed_account
Creates a login the platform manages for you — a database user, a mailbox, an SFTP user or a Git user — and registers it for rotation. Use it so an app gets a database user of its own instead of sharing the root account.
The password is generated and written to your secrets vault. The tool reports the vault entry's name and not the password, so a live credential never lands in a chat transcript. Only the four kinds the platform can actually create on the target are offered; the others exist in the portal but would report success for a login that does not exist.
invite_org_member
Adds an existing Simplewala account to one of your organisations, as
admin or member. The caller must be an owner or admin of that
organisation, ownership cannot be granted this way, and if no account exists for the address the
tool fails — deliberately, because the person must have signed up and authenticated themselves
first.
create_account
Registers a new Simplewala account and emails its owner an invite link. Use it when onboarding somebody who asked you to set an account up for them.
An agent may register an account. It may not get into one.
- No password is set, and the tool cannot supply one. The owner chooses their own from the invite link, so the only party who can ever sign in is whoever holds the mailbox.
- Nothing usable is returned — no password, no token, no session. The invite token goes to the email address and nowhere else.
- The account cannot order anything until its owner appears. It is recorded as agent-created, and ordering stays blocked until the owner has verified the address and signed in at least once. Then it begins on the ordinary trial: one small server, with the next trust level earned by keeping it a week. So an agent cannot create accounts to get around a limit on its own — a new account can do strictly less than the one that made it.
- Capped. One key may create at most five accounts per rolling 24 hours, counted from the audit log. The platform-wide registration switch applies, so turning signups off turns this tool off too.
If you are giving a colleague access to infrastructure you already run, use
invite_org_member instead — they should have their own account, not one you created.
Claude Code
claude mcp add --transport http simplewala https://simplewala.cloud/api/v1/mcp \
--header "Authorization: Bearer sw_dt_YOUR_KEY" Claude Desktop, Cursor and other clients
Clients configured from a JSON file take the same shape. Add this to the client's MCP configuration:
{
"mcpServers": {
"simplewala": {
"type": "http",
"url": "https://simplewala.cloud/api/v1/mcp",
"headers": {
"Authorization": "Bearer sw_dt_YOUR_KEY"
}
}
}
} Treat that file as a secret. If it lives in a repository, keep the key in an environment variable your client expands instead of writing the literal value in.
Tool reference
Each tool carries its own description and parameter help, so a capable assistant generally picks correctly without being told. This table is for when it does not, or when you want to know what you are authorising.
A connected client sees up to seventeen tools, minus anything your key or your administrator withholds. Seven read; five run what you already have; three create or deploy a resource; two create an identity (see creating accounts and logins).
Reading — included in every key
list_servers
Every server on the account, with status, public IPv4, provider and specification. Takes no
parameters. Returns id, name, slug, status,
ipv4, provider and spec, newest first.
Start here. Most other tools identify a server by its slug, and
this is where slugs come from.
get_server
One server in full, including when billing started.
Takes slug (required) — the slug field from list_servers,
not the display name and not the IP.
Use it when you already know the slug and want detail about that one machine. To look at several,
use list_servers — an assistant should not call this in a loop over every server.
list_databases
Database engines across every server, with engine type, status and host server. Takes no parameters.
Connection credentials are deliberately absent. Root passwords live in the secrets vault and no MCP tool reads it.
list_apps
Deployed applications — Docker, runtime and CMS — with deploy method, image and domain. Removed apps are excluded. Takes no parameters. Capped at 50, so on a large account an absent app is not proof it does not exist.
list_domains
Domains on the account with their id and verification status. Takes no parameters.
Required before deploy_docker_app: that tool needs a domainId, the id
is a UUID that cannot be guessed from the domain name, and this is the only tool that returns
one. A domain whose status is not active will not serve traffic even after a successful deploy.
list_mailboxes
Mailboxes as full addresses, with status. Takes no parameters. Capped at 50. This does not read mail, send mail or return passwords, and no MCP tool does.
get_billing
The live billing position: credit balance, hourly and daily burn rate, metered spend today and this month, unpaid usage, and runway in hours and days. Takes no parameters.
Billing is metered hourly, so these are live figures — not a monthly estimate and not an invoice. Useful as a check before authorising something that adds cost.
Creating — full keys only
Both of these create a billable resource and start charging from the hour it runs. Both are marked in the protocol as non-read-only, so a well-behaved client will ask you before calling them.
deploy_database
Deploys a database engine in a container on an existing server. Parameters:
serverSlug(required) — fromlist_servers. The server must already exist; this cannot create one.-
dbType(required) — one ofmysql,postgres,mariadb,redis,valkey,mongodb,kafka,rabbitmq,memcached. Published as an enum, so a client cannot sendpostgresqlby mistake. version(optional) — e.g.17for postgres. Omit for the platform default.name(optional) — a label. Omit and a readable unique name is generated.
The root password is generated and written to your secrets vault. The tool
returns the name of that vault entry, never the password itself, so it does not end up
in a chat transcript. Check list_databases first to avoid deploying a duplicate.
deploy_docker_app
Creates an app from a Docker image, binds it to a domain you hold, and starts the deploy. Parameters:
serverSlug(required) — fromlist_servers.name(required) — name for the app.-
dockerImage(required) — full reference including the tag, e.g.ghcr.io/acme/api:1.4.2. Avoidlatest: the deployed release becomes unidentifiable and rollback cannot tell versions apart. containerPort(required) — the port the app listens on inside the container, e.g.3000. Not the public port.domainId(required) — theidof a domain fromlist_domains.
The image must already exist in a registry the server can pull from. There is no hosted build
step, so source code cannot be deployed this way. The deploy runs asynchronously; use
list_apps to see the result.
What is deliberately not here
- Nothing is deleted over MCP. There is no tool that destroys a server, volume, database, domain or mailbox. Destructive actions stay in the portal, behind a confirmation.
- No secrets are returned. No tool reads the vault, a database password, an SSH key or mailbox credentials.
- No server provisioning. Both deploy tools need a server that already exists. Ordering a machine is a portal operation.
- No per-tool scoping. The choice is read-only or full; you cannot yet allow
deploy_databasewhile withholdingdeploy_docker_app. - No signing in as an account. No tool returns a password, a session or a token, including for an account it just created.
- No audit log edits. Nothing can delete or amend an entry — not through MCP, not through the portal. The chain is what makes that checkable.
- No server provisioning, resizing or termination.
reboot_serveris the only machine-level action; ordering, scaling and terminating stay in the portal. - No log reading. There is no tool that returns application or server logs yet. Use the portal's log views.
When it does not connect
- 401 "Invalid, revoked or expired API key" — check the prefix shown on the access page matches the key you configured. Rotate it if you cannot tell.
- 403 about being scoped to a single app — you are using a deploy credential from a Git app's CI/CD tab. Create an account key on the API & MCP access page.
- 403 about an IP allowlist — the key is pinned to addresses that do not include yours. The message names the address it saw.
- 403 about email verification — verify the account's email address first.
- 402 "Insufficient credit balance" — top up on the billing page. The API is refused at or below a zero balance even for read-only calls.
- 503 "The MCP server is disabled on this platform" — your administrator has turned the endpoint off. Nothing on your side will change that.
- A tool is missing from the tool list — either the key is read-only, or your administrator has switched that tool off. The API & MCP access page distinguishes the two: each tool shows whether it is included for a read-only key and whether the platform has it on.
- The deploy tools are missing from the tool list — the key is read-only. That is the feature working; create a full key if the agent genuinely needs to deploy.
- 404 "Unknown or expired MCP session" — the session was idle for over 30 minutes or the server restarted. Clients reconnect on their own; reload the connection if yours does not.
- 400 about not being an initialize request — only when writing your own client.
POST an
initializefirst and reuse themcp-session-idit returns.
Running what you already have — full keys only
These are the tools for keeping infrastructure working, as opposed to creating more of it. All
five take a slug from list_apps or list_servers.
restart_app
Stops and starts an app's container with the same image, configuration and volumes. Nothing is rebuilt and no data is touched. Try this first when an app is misbehaving but its configuration is right — a wedged process, a connection pool that will not recover.
stop_app and start_app
Takes an app offline and brings it back. The container is stopped rather than removed, so
volumes and configuration survive and start_app restores it as it was. Stopping an
app does not reduce your bill — the server it runs on is what you pay for.
stop_app is marked destructive in the protocol, so a well-behaved client asks before
calling it: whatever the app serves goes down immediately.
redeploy_app
Redeploys from the app's current configuration, pulling the image again and recording a new
release so it can be rolled back by release afterwards. Use it after changing an image tag,
environment or settings — or to pick up a tag that has moved. For a wedged process with
unchanged configuration, restart_app is faster and less disruptive.
reboot_server
Reboots the machine through the cloud provider's API rather than over SSH, so it works even when the server is unresponsive. Everything on that machine goes down — every app, database and mailbox — typically for 30 to 60 seconds.
A last resort, and marked destructive so a client confirms first. Rebooting to fix one container
takes every other service on the box with it, so restart_app on the specific app is
almost always the better move. Not every provider supports it; the tool says so rather than
pretending it worked.
Creating an identity — full keys only, off by default
create_managed_account— a database user, mailbox, SFTP or Git login; password to the vaultinvite_org_member— add an existing account to your organisationcreate_account— register an account for somebody, who must then set their own password
All three are documented in full under creating accounts and logins.
For the REST API that covers the same account — and a good deal more of it — see the API overview. New to the platform? Start with the getting started guide.