MCP & access tokens

The Pierrr MCP server

Pierrr exposes a remote Model Context Protocol (MCP) server. You connect an AI client to it to drive your projects, deployments, domains and secrets in natural language. Compatible clients include:

• Claude (Desktop or web)
• ChatGPT
• Cursor
• Gemini, and any other client that supports a remote MCP server.

Connect by authorizing the client in your browser

With a client that supports it, there is no token to copy: give it only the MCP server URL. The client opens a Pierrr page in your browser, where you are already signed in, and you choose there what it may do.

How it goes:

1. Add the MCP server to your client with the URL below, without an Authorization header.
2. The client opens the Pierrr authorization page. Sign in if needed: no password is asked again while your session is open.
3. Check the application name, marked "unverified" since the application declares it itself, and the address the answer is sent to. Only authorize what you just started yourself.
4. Choose the organization and the permissions, then Authorize. Permissions are capped to your role, and revealing variable values is never ticked by default.
5. The client gets short-lived access that it renews on its own. Denying sends it back without any access.

In a JSON configuration file, the URL is enough:

{
  "mcpServers": {
    "pier": {
      "url": "https://api.pierrr.com/mcp"
    }
  }
}

One authorization covers a single organization. To drive several from the same client, use pasted access tokens, described below.

Connected applications

Clients authorized from the browser show up in Settings, Access tokens, under Connected applications, with their permissions and last use. The Disconnect button cuts their access at once: the client will have to ask for authorization again.

If the same renewal credential is presented twice, Pierrr treats it as leaked and cuts the matching connection. The client then asks for authorization again.

Create a personal access token

The other way to authenticate to the MCP server is a personal access token (PAT) that you create in the dashboard and paste into the client configuration. This token replaces your password for programmatic access.

Step by step

1. Open the dashboard, then Settings, then Access tokens (/settings/tokens).
2. Click New token, give it a clear name (for example "Claude Desktop"), then confirm with Create token.
3. Copy the token shown in the Token created window, keep it somewhere safe, then click Done.
4. Paste it into your AI client configuration (see the next section).

The token is shown only once, at creation. If you lose it, revoke it and create a new one.

On creation, a token gets every permission of your role by default, except revealing variable values. Untick Full access to choose a subset among 16 permissions: read projects, manage projects, manage containers, read domains, manage domains, bind domains, read servers, restart servers, provision servers, read deployments, notifications, billing, read repositories, manage the organization, manage members, access databases.

The Allow revealing variable values box is unticked by default. Without it, an assistant connected with this token can list, create or update variables, but never read a value in clear. Tick it only if you need it.

Every new token expires. The suggested date is 90 days away; you can pick another one. Tokens created before this rule keep their date, or their lack of one: revoke and recreate them if you want them to expire.

The token list shows, for each of them, its state (Active, Expired, Revoked), its creation date, its expiry date and its last use (or Never used).

The page also shows the MCP connection URL with a Copy button: copy it from there rather than rebuilding it.

The token's permissions are bounded by your role in the organization: a token can never do more than you can do yourself in the console.

A token can also be restricted to one or several projects of its organization. Leave every project selected (the default) for a token that reaches the whole organization; pick a subset and it is refused on every other project, reads included, wherever it is used.

Connect an MCP client

Provide these three pieces of information in your client's MCP configuration:

• URL: https://api.pierrr.com/mcp
• Transport: Streamable HTTP.
• Header: Authorization, value Bearer followed by a space and your access token. Not needed if your client connects by authorizing it in the browser.

This is the hosted Pierrr hub URL, the same for every client. If you run your own Pierrr instance (self-hosted), use your domain's API: https://api.your-domain.com/mcp.

Example configuration

Most clients accept a JSON configuration file of this shape:

{
  "mcpServers": {
    "pier": {
      "url": "https://api.pierrr.com/mcp",
      "headers": {
        "Authorization": "Bearer pier_pat_xxxxxxxxxxxxxxxx"
      }
    }
  }
}

Replace the example token with your own (created in the previous step). The URL is already your hub's.

Multiple organizations

A single access token authorizes one organization. If you manage several, list multiple personal access tokens separated by commas in the Authorization header, one per organization, all created by the same user:

{
  "mcpServers": {
    "pier": {
      "url": "https://api.pierrr.com/mcp",
      "headers": {
        "Authorization": "Bearer pier_pat_orgA_xxxxxxxx,pier_pat_orgB_yyyyyyyy"
      }
    }
  }
}

The New token dialog can build this for you: turn on Multiple organizations, pick which of your organizations the connector should reach and, for each one, all its projects or only some, then Create token hands back the combined value below already assembled, with the coverage of each organization listed underneath so you can check it before copying.

All tokens in the list must belong to you. If they don't, the connection is rejected.

With a multi-org token, every tool call must say which organization it targets by adding one of these arguments:

• organizationId: the organization's id.
• organizationSlug: the organization's short identifier (the one in its addresses), as an alternative to the id.

If a tool call omits the selector, or names an organization the token doesn't cover, the server returns a clear error listing the organizations available on that token, so your AI client can ask you to pick one instead of failing silently.

Capabilities

Everything is scoped to the token's organization and respects your permissions. Capabilities split into reads and actions.

Read

• List and inspect your projects and their containers.
• Review deployment history, details and logs.
• List your custom domains and their status.
• List your servers (Pierrr Agent) and their state.
• List environment variables, never their values.
• Review your usage and billing quotas.
• List past invoices, paginated.
• List notifications and check the unread count.
• List recent data backups and Pierrr project exports.
• List a project's volumes and their container mounts.
• List your Redis add-on instances and their linked projects.
• List a project's network groups.
• List a project's containers and the repositories linked to them, or create an app.
• Read a project's security scan history and its findings.
• List the organization's members and its pending invitations.
• Read the GitHub installation status and list the accessible GitHub repositories (GitLab projects cannot be driven through MCP).
• List your personal access tokens.

Detailed reads, by area

Every tool in this list only reads: it changes nothing, and your client may allow it without asking you. In brackets, the permission the token must carry.

• Projects and containers, read (Read projects): recent runtime logs of a project or of a single container, 500 lines at most, recognisable secrets masked; CPU and memory over the last hour with the project's budget; a container's resource limits; its autoscaling rule; public TCP ports; database extensions; how environment variables reach the containers.
• Deployments, read (Read deployments and Read projects): the detail of a deployment, with its attempts and their stages.
• Before a deployment, read (Manage containers): the latest commits of the deployed branch, to pick a precise version; a check of the variables a container will receive, by name only, never their value.
• Backups and security, read (Read projects): the automatic backup schedule, the security scan schedule, the detail of a scan.
• Servers, read (Read servers): the health history of a server, the projects it hosts, the log of the commands it received and their outcome.
• Organization, read (Read projects): an overview (projects, containers, domains, servers); the daily health history of the organization or of a project; the available frameworks and the Dockerfile templates provided.
• Notifications, read (Notifications): the organization's notification subscriptions.
• Billing, read (Billing): the current plan and subscription, the plan catalog, available and active add-ons, a preview of what a plan change would cost, object storage instances and their projects, never their access credentials. Payment and the plan change itself stay in the console.
• Repositories, read (Read repositories): the branches of a connected repository, the folders of a branch, whether a folder has a Dockerfile and which framework it declares.
• WordPress sites, read (Manage containers): the organization's sites, their installation state, their address, the administrator's login and the last error.
• Migrations from another host, read (Manage projects): the organization's migrations, their state, their analysis (variables by name only, domains, what to fix) and their report; the accounts the connection made in the console reaches at the other host.

Actions

• Trigger a deployment.
• Restart, start, stop, build or delete an app.
• Start or stop every app of a project at once (scale), or set an app's number of replicas.
• Create a domain.
• Set an environment variable.
• Mark one or every notification as read.
• Run a data backup for a project, or restore one onto its app.
• Create a Pierrr project export.
• Mount or unmount a volume on an app.
• Link or unlink a project to a Redis add-on instance.
• Create or remove a network group.
• Create a project, rename it, and create a container inside it.
• Probe a domain, bind or unbind it from a service, resync its configuration.
• Update or delete a variable, apply a whole .env block at once, manage per-container bindings, and reveal a value if the token was allowed to.
• Run a security scan on a project.
• Invite a member into the organization, or resend a pending invitation.
• Resync the list of repositories accessible through the GitHub installation.
• Ask a server for a health snapshot, or check whether an agent update is available.

Detailed actions, by area

Every tool in this list changes something. "changes": the action can be redone or corrected without loss. "destructive": it deletes or cuts something off, and the server refuses it without confirm: true. In brackets, the permission the token must carry, the same as for the equivalent action in the console.

• Lifecycle, changes (Manage containers): cancel a pending or running deployment; restart every app of a project; wake a Free project switched off after 30 days without activity; build an app from a precise commit rather than the latest of its branch, which is also how to roll back to an earlier version.
• Autoscaling, changes (Manage containers): create, replace or switch off the rule of an app; its settings are kept while it is off.
• Projects and apps, changes (Manage projects): choose where a project runs, on Pierrr or on one of your servers; rename an app; change its CPU and memory limits and reservations; change its build settings (branch, automatic deploy, paths, commands, health check path); open a public TCP port.
• Data and network, changes (Manage projects): give an app access to the project's database, cache or object storage; enable a database extension; change a network group (destructive: setting its list of apps removes the ones left out) or re-apply the network configuration on the server; schedule automatic backups and security scans.
• Object storage, changes (Billing): link a project to one of your object storage instances.
• Servers, changes (Provision servers): rename a server.
• WordPress sites, changes (Manage projects): create a site in an existing project or in a project of its own, on Pierrr or on one of your servers. The administrator's password is returned once, in the answer, as in the console.
• Migrations from another host, changes (Manage projects): pick an account and list its projects, analyze a project, create on Pierrr the domains of the imported app and bind those that already point here, close an imported migration.
• Projects, destructive (Manage projects): delete a project with all its apps, its database and its data; close a TCP port; change how variables reach the containers, which clears the per-container bindings; remove an app's access to the database, cache or object storage; disable a database extension.
• Domains, destructive (Manage domains): delete a domain and all its bindings; the sites stop answering on it.
• Object storage, destructive (Billing): unlink a project from an instance.
• Server update, destructive (Restart servers): update the agent of a server to the latest published version; it restarts.
• Servers, destructive (Provision servers): revoke a server, which can never reconnect with its current credentials; remove it from the list.
• Invitations, destructive (Manage members): revoke a pending invitation; its link stops working.
• Migrations, destructive (Manage projects): run the import, previewed by default (variables carried over and left behind, what blocks it); copy the database over one that already holds data; cancel a migration, which cannot be resumed.
• Organization, destructive (Manage organization): rename the organization, previewed by default. When its identifier changes, every app is recreated under the new one and the addresses Pierrr provides change with it; your custom domains stay.

Preview before you act

Every action that touches your servers or recreates something defaults to dryRun: true: restarting, starting, stopping, building or deleting an app, scaling, restarting or deleting a project, renaming the organization, importing a migration. The tool describes what it would do without touching anything, for instance the apps and the database a project deletion would take with it; the client must explicitly pass dryRun: false to actually run it.

Destructive actions additionally require confirm: true, even with dryRun: false: deleting an app or a project, renaming a project (its identifier and addresses follow the new name), restoring a backup, deleting a variable, applying a .env block that deletes variables (!KEY lines), replacing the variables bound to a container, changing how variables reach the containers, unbinding or deleting a domain, unmounting a volume, removing a network group or changing its list of apps, unlinking a project from a Redis or object storage instance, removing an app's access to the database, cache or storage, closing a TCP port, disabling a database extension, updating, revoking or deleting a server, revoking an invitation, renaming the organization, importing or cancelling a migration, copying a database over the existing one. Without it, the call is rejected and the message says what to do.

For a destructive action that has a preview (deleting an app or a project, renaming the organization, importing a migration), confirm: true is no longer enough: the preview returns a confirmation token, valid for 5 minutes and once, bound to your access token, to the tool and to the exact arguments of the preview. The real call must bring it back, with the same arguments, dryRun: false and confirm: true; any other argument invalidates it. An assistant that called these tools directly with confirm: true now gets a message telling it to go through the preview. The other destructive actions, which have no preview, still need confirm: true alone.

Each tool tells your client whether it only reads, changes something, or can destroy something. Set your client to ask for your approval before any action that changes or destroys, and before revealing any value.

Since version 0.0.42, permissions are stricter: a token limited to container management can no longer restore a backup, export a project or create a container, which require write access to the project.

Limits

To protect your account and the service, the MCP server applies these limits:

• One call per request: batches of several calls in a single request are refused.
• At most five tokens in the Authorization header.
• A capped number of calls over time for each tool and each token, tighter for costly or sensitive actions (invitations, builds, variable writes, reveals). Beyond it, the call is refused with the time to wait.

Content written by third parties

Build logs, repository names, member names and scan results come from your repositories or from other people. They can contain text written to trick an assistant. The server returns them marked as such, stripped of control characters and recognisable secrets, and tells the client never to follow an instruction they contain. Keep manual approval before any action: it is the best protection.

What stays in the console

Some actions are not offered by the MCP server, because a mistake or a stolen token would cost too much: payments and plan changes, deleting, suspending or transferring the organization, member roles and removal, your identity (password, two-factor authentication, sign-in methods), creating or revoking tokens, adding a server, connecting a repository provider or another host, switching the DNS of a migration and rolling it back, and database and storage credentials. Do them from the dashboard.

A few natural-language requests you can make:

• "List my projects and their status."
• "Redeploy the api app of the shop project."
• "Add the domain app.example.com to the web container."
• "Mount the exports volume onto the worker app at /data."

Security

The MCP server enforces the same guardrails as the console:

• A token only sees its own organization, never anyone else's.
• Permissions are bounded by the current role of the member who owns the token, exactly as in the console: a Developer or Billing role keeps its limits, MCP included. If the role changes, the available tools follow.
• Every action that changes something, every refused call, and every token creation and revocation are logged with the token involved. Variable values never appear there, only their names.
• Lists never return the value of a variable. Revealing one is a separate, logged action that a token only gets if you ticked it when creating it.

Revoke a token at any time from Settings, Access tokens, with the Revoke button and its confirmation window. Revocation is immediate: the client loses access on its next call.