PlugLayer MCP Server

Deploy and manage your infrastructure through natural language with any MCP-compatible AI assistant.

Public plugin setup

Public PlugLayer plugins use the hosted MCP endpoint with OAuth. In the PlugLayer portal, choose Codex, Claude Code, Cursor, or Antigravity, copy the setup prompt, paste it into the agent, and approve PlugLayer in the browser. The agent stores and refreshes its OAuth connection. No Python, uv, terminal, desktop app, or API token is required.

The local commands below are an advanced developer path for explicitly running an MCP server on the same machine.

Local installation

Option 1: uvx (recommended — no install needed)

PLUGLAYER_API_KEY=your-pluglayer-api-token uvx pluglayer-mcp

This local command mode uses the MCP stdio transport by default, which is the right mode for Cursor, Claude Code, and other editor-launched command servers. The pluglayer-mcp command now always uses stdio so editor clients cannot accidentally switch it into HTTP mode.

Option 2: pip

pip install pluglayer-mcp
PLUGLAYER_API_KEY=your-pluglayer-api-token pluglayer-mcp

Configuration

For editor installations, PlugLayer also reads ~/.pluglayer/credentials.env on every tool call. Saving or rotating PLUGLAYER_API_KEY (and optionally PLUGLAYER_API_URL) there takes effect on the next call without restarting the server. A client's OAuth or generic mcp_auth action does not configure credentials for a local stdio server.

Claude Desktop

Add to ~/.config/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "pluglayer": {
      "command": "uvx",
      "type": "stdio",
      "args": ["pluglayer-mcp"],
      "env": {
        "PLUGLAYER_API_KEY": "your-pluglayer-api-token"
      }
    }
  }
}

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "pluglayer": {
      "command": "uvx",
      "type": "stdio",
      "args": ["pluglayer-mcp@latest"],
      "env": {
        "PLUGLAYER_API_KEY": "your-pluglayer-api-token"
      }
    }
  }
}

Use either this manual registration or the PlugLayer Cursor plugin's bundled server, not both. If both appear in Cursor's Tools & MCP settings, disable or remove the manual copy so tool calls cannot land on servers with different authentication state.

Remote HTTP (hosted)

The remote MCP server runs at https://mcp.pluglayer.com/mcp and uses OAuth metadata discovery. Add that URL in an agent's remote MCP settings and choose browser authentication; do not paste a PlugLayer API token into chat.

If you intentionally want to run the package itself as an HTTP MCP server, use:

pluglayer-mcp-http

Release Checklist

Before publishing a new pluglayer-mcp build:

1. Confirm local command mode still uses stdio by default.
2. Confirm PLUGLAYER_API_URL override works when pointed at a dev API.
3. Let the publish workflow stamp the package version from the UTC date/time, unique GitHub run ID, and run-attempt number. Do not reuse a published PyPI version or artifact filename.
4. Publish from the public repo main branch after reviewing the dev -> main PR.

After publishing:

1. Restart Cursor, Claude Code, or the MCP client you are testing.
2. If the editor still behaves like an older MCP build, remove and re-add the MCP server entry, then restart the editor.
3. Re-test with a simple command such as:
   • get_current_user
   • list_projects
   • get_compute_summary
   • list_my_feedback

Cursor Notes

• For command-based MCP setup, use uvx pluglayer-mcp.
• Do not force HTTP transport for local editor usage.
• pluglayer-mcp always uses stdio, which is the correct transport for Cursor-launched command servers.
• Only use pluglayer-mcp-http when you intentionally want to run the package itself as an HTTP MCP server.

Available Tools

The MCP calls the PlugLayer FastAPI backend instead of re-implementing backend business logic. Auth, roles, ownership, compute guards, and k3s orchestration remain in the backend. MCP and editor plugins should authenticate with a PlugLayer API token created in the PlugLayer Settings page, not the browser/session auth token.

Managed registries are configured by PlugLayer admins in the platform UI/API. When deploy_image uses mirroring, the backend picks a registry the current user is allowed to use and keeps Kubernetes pull secrets in sync automatically.

Runtime networking and replicas

get_app_access_policy and update_app_access_policy expose outbound policy separately from public ingress. egress_mode=deny_all permits DNS and same-project service traffic but blocks internet destinations. Use egress_mode=allow_cidrs with explicit IP/CIDR entries for a small set of external endpoints; the backend applies this as a per-app Kubernetes NetworkPolicy. allow_all preserves the platform's normal HTTP/HTTPS egress.

replicas creates independent pods. Public routes do not promise cookie or header session affinity, and HPA-style CPU autoscaling is not currently available through MCP. Stateful WebSocket or room-based services should use a single replica or externalize room state and routing until those controls are introduced.

Databases are a first-class Data Layer workflow in MCP. When a user needs a new database, wants to know whether one already exists, asks for a connection string, or needs env vars to wire an app to a database, the preferred MCP path is:

1. list_user_databases
2. if needed, list_database_templates
3. check_slug_availability
4. optionally check_database_slug_availability
5. create_database
   • the MCP tool resolves required deploy-time database env vars itself
   • password/secret/token/key fields are generated there when the template expects a random value
   • database-name placeholders are filled from the chosen app name
6. get_task_status
7. get_database_connection_details
8. optionally get_database_logs when troubleshooting
9. use update_database_access, restart_database, or remove_database for follow-up lifecycle actions

After provisioning a database, the assistant should proactively suggest or apply exact env var updates for dependent apps instead of leaving the user with only a raw connection string.

Marketplace template deployment through MCP now supports both:

1. deploying into an existing project by project_id
2. creating a new project inline by passing project_name

Example Conversations

Deploy your first app:

"I have a FastAPI app at ghcr.io/myorg/api:latest that runs on port 8000. Deploy it into my production project in my cloud."

Convert docker-compose:

"Here's my docker-compose.yml: [paste]. Deploy this to PlugLayer."

CI/CD setup:

"Generate a GitHub Actions workflow for my api app so every push rebuilds it, uploads it to PlugLayer, and redeploys the same app id."

The agent configures the existing app using its PlugLayer OAuth connection and reads repository metadata using the user's GitHub access. If access is missing, it guides one-time browser authentication. Hosted MCP never inspects the user's local filesystem; repository detection belongs to the agent.

The generated workflow builds an image and uses GitHub OIDC to obtain a short-lived, app-scoped deployment credential. Future pushes need no editor login and no PLUGLAYER_API_KEY secret. Optional PLUGLAYER_BUILD_ENV_JSON and PLUGLAYER_ENV_JSON remain application secrets; existing runtime variables are retained. Setup is verified only after GitHub and the PlugLayer rollout succeed. Workflow generation requires a published immutable OIDC Actions release configured in the backend; report that release prerequisite if generation is unavailable.

Add a custom domain:

"Add api.example.com to my production project, detect the provider, show me the DNS records in a table, then verify it and attach it to my API app."

For a root/www website pair, say whether both hostnames must work. PlugLayer routes exact hostnames, so example.com is not automatically covered when only www.example.com is attached. Configure the root separately or redirect it to www, then test a nested path such as /page-1 on both names.

Provision a database and wire the backend to it:

"Create a Postgres database in my marketplace project, check whether the slug postgres is available first, and after it finishes show me the connection env vars so we can update my backend."

Reuse an existing database instead of creating a new one:

"Check whether I already have a Mongo or Postgres database in my project. If I do, show me the connection details and suggest the backend env vars I should update."

Legacy local stdio credentials

Hosted editor plugins use browser OAuth. New GitHub workflows use OIDC. Neither requires users to manually copy a PlugLayer API key.

Self-managed local stdio installations may still use a user-issued PlugLayer API token stored in their local credential file or PLUGLAYER_API_KEY. Existing key-based Actions remain available for compatibility; migrating a workflow must not delete repository secrets still used by other jobs.

Template authoring

Use get_template_authoring_schema(section="create_draft") and preview_template_compose before saving with create_template_draft. The tools also list/read/update/clone/delete private drafts, submit for admin approval, expose launch context/planning/sessions, and update existing apps from templates. deploy_marketplace_template handles test deployments and accepts database_bindings. Public template tools do not publish or approve; those actions remain in the private Admin Center. Schema and context discovery default to summaries; fetch named sections and context pages as needed. Launch planning creates/resumes a session. close_template_launch_session archives it without cancelling tasks or deleting apps.

Run python scripts/test_local_template_mcp.py from this package for a focused read-only local stdio smoke using saved credentials. The new backend routes must be released before the corresponding MCP/plugin release can pass this check.

App security checks and traffic controls

“Check my apps” or “check my app security” starts with app inventory, status, recent runtime logs, and get_app_access_policy. The four public plugins bundle check-app-security and manage-app-access to distinguish abusive traffic from app faults, preserve legitimate clients, and carry authorized mitigations through verification. Check-only requests produce findings and concrete proposals.

update_app_access_policy uses PUT /v1/plugin/apps/{app_id}/access and the same backend workflow as the portal. Read the existing policy first and provide all values, including the unchanged ones. An empty allowlist opens source access; CIDRs must represent approved trusted clients, not suspected attackers. HTTP limits count requests per peer IP/route/Traefik instance; TCP limits cap concurrent connections. Neither replaces app authentication, and internal traffic bypasses public ingress controls. Saves need no restart.

Release the matching backend route before the MCP/plugins. Validate local stdio reads with python scripts/test_local_app_security_mcp.py; it uses saved public credentials and never changes live app settings or prints logs. This smoke does not prove policy writes or client enforcement; test those only on an explicitly authorized disposable app before releasing the update feature.