mcp-app Admin

Overview

This skill covers operating mcp-app solutions — connecting the admin CLI, verifying a deployment end-to-end, managing users and credentials, and registering MCP clients. It applies regardless of how the solution was deployed — Cloud Run, Docker, bare metal, k8s, or any other environment.

This skill is the third stage of the mcp-app solution lifecycle:

1. Author — code, structure, local validation. Owned by

author-mcp-app.

1. Deploy — turn a validated working tree into a reachable

URL that passes a minimal health check. Owned by neither mcp-app skill — the operator's environment supplies the route (a deployment skill, plugin, script, or context).

1. Operate — this skill. Assumes a known URL that has

already passed GET /health → {"status": "ok"}.

This skill does NOT deploy. It does NOT discover deployments. It does NOT decide where the URL came from. If the operator does not yet have a healthy URL to point at, that is a stage-2 problem — either the operator's agent environment provides a deployment route, or the operator handles deploy out-of-band — and this skill waits.

Verification of a freshly deployed instance is non-optional. Whenever this skill is invoked immediately after a deploy (or whenever the operator suspects the running instance has changed), the verification ladder in Step 3 is mandatory before declaring the deploy successful. GET /health returning ok is necessary but not sufficient — probe and (when the solution declares one) safe-tool --invoke are the actual contracts the operator relies on. Skipping past them with raw curl or cloud CLI inspection is the wrong move; this skill is the route, not a fallback.

Where this skill fits — user journey map

Every mcp-app solution supports six recurring journeys across three audiences (developer, operator, end user). The author-mcp-app skill enumerates the full map. This skill owns journeys 4–6:

• Journey 4: Connect admin CLI post-deploy — retrieve the

signing key, point the admin CLI at the deployed instance (or the local store), persist the per-app config.

• Journey 5: Manage users and credentials — add, list,

revoke, issue tokens, read profiles (users get-profile), rotate profile fields (users update-profile).

• Journey 6: Verify end-to-end and register MCP clients —

probe for the framework layer, tools list/show/call for discovery and ad-hoc invocation, safe-tool --invoke for the opinionated end-to-end smoke test (when declared), and register to emit Claude Code, Gemini CLI, and Claude.ai URL-form commands.

Journeys 1–3 (install, run locally, deploy) are outside this skill's scope. Install and local-run live with the app's own README and (for agents) author-mcp-app. Deploy lives with the operator's own deployment tooling — a deployment skill or plugin, in-repo scripts, or operator/user-level context describing how this operator deploys mcp-app solutions. This skill assumes a healthy URL produced by some stage-2 path; it does not produce one.

Audiences

• Deploying operator — just finished a deploy, needs to

connect, verify, and register the first user.

• Returning operator — coming back months later to rotate

a credential, add a user, or investigate an issue. May not remember how the app was deployed. Should be able to reconstruct the operational state from the app's own docs and the per-app admin CLI config.

• Agent-operator — an AI agent performing admin operations

on behalf of a human. Relies on structured output (--json), deterministic commands, and self-documenting CLI help (profile field descriptions).

The returning operator is the most frequently neglected audience and the one this skill most explicitly serves. If a workflow requires the operator to remember something not captured in the app's docs or the admin CLI's persistent config, flag it as a gap.

Before You Start

At the start of any session involving admin operations, check the current connection state before doing anything else:

my-solution-admin health        # remote — confirms URL and auth
my-solution-admin users list    # local or remote — confirms store access

Do not assume the admin CLI is pointed at the right target. The connection may be stale from a previous session, pointed at a different environment, or not configured at all. Verify first.

Prefer the per-app admin CLI (my-solution-admin) over the generic CLI (mcp-app). The per-app CLI stores connection config per app in ~/.config/{name}/setup.json — each app remembers its own target independently. The generic CLI stores one connection at a time and overwrites on each connect.

The framework tracks one connection per app (a single deployment environment, whether local or remote). If the same app is deployed to multiple environments, connect switches between them but only remembers the last one configured.

Troubleshooting: when a client reports the MCP isn't working

Most "my MCP connection failed" reports do not require guessing at signing keys, poking at curl commands, or reading framework source. Run one command first and let its output narrow the problem:

my-solution-admin probe

Probe walks the full stack: /health for liveness, admin signing verification, and an MCP tools/list round-trip using a short-lived token minted for an existing user. The point at which probe fails tells you which layer is broken.

Decision tree

Why probe first

The server returns the same {"error": "Invalid or revoked token"} body for at least three distinct causes: (a) JWT signature doesn't verify, (b) the user has been revoked, (c) the solution-specific backend credential on the user's profile is invalid or expired. Curl output alone cannot distinguish these. Probe exercises each layer with known-good inputs (the admin CLI's own signing key, a freshly minted token) and isolates the failing layer without ambiguity.

Scope: what mcp-app does and doesn't own

mcp-app is responsible for signing-chain integrity and user access control (revocation, token issuance). The framework is not responsible for whether the solution's backend credential — the token or API key the solution uses to call its upstream on behalf of the user — is still valid. That credential lives on the user's profile, its schema is declared by the solution, and its validity depends on whatever upstream service the solution targets. When probe reports admin + MCP working but the client still misbehaves at a tool-call level, assume a solution-specific issue and consult the solution's docs or admin CLI help.

Step 1: Retrieve the Signing Key

The signing key is required for admin operations on remote instances. Its location depends on how the solution was deployed:

• `mcp-app deploy` via a cloud provider → the provider's

own secret-resolution mechanism (typically a cloud secret manager); retrieve via mcp-app signing-key show or the provider's surface.

• Bare `gcloud run deploy` with `--set-secrets=` → stored

directly in Secret Manager; retrieve via gcloud secrets versions access latest --secret=....

• Any other opinionated deploy tool → stored wherever the

tool puts it; consult that tool's documentation or CLI.

• Manual deploy (any CI, docker, systemd, etc.) →

wherever the operator put it when setting up the deploy; investigate the deploy configuration.

For anything other than mcp-app deploy, the app admin CLI is connected manually:

my-solution-admin connect <url> --signing-key "$(retrieve-it-somehow)"

How to find it

Start with the deployment configuration. Look at how the solution was deployed and how SIGNING_KEY was configured:

• gapp with a generated secret — retrieve from GCP Secret

Manager using the secret name from gapp config. Run from inside the solution's repo directory (gapp resolves the solution from the working directory):

  cd <solution-repo> && gapp secrets get <secret-name> --plaintext

• Cloud secret manager (GCP, AWS, etc.) — the key was

stored there by the deployment tool or manually:

  # GCP
  gcloud secrets versions access latest --secret=SECRET_ID --project=PROJECT_ID
  # AWS
  aws secretsmanager get-secret-value --secret-id SECRET_ID

• Terraform managing the secret — check Terraform state:

  terraform output -raw signing_key

• Docker Compose — check docker-compose.yml for the

secret source (file path, env var, Docker secret).

• CI/CD secrets (GitHub Actions, GitLab CI) — these are

write-only from the UI. If this is the only copy, generate a new key, update the CI secret, and redeploy.

• Environment variable set manually — check the process

environment or the shell/systemd/supervisor config.

If you can't find it

Generate a new one, store it wherever the deployment expects it, redeploy, and re-register all users (existing tokens become invalid):

python3 -c 'import secrets; print(secrets.token_urlsafe(32))'

When credential retrieval is sandbox-denied (agents)

An agent operating in a sandboxed environment may find that the plaintext signing-key fetch — whether via an MCP tool that returns the secret value, a gcloud secrets versions access call, or any other direct retrieval — is denied by the environment's permission policy. This is intentional: pulling a live production credential into an agent's transcript context needs explicit per-action authorization.

When this happens, do not downgrade verification. A common failure mode is to skip connect, skip probe, skip safe-tool --invoke, and substitute curl /health plus cloud-CLI inspection of the running revision. That is not equivalent — it verifies the process is alive but not that the deployment serves tools end-to-end, and it leaves the actual operator workflow (connect, probe, manage users, register clients) un-exercised.

Use the user-executed pattern instead. Ask the user to run the connect command themselves so the secret never enters the agent's context. The exact mechanism depends on the agent platform — most platforms expose some way for the user to run a shell command in-session whose output stays out of the agent's transcript (for example, a !-prefix in some interactive agents). When that's available, ask the user to run something like:

my-solution-admin connect <url> --signing-key "$(<retrieval cmd>)"

…where <retrieval cmd> is the appropriate gcloud secrets versions access ..., aws secretsmanager get-secret-value ..., deployment-tool secret-get command, or terraform output -raw ... for the operator's environment. After the user runs that, the per-app connect config persists the URL and key for this session and future ones; the agent can then proceed with probe and the rest of Step 3 normally without ever having seen the key.

If the agent's platform offers no in-session shell execution, ask the user to run the equivalent command in their own terminal and confirm when connect has succeeded. Then continue.

The point: a permission denial is a routing signal, not a signal to substitute a weaker verification path.

Step 2: Connect the Admin CLI

Check if the app's own admin CLI is available:

which my-solution-admin

If not found, install the package. Check pyproject.toml for [project.scripts] to find the entry point name:

pipx install git+https://github.com/owner/my-solution.git
# or from a local clone:
pipx install -e .

Then connect:

# Per-app CLI (preferred) — local or remote
my-solution-admin connect local
my-solution-admin connect https://your-service --signing-key xxx

# Generic CLI (fallback) — remote only
mcp-app connect https://your-service --signing-key xxx

connect local is only available on the per-app CLI — the generic CLI doesn't know which app's store to locate.

Step 3: Verify the Deployment

The verification ladder has six rungs. Stop at the first one that reveals the issue; otherwise climb until the deployment is fully validated.

1. `connect` — point the admin CLI at the deployment.
2. `probe` — framework layer (liveness, admin auth,

tools/list round-trip).

1. `tools list` — confirm the solution's tools module

loaded and tool names match expectations.

1. `tools show <name>` — when the schema for a specific

tool needs a sanity check.

1. `safe-tool --invoke` — opinionated end-to-end smoke

test (only if the solution declared one).

1. `tools call <name>` — debug a specific tool with custom

arguments when steps 2–5 leave a gap.

3a: probe

my-solution-admin probe

Output:

URL: https://your-service
Health: healthy
MCP: ok (probed as [email protected])
Tools (3):
  do_thing
  list_items
  get_status

This hits /health for liveness, then does an MCP tools/list round-trip using a short-lived token minted for an existing user. If it reports tools, the framework layer is operational — health, admin auth, user auth, MCP transport, and tool wiring all work.

If no users are registered yet, probe reports liveness only and tells you it can't do the MCP round-trip. Register a user first (Step 4), then probe again.

For structured output (agent consumption):

my-solution-admin probe --json

3b: tools list / show

probe confirms the framework layer. tools list is a quick sanity check that the right tools are exposed:

my-solution-admin tools list
my-solution-admin tools show <name>
my-solution-admin tools list --json     # for agent consumption

tools show <name> renders the description, arguments with type/required-ness, and a copy-pasteable tools call invocation example. Useful when you don't remember a tool's schema or want to debug a specific tool's contract before calling it.

Requires a registered user. Unlike probe, which can report liveness-only when the deployment has no users, tools list and tools show mint a per-user probe token to do the MCP tools/list round-trip. On a deployment with no registered users they exit with a clean error pointing at users add rather than degrading to a liveness check — because there's no useful "tools list" output to render without the round-trip. Run Step 4 (users add) first if you haven't.

3c: safe-tool --invoke (deeper than probe)

Probe stops at tools/list. It does not exercise the solution's tool handlers, the upstream credential on the user's profile, or the response-shape contract a real client depends on. safe-tool --invoke does — when the solution declared a safe tool:

my-solution-admin safe-tool                # show declaration only
my-solution-admin safe-tool --invoke       # full end-to-end round-trip
my-solution-admin safe-tool --invoke --json

The CLI prints the JSON-RPC request body before sending so an operator can copy and replay it manually in a debugger or another terminal, with a different bearer token, etc. After the call it prints the HTTP status code and the full response body.

`safe-tool --invoke` requires a registered user for the same reason as tools list/show: the round-trip mints a per-user probe token. The bare safe-tool (no --invoke) only fetches the declaration metadata and does not need a user — handy for confirming the safe tool is declared on a fresh deployment before you've added any users.

#### Failure-mode table

Note: --json is the canonical agent-consumption path. The envelope is versioned (schema_version: "1") and additive-only — consumers must tolerate unknown fields.

#### Privacy note for agent operators

safe-tool --invoke returns a curated, low-PII response that is safe for an agent to read. `tools call` is not curated and may return user content. When agent-driven validation must not see user-authored data, prefer safe-tool --invoke and rely on the response envelope contract.

3d: tools call (open invocation)

When safe-tool --invoke isn't declared, or you need to invoke a different tool with custom arguments to isolate an issue:

my-solution-admin tools call <name> --arg k=v --arg k2=v2
my-solution-admin tools call <name> --body '{"k": "v"}'
my-solution-admin tools call <name> --body @args.json
my-solution-admin tools call <name> --user [email protected]   # mint as alice

--arg is for scalars (booleans, numbers, strings, null) and type-coerces from the tool schema. Use --body for objects and arrays.

tools call may return PII or user-authored content. Operators running it interactively are implicitly accepting that.

Manual verification (if the CLI isn't enough)

# Liveness
curl https://your-service/health

# Admin auth
my-solution-admin users list

# User auth — tools/list with a user token
curl -X POST https://your-service/ \
  -H "Authorization: Bearer USER_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}'

Step 4: Manage Users

Register a new user

# Data-owning app — no profile needed
my-solution-admin users add [email protected]

# API-proxy app — profile via typed flags (field names are solution-specific; see `users add --help`)
my-solution-admin users add [email protected] --<field> <value>

users add rejects existing users. If the user already exists, use update-profile instead.

To discover what profile fields the app expects, check the --help output — field names and descriptions are generated from the app's Pydantic profile model:

my-solution-admin users add --help

Read the current profile

my-solution-admin users get-profile [email protected]
my-solution-admin users get-profile [email protected] --json

When the solution has a registered profile model, the per-app CLI shows every declared field with its current value or (missing), and tags any extra stored keys as (not in profile model). This is how you confirm what's actually stored before rotating, or verify a credential rotation landed.

Update credentials

Field names are solution-specific — discover them from my-solution-admin users update-profile --help, which lists valid keys generated from the solution's profile model.

# Typed key (expand=True apps) — key is validated, tab-completable
my-solution-admin users update-profile [email protected] <field> <new-value>

# JSON merge (expand=False apps)
my-solution-admin users update-profile [email protected] '{"<field>": "<new-value>"}'

Use this to rotate backend credentials without re-registering the user. Only the specified field is changed — other profile fields are preserved.

Other user operations

# List all users
my-solution-admin users list

# Revoke a user (invalidates all their tokens immediately)
my-solution-admin users revoke [email protected]

# Issue a new token for an existing user
my-solution-admin tokens create [email protected]

Token lifecycle

• Tokens are long-lived by default (~10 years) because MCP

clients cannot refresh tokens automatically.

• Revocation is the primary access control — users revoke

sets a cutoff timestamp, and all tokens issued before that moment are rejected.

• After revoking, issue a new token with tokens create to

reactivate the user.

• The token from users add or tokens create is what the

user configures in their MCP client.

Step 5: Register MCP Clients

Use register to generate ready-to-paste commands:

# With a real token (mints one for the user)
my-solution-admin register --user [email protected]

# With a placeholder (operator substitutes later)
my-solution-admin register

This outputs commands for Claude Code, Gemini CLI, and the Claude.ai URL form, with the URL and token already substituted.

For structured output:

my-solution-admin register --user [email protected] --json

Filter by client or scope:

my-solution-admin register --user [email protected] --client claude --scope user

Manual registration (if register isn't available)

stdio (local):

claude mcp add my-solution -- my-solution-mcp stdio --user local
gemini mcp add my-solution -- my-solution-mcp stdio --user local

HTTP (remote):

claude mcp add --transport http my-solution \
  https://your-service/ \
  --header "Authorization: Bearer USER_TOKEN"

Claude.ai / Claude mobile:

https://your-service/?token=USER_TOKEN

Pointing the admin CLI at a solution deployed outside mcp-app

However the solution was deployed — bare gcloud, docker, systemd, a CI pipeline, anything — the admin flow is the same: connect the admin CLI at the URL, supply the signing key, and use the normal admin commands.

my-solution-admin connect https://my-service.example.com --signing-key xxx
my-solution-admin users add [email protected]
my-solution-admin probe

The generic mcp-app CLI works the same way when the per-app admin CLI isn't installed (see below). Both interfaces hit the same admin REST API exposed by the running service.

When to Use the Generic CLI

If the app's own admin CLI (my-solution-admin) isn't installed — e.g., managing a deployed instance from a machine without the app's repo — use the generic mcp-app CLI:

mcp-app connect https://your-service --signing-key xxx
mcp-app users add [email protected] --profile '{"<field>": "<value>"}'
mcp-app users get-profile [email protected]
mcp-app probe
mcp-app register my-solution --user [email protected]

The generic CLI works but doesn't have typed profile flags, model-aware get-profile output, or connect local. Always prefer the per-app CLI when available.

Important Notes

• `connect` and `deploy` are independent. Deploying a

service does not automatically connect the admin CLI to it. After deploying, explicitly run connect before admin operations.

• User management is an mcp-app concern, not a deployment

tool concern. Admin endpoints and the CLI are part of the framework.

• Admin tokens are generated locally using the signing

key — they don't pass through the deployed service.

• **The signing key retrieval method depends on the deployment

tooling.** This skill can't prescribe a single command — investigate the deployment configuration to trace where the key lives.