Skip to main content
Connect a client covers setup, OAuth or an API key, per client. This page covers what a credential can do once connected.

​
Scopes and repository access

Every tool requires one of three access levels. The levels are hierarchical: admin includes write, and write includes read.
ScopeGrants
readView repositories, changes, commits, content, and diffs.
writeEverything in read, plus creating changes, writing files, and creating, moving, merging, and deleting bookmarks.
adminEverything in write, plus API key and webhook management.
The Access column in the Tool reference shows the scope each tool needs. How far a credential reaches depends on how you signed in:
  • OAuth tokens are granted to your user within an organization and carry full access to that organization.
  • API keys can additionally be scoped to specific repositories. Tool calls targeting any other repository are rejected. This is the way to give an agent least-privilege access. See Auth & Permissions for key management.

​
Errors

A missing or invalid credential returns 401 Unauthorized with a WWW-Authenticate header pointing back at the metadata, so a client can re-discover and re-authenticate: 
WWW-Authenticate: Bearer realm="mesa", resource_metadata="https://api.mesa.dev/.well-known/oauth-protected-resource/mcp"
Error responses carry a stable code and a trace id for support: 
{
  "error": { "code": "UNAUTHENTICATED", "message": "Bearer token required" },
  "trace_id": "..."
}