How to use the MCP access and admin agent skill

What the mcp-access skill makes the agent do

An agent skill is a folder with a SKILL.md file that gives an agent extra instructions for a specific task. When this skill is installed, the agent knows how to administer a GBrain server you already run. It can generate single-use owner login links for the admin dashboard, register or grant access to MCP clients, preview and apply permission changes, and revoke, invalidate or delete client access.

The skill also explains how to connect a native OAuth client and how to recover from failed or unclear operations. It is about administration, not daily use. Someone who only reads or writes notes through an already connected client does not need it.

• Open the owner dashboard by generating a login link
• Create, inspect and grant access to MCP clients
• Preview and apply permission changes before they take effect
• Revoke, invalidate tokens for, or delete client access
• Walk through native OAuth setup and recover from failed operations

Install the mcp-access skill

Download the ZIP for this skill from this page. Unzip it into one of two places. For a personal setup, use ~/.claude/skills/. For a single project, use the .claude/skills/ folder inside that project.

If you use the Claude apps instead, open Settings, then Capabilities, then Skills, and upload the skill there.

• Personal install: unzip into ~/.claude/skills/
• Project install: unzip into .claude/skills/ in your project folder
• Claude apps: Settings → Capabilities → Skills, then upload

What you need before the agent can help

The skill does not grant any authority. The agent cannot log in on its own, so you need the following before you start. The skill's own requirements list them, and the agent will stop if any are missing.

• GBrain CLI, meaning the gbrain command with its mcp admin subcommands
• Access to a running GBrain server URL
• An owner admin token, supplied either as a private file or through the GBRAIN_ADMIN_BOOTSTRAP_TOKEN environment variable
• Permission for the agent to run gbrain commands through its exec tool

Trigger the skill with natural requests

You do not need special syntax. Ask in plain language, and the skill's triggers will match phrases such as the ones below. The listed triggers are examples; wording close to them should work too.

Keep requests specific about the goal. Saying what client you are connecting, or which access you want to change, helps the agent pick the right commands.

• "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"

Example workflows

Before any change, the agent previews it. For a permission change, it runs the grant command with a dry-run flag, which shows the before and after state. Once you approve the reviewed action, it applies the change. Removed authority takes effect immediately. Expanded scopes need fresh native authorization or a newly issued machine token.

Ending access works the same way. Invalidating tokens removes access and refresh tokens and authorization codes, but keeps the client and its secret, so a machine credential can still obtain new tokens. Revoking disables access. Deleting removes the registration while audit history remains. The agent will not treat one of these as a substitute for another.

• Give a new AI assistant access to your hosted brain for machine use
• Set up a native OAuth client that asks you to approve consent in your browser
• Narrow an existing client's permissions after a review
• Stop a client from using old tokens while keeping its registration
• Permanently remove a client you no longer use

Safety notes: scripts and network

This skill runs scripts and uses the network. Its commands run against your server's HTTP endpoint, using the live database connection. The agent should not open a second local database process, delete its lock, or start another server to get administrative access.

The skill also follows strict rules. It previews before changing anything. It never prints secrets. It never tries broader OAuth scopes to get around a missing permission. Login links are sensitive and single-use, so they should be delivered privately to the owner. Because commands can create, change or delete access to a personal knowledge base, only use this skill with servers you own or trust.

• Use only with servers you own or trust
• Tokens are read from a private file or protected environment variable and are not printed
• Preview first, then apply with an explicit confirmation
• If a request fails after it was sent, the agent re-checks the client list before retrying

Tips and troubleshooting

If you see insufficient_scope or invalid_token on an MCP call, the problem is a grant the owner must change. The agent should tell you which scope is missing rather than trying broader scopes. If a list call fails, that is an error, not an empty list. If a tool is missing, the grant diagnosis explains which blocker is involved.

When you hand recovered native setup back to a client, remember that two steps remain. The native client starts PKCE authorization, and the owner reviews and approves consent. Recovering a secret alone does not finish the connection.

• Read the error code before changing anything
• Treat a failed list as unknown, not as empty
• Owner login leads to a separate consent review
• An expired request or server restart means restarting the connection in the native client
• A new login link does not restore an expired authorization request