mcp-access

MCP access and administration

Use MCP administration for the exact commands and recovery table, hosted setup for client installation, and deployment 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.