Local server and CLI

Most assistants should use the hosted server, which signs in through your browser. Two other routes run on your own machine and use the CLI’s login instead:

	edgible mcp server	The CLI with -o json
Works with	Assistants that speak the Model Context Protocol and can start a local server (Claude Code, Cursor, VS Code, and others)	Any assistant that can run shell commands
Reach	Inspect applications and devices; optionally change or restart an application	Every edgible command
Writes	Off until you start the server with --allow-write	Whatever you let it run
Use it for	CI and other places without a browser; letting an assistant make changes	Coding agents in a terminal

Both act as the CLI profile you are signed in to, and can do what that account can do and nothing more.

Before you start

Sign in once in a terminal. Both routes reuse that session, and refresh it on their own:

edgible auth login
edgible whoami

If you work in more than one organization or environment, pick the profile first with edgible profile use <name>, or pass --profile <name> in the assistant’s configuration (see below).

Caution

Everything an assistant reads is sent to the model provider behind it, including application configuration and workload logs. Do not point an assistant at an organization whose logs you cannot share with that provider. Never paste secret values into a chat. Store them with edgible secret set and refer to them by name.

The edgible mcp server

edgible mcp runs on your machine and talks to the assistant over standard input and output. It starts read-only. Add it to your assistant’s configuration as a command; you do not run it by hand.

Claude Code

claude mcp add edgible -- edgible mcp

Cursor

Add this to .cursor/mcp.json in a project, or ~/.cursor/mcp.json for every project:

{
  "mcpServers": {
    "edgible": { "command": "edgible", "args": ["mcp"] }
  }
}

VS Code

Add this to .vscode/mcp.json:

{
  "servers": {
    "edgible": { "type": "stdio", "command": "edgible", "args": ["mcp"] }
  }
}

Use a specific profile

Global flags go before the subcommand, so a profile is chosen like this:

claude mcp add edgible -- edgible --profile work mcp

In the JSON files above, use "args": ["--profile", "work", "mcp"].

In CI

A pipeline can’t sign in through a browser, so it signs in with an email and password. Make a member for the pipeline, give it the Read-only role, and keep its credentials in the CI system’s secret store:

edgible auth login \
  --user-email "$EDGIBLE_EMAIL" \
  --user-password "$EDGIBLE_PASSWORD"
edgible mcp

The member’s role caps every tool, whatever the server’s flags say: a Read-only member can’t change anything even with --allow-write.

What the assistant can do

Read-only (always available):

Tool	What it returns
whoami	The account, profile, environment and organization, and whether writes are enabled
list_applications	Each application’s id, name, status, hostnames and serving devices; can filter by tag
get_application	One application’s record and its current configuration as a JSON document
get_application_status	Deployment state, why a deploy is stalled, and which devices run the current release
get_application_logs	Recent output of the application’s own workloads, per device
list_devices	Each device’s id, name, type, status, last seen and agent version
preview_application_change	What a change would do, without making it

With --allow-write:

Tool	What it does
apply_application_change	Applies a change to an application’s configuration
redeploy_application	Restarts the application’s workloads, for example to pick up a changed secret

The server cannot create or delete applications, devices or secrets, install the agent, or read secret values. Use the CLI for those.

Turn on changes

Start with read-only access. When you want the assistant to make changes, add --allow-write:

claude mcp add edgible -- edgible mcp --allow-write

A change is a JSON Merge Patch against the configuration that get_application returns: an object merges into the current document, null removes a key, and an array replaces the whole array. The assistant is told to work in two steps:

1. preview_application_change lists every change and marks it live, restart, disruptive, or fixed (cannot be changed in place). Nothing is written.
2. apply_application_change makes the change. It carries the version the preview was based on, so if someone else changed the application in between, the change is refused and the assistant has to read the application again.

A disruptive change is not applied unless the assistant passes confirm: true. Without it, the tool returns the list of impacts and changes nothing. A well-behaved assistant shows you that list and asks before it confirms. Your assistant’s own tool-approval prompts are a second check; keep them on for the two write tools.

Workload environment values are hidden in everything the server returns, and a patch that carries the hidden placeholder is rejected, so an assistant cannot write the placeholder over a real value. Changing environment values is therefore a job for edgible application update --env or --secret in your own terminal.

When it does not work

• A tool returns “Not signed in”. Run edgible auth login in a terminal, then retry.
• The server does not start. Run edgible mcp once in a terminal. It prints nothing and waits for input, which is correct; press Ctrl+C. An error message here means the CLI itself is not working. Run edgible --version and edgible whoami.
• The assistant cannot find edgible. Use the full path to the binary as command (which edgible shows it). Editors started from a launcher do not always see your shell’s PATH.
• Nothing appears on screen. That is by design: standard output is the channel to the assistant. Diagnostics go to standard error, which most assistants show in their MCP log.

The CLI with -o json

An assistant that can run commands needs three habits, all of which the CLI already supports.

Ask for JSON. Pass -o json before the subcommand. It is also the default whenever the output is piped, so a captured command already returns JSON, but saying it removes the guesswork.

edgible -o json application list
edgible -o json application get web
edgible -o json device list

Preview before you change. Configuration changes take --dry-run, which prints what would change, with each change marked live (no restart), restart, or disruptive, and writes nothing.

edgible -o json application update web --port 8080 --dry-run
edgible application update web --port 8080

Disruptive changes (removing a hostname, renaming, changing a public port) are refused unless the command carries --confirm. Add --non-interactive so the command fails with an error instead of waiting for an answer nobody can type. Give the assistant --confirm only after you have read the dry run.

Read the exit code and the error. With -o json, a failure prints one JSON document to standard error and sets a meaningful exit code:

{ "error": { "code": "CONFIRMATION_REQUIRED", "message": "...", "requestId": "..." } }

Exit code	Meaning
0	Success
1	Unexpected or server error
2	Usage or validation error
3	Not signed in, or not allowed
4	Not found
5	Conflict, or the change needs confirmation
6	Rate limited
7	Network error or timeout

Commands that only perform an action, such as application delete or application redeploy, report their result through the exit code rather than a JSON document.

To teach an assistant the commands, point it at edgible --help and edgible <noun> --help, or at the CLI reference.

Related

• edgible mcp reference
• Application YAML reference
• Diagnose a broken app