An agent cannot connect or cannot see tools

The client reports 401

Check the token is sent as Authorization: Bearer mm_pat_..., whole. A personal access token has four parts - mm_pat_, the token id, an underscore, and the secret - and the secret itself can contain underscores, so splitting on _ and taking the last piece truncates it. Copy the value verbatim.

If the token was revoked or has expired, mint a new one. The stored value is a hash; there is no way to recover a token that was not copied when it was shown.

tools/list comes back short

That is the design, not a fault. Discovery is permission-aware: the list contains only tools the calling token can actually use. A missing tool almost always means a missing scope - check the scope reference for which one unlocks it, then mint a token that has it.

A tool is missing even though the scope is granted

Then the caller is an agent principal and the tool is protected. Roughly thirty tools are refused to agents whatever their scopes: creating workspaces or organizations, inviting or revoking members, registering agents, resolving decisions, and every hard delete. They are not published to an agent at all, so they are absent rather than erroring - being refused is the fallback, not being offered is the mechanism.

The tool reference marks each one.

The client connects but every call times out

The MCP endpoint is /api/mcp, not /mcp. Locally that is http://localhost:4591/api/mcp.