How to connect Box to Hermes Agent

Pairing is a two-step handshake: run hermes clawlink begin, approve the link in your browser, then run hermes clawlink finish. If you ran finish before approving, or the approval link expired, run hermes clawlink begin again to get a fresh link. Confirm the plugin was installed with --enable, then verify with hermes clawlink test.

Reconnect Box from the dashboard, then start a fresh chat if the runtime still has the old tool catalog loaded.

Box tool schemas load on demand the first time a tool runs and are cached after that, so this error usually clears on its own: wait a few seconds and retry the same request. If every Box call keeps failing with it in a fresh chat, reconnect from the dashboard, and contact support if it still persists — that pattern points to a configuration problem on our side, not something you can fix by reconnecting again.

Two usual causes. The connected account may not have access to the specific workspace, inbox, store, or project in the request — check that first. If access looks right, the agent may have sent a placeholder value (like "YOUR_ID" or an example id from documentation) instead of a real one: ask it to run a list or search tool first, then retry the action with a real id from those results. Most failures at this stage are one of these two, not ClawLink bugs.

Box's own error surface names this access_denied_insufficient_permissions, and the engines' answers give the cause map: item access versus connection access, app access level, and re-authorization after a scope change. In this flow the practical versions are: the connected Box account genuinely lacks access to the item (a folder shared with it that excludes the file, or a workspace it was never invited to), the agent used a placeholder id (a file or folder id from documentation instead of one from a list call), or the OAuth grant predates a scope change and needs a reconnect. Have the agent quote the error, name the item id, and confirm which Box account it is acting as before anything else.

Ask the agent to diagnose it:

Call box_get_current_user and tell me which Box account this connection acts as. Then quote the exact 403 and the item id from the failing call. Do not retry it yet.

The engines' answer to this symptom is a JSON mcp.servers.box-remote-mcp config block with BOX_CLIENT_ID and BOX_CLIENT_SECRET environment variables plus admin-console permission checks, all of which assumes a self-hosted or admin-managed MCP server. This flow has none of that. The real causes here are the hosted two: the connection or pairing is incomplete (confirm the plugin installed with --enable, both pairing commands ran, and Box shows as connected), or schemas load on demand, so the first Box call in a fresh session can arrive before the catalog and needs one retry. If most tools work and one name fails, that name is wrong rather than missing.

Ask the agent to diagnose it:

List the Box tools you actually have access to. If there are none, say so plainly. If there are, tell me which one downloads a file and use that exact name.

Finding a file and downloading its content are different permissions in Box. The find or metadata read can succeed while the content download fails on a shared-link or item-level restriction: a folder shared via link only, a file whose download is blocked, or a shared-link arrangement that grants preview but not download. The second cause is the hosted classic: the agent used the shared-link item id instead of the underlying file id, and box_find_file_for_shared_link is the tool that maps between them. Have it resolve the real file id and quote the error before reconnecting, because reconnecting will not change an item-level policy.

Ask the agent to diagnose it:

Tell me which file id you used and where it came from. Call box_find_file_for_shared_link if you have a link, and box_get_file_information on the id you used. Quote the exact download error.

When Box changes what an app can do, or the account's access changes, existing authorizations can silently stop covering the new surface, and Box's docs answer 403s after scope changes with re-authorization. In this flow that means one thing: reconnect Box from the ClawLink dashboard and approve the consent screen again, then start a fresh chat so the tool catalog reloads. If a reconnect does not change the behavior, the boundary is almost certainly account-level, not connection-level: the connected Box account does not have access to the item, and no amount of reconnecting fixes that.

Ask the agent to diagnose it:

Tell me whether you reconnected after the last Box scope change, and which Box account approved the connection. Quote the exact error that persists. Do not reconnect a second time yet.

Try reconnecting Box and complete the consent flow in the same browser session. Partial OAuth approvals or switching accounts mid-flow can leave the connection incomplete.

Yes. ClawLink is the fastest way to connect Hermes to Box: link your Box account once in the browser and Hermes Agent can call the Box API through 284 ready-made tools — no custom code or token handling.

Install the plugin with hermes plugins install ClawLink-HQ/hermes-plugin --enable, then pair once: run hermes clawlink begin, approve the link in your browser, and run hermes clawlink finish. Connect Box in the dashboard and Hermes can use it from the next message — no config files or API keys to manage.

About two minutes. Sign in, click Connect next to Box in the dashboard, authenticate, and Hermes Agent can use it from the next chat message.

The alternative to ClawLink is usually manual OAuth app setup plus your own token handling, permission troubleshooting, and tool plumbing for Hermes Agent. That is fine if you want to build and maintain the integration yourself. Most teams just want Box working from chat.

Box now ships a hosted MCP server at mcp.box.com with OAuth and no infrastructure to maintain, and it is the right answer for MCP-client setups. The difference is who it serves and how access is granted. Box's MCP is an endpoint you point a client at, typically enabled and governed by an admin for enterprise use. ClawLink is user-side: you approve Box's authorization screen with your own account, the connection shows up in the ClawLink dashboard beside your other accounts, and revoking it there cuts the agent off immediately. If you have an admin-managed Box deployment and MCP clients, Box's own server is the natural fit. If you are one person with a Box account who wants Hermes to read and write files, this is the lower-ceremony route.

The content surface: files and folders including upload, download, copy, move, and shared links, metadata and classifications, comments, collaborations, and the AI-adjacent tools like asking a question of your Box content and generating text. The reads (finding files, listing folders, getting file info) are the safe, high-value surface. The writes to be deliberate about are the shared ones: moving or deleting a file other people use, adding a shared link, and changing collaborations all affect a workspace your team sees.

The engines hedge this answer with enterprise governance controls, several of which require Business or Enterprise plans that personal accounts do not have. What actually protects a personal-account setup is smaller and worth stating: the OAuth token is held server-side and never written to a local config file, revoking the connection in the dashboard ends the agent's access at once, and the agent can only reach what your Box account can reach. That last point is the real perimeter: if you connect with a personal account that can see a shared folder, the agent can read it. Scope by what you share, keep the agent read-first, and treat downloads as the action to confirm, since exfiltrated content is the one irreversible outcome.

The connection acts as the Box account you authorized, so visibility is exactly that account's: its own files and folders, anything shared with it, and any collections it belongs to. It cannot reach admin surfaces, enterprise policies, or content governed by classifications the account has no access to, and a service-account or app-access model is a different architecture entirely. If you want the agent to touch a shared workspace, the reliable setup is connecting with an account that can already see it, then testing a read before promising a write.

Pairing is a two-step handshake: run hermes clawlink begin, approve the link in your browser, then run hermes clawlink finish. If you ran finish before approving, or the approval link expired, run hermes clawlink begin again to get a fresh link. Confirm the plugin was installed with --enable, then verify with hermes clawlink test.