/mcp-access

name: mcp-access
description: Open the GBrain owner dashboard, manage MCP clients and permissions, or connect a native OAuth harness. Distinguishes owner administration from ordinary MCP access.
triggers:
  - "GBrain admin login link"
  - "open the MCP admin panel"
  - "manage MCP clients"
  - "register an MCP client"
  - "set up MCP OAuth"
  - "connect this harness to my hosted brain"
  - "invalidate MCP tokens"
  - "revoke an MCP client"
  - "delete an MCP client"
  - "edit MCP access levels"
tools:
  - exec
mutating: true
brain_first: exempt

MCP access and administration

Use [MCP administration](../../docs/mcp/ADMIN.md) for the exact commands and recovery table, [hosted setup](../../docs/guides/hosted-harness-access.md) for client installation, and [deployment](../../docs/mcp/DEPLOY.md) for the running service. If this skill is loaded remotely without those files, use https://raw.githubusercontent.com/garrytan/gbrain/master/docs/mcp/ADMIN.md. No local brain initialization or personal-agent bootstrap is required to administer an existing server.

Contract

Inspect the user's supplied endpoint and available configuration. A hosting harness may administer its own server only when it has that server's owner credential. A remote administrator needs the same separately supplied authority. An ordinary MCP OAuth token, client secret, `admin` scope, or full tool surface does not authorize dashboard login or client management.

Use `gbrain://capabilities` for effective MCP access and administration guidance when available. Its admin URL is orientation, not a login. Without owner authority, provide the exact owner-side command and prerequisite instead of trying successively broader OAuth scopes. Name the server-hosting or authorized administrator harness in the handoff, rather than asking an arbitrary agent.

Owner actions

Commands run against the **existing** server with `gbrain mcp admin … --url URL`. Use `--admin-token-file PRIVATE_FILE`, or the protected `GBRAIN_ADMIN_BOOTSTRAP_TOKEN` environment variable. Do not print their values. This HTTP path uses the live database connection; do not open a second PGLite process, delete its lock, or start another server to obtain administration.

• **Login:** `login-link` returns a sensitive, single-use URL for private delivery

to the requesting owner. Explain in the handoff that the plain `/admin/` URL requires an authenticated owner session; the owner signs in by opening the returned login link. Do not GET/fetch/open it for verification. If the pending OAuth browser URL carries `oauth_request`, pass that ID through `login-link --oauth-request ID`. The native client retains its PKCE verifier.

• **Inspect:** `clients` includes revoked registrations; `client ID` gives live

metadata and revision. List failure is not an empty list.

• **Create:** machine access uses `mcp grant NAME --harness ID` with a private

handoff. Native OAuth uses `mcp admin register NAME --redirect-uri URI`; choose the actual callback and authentication method, not a guessed vendor default.

• **Setup:** `setup ID --harness ID` reads the actual client method. For a mixed

registration, explicitly select `--flow authorization-code` or `--flow client-credentials`. Ordinary output contains no secret; confidential delivery/recovery requires `--credentials-out PRIVATE_FILE`.

• **Permissions:** `mcp grant NAME --client ID --if-version N --dry-run` previews

before/after. Omitted restrictions remain unchanged. Repeat without dry-run when the reviewed action is within the user's authorization. In the receipt, explain both consequences: removed authority applies immediately; expanded scopes require fresh native authorization or a newly issued machine token. Refresh cannot expand the original scope grant.

• **End access:** `invalidate-tokens ID`, `revoke ID`, and `delete ID` preview

consequences by default; apply an authorized reviewed action with `--yes --if-version N`. Explain that invalidation removes access/refresh tokens and authorization codes and invalidates pending approvals; it retains the active client and secret, so machine credentials can obtain new tokens. Revocation disables access; deletion removes its registration while audit history remains. Never substitute one for another silently.

A failed transport after a mutation was sent can mean **unknown outcome**. Inspect the existing client before retrying. Recover a committed secret delivery instead of creating a duplicate. Journal recovery is preferred to secret rotation. The legacy local `agent register --reissue` path has specific limits; consult ADMIN.md rather than inventing a remote rotation command. When handing recovered native setup back to a client, include both remaining connection steps: the native client starts PKCE authorization and the owner reviews and approves consent. Secret recovery alone establishes neither step.

Native OAuth connection

The client initiates authorization and owns its verifier. Public PKCE uses `token_endpoint_auth_method: none` and has no secret. Confidential PKCE uses the client's actual POST/Basic method and a protected secret delivery. An `OAuthClientSetup` file is not a machine handoff for `gbrain connect`.

Verify the connection with an authenticated call from the native harness, such as reading `gbrain://capabilities`. For an authorized memory round trip, follow the hosted guide and inspect the advertised tool schemas. Remote `recall` and `forget` operate on `world`-visible facts within the client's source grant: use only a harmless synthetic fixture with `visibility: "world"`, retain its returned ID for cleanup, and never change real private facts' visibility to pass a test.

Owner login leads to a separate consent review. An expired request or server restart requires restarting the connection **in the native client**; a new login link does not recreate authorization state. Self-service DCR is opt-in and never bypasses owne