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.

Create a personal access token

Authentication to the MCP server uses a personal access token (PAT) you create in the dashboard. This token replaces your password for programmatic access.

Step by step

1. Open the dashboard, then Settings, then Access tokens (/settings/tokens).
2. Click Create token and give it a clear name (for example "Claude Desktop").
3. Copy the token shown right away and keep it somewhere safe.
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 all your permissions by default. You can instead tick a subset, reading projects and deployments only for instance, and give it an expiry date. Without one, it never expires.

The token list shows, for each of them, its state (active, expired, revoked), its creation date, its expiry date and its last use.

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.

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.

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"
      }
    }
  }
}

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 slug, 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 and details.
• List your custom domains and their status.
• List your servers (Pierrr Agent) and their state.
• List environment variables, with sensitive values masked.
• 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.
• 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 repositories.
• List your personal access tokens.

Actions

• Trigger a deployment.
• Restart, start, stop, build or delete an app.
• Start or stop every app of a project at once (scale).
• 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, reveal or delete a variable, apply a whole .env block at once, and manage per-container bindings.
• 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.

Preview before you act

Every self-hosted action, restarting, starting, stopping or building an app, deleting an app, and scaling a project, defaults to dryRun: true. The tool describes what it would do without touching your infrastructure; the client must explicitly pass dryRun: false to actually run it.

Two destructive actions additionally require confirm: true even with dryRun: false: deleting an app and restoring a backup. Without it, the call is rejected.

Platform-admin tools

The catalog also lists platform-admin tools (organizations, agents, monitoring, waiting list, audit log across every tenant). They are never advertised or executable for a regular organization token, only Pierrr's own operators can use them.

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 role of the member who owns the token.
• All actions are audited.
• No secret is ever exposed in plain text, values stay masked.

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