Overview
auth_status returns information about the current authentication state, including the authentication method, user identity, and granted scopes. This tool requires no parameters and no specific scope.
Primary Use Cases:
- Verify that authentication is configured correctly
- Debug permission issues when other tools return authorization errors
- Confirm which scopes are available before making tool calls
- No parameters required
- No scope required
- Returns complete authentication context
Parameters
This tool takes no parameters.Request Example
Response Format
Success Response
| Field | Type | Description |
|---|---|---|
authenticated | boolean | Always true when this tool returns successfully |
authMethod | string | Authentication method used: jwt or api_key |
userId | number | null | The authenticated user’s ID (set for user-scoped keys) |
workspaceGuid | string | null | The workspace GUID (set for workspace-scoped keys) |
clientId | string | The client application ID |
scopes | string[] | List of granted permission scopes |
Understanding Scopes
Thescopes array indicates which tools you have permission to use:
| Scope | Grants Access To |
|---|---|
mcp:notes:read | list_notes, search_notes, get_note, get_note_transcript, list_document_templates, get_document_template, get_share_link |
mcp:folders:read | search_private_folders, search_team_folders |
Usage Examples
Debugging Permission Errors
If a tool call returns a403 Forbidden error, use auth_status to check your scopes:
mcp:notes:read scope. Tools requiring a different scope (e.g., mcp:folders:read for folder search) would return 403 Forbidden.
Verifying API Key Kind
CheckuserId and workspaceGuid to determine which kind of API key you are using:
- User-scoped key:
userIdis set;workspaceGuidisnull. Can span multiple workspaces. - Workspace-scoped key:
workspaceGuidis set;userIdisnull. Tied to a single workspace, with no user identity.
Common Errors
Invalid or Expired Credentials
Solution: Verify your API key or JWT token is correct and has not expired. Generate a new key if needed.Best Practices
Call auth_status on Startup
Call auth_status on Startup
When initializing your MCP client, call
auth_status first to confirm connectivity and verify available scopes. This catches configuration issues early before making other tool calls.Use for Troubleshooting
Use for Troubleshooting
When a tool returns an unexpected authorization error,
auth_status is the fastest way to diagnose the issue. Check whether the required scope is in the scopes array.