Getting started
MCP authentication: sign-in, access tokens and scopes
How OAuth sign-in and personal access tokens work with the OClever MCP server, what the read, write and spend scopes allow, and how to revoke access.
Two ways to connect
| OAuth sign-in | Personal access token | |
|---|---|---|
| Best for | Claude, ChatGPT, Cursor, VS Code and other chat apps | Claude Code, scripts, CI and clients without OAuth |
| How | Sign in from the assistant; choose workspaces and permissions on a consent screen | Create a token in the dashboard and paste it into the client's config |
| Looks like | Handled by the client | oc_pat_… |
| Lifetime | Access renews automatically; sign-in lasts up to 90 days of inactivity | 30, 90 or 365 days, or no expiry |
| Revoke | Dashboard → Settings → AI assistants → Connected apps | Dashboard → Settings → AI assistants → Access tokens |
Both act as you. An assistant never sees more than you can see in the dashboard, and if your account is restricted to certain workspaces, so is the assistant.
OAuth sign-in
When you add the server URL, your client discovers OClever's sign-in automatically and opens a browser window. You sign in with your OClever password or Google, then pick workspaces and permissions on the consent screen. The client never sees your password.
Behind the scenes this is OAuth 2.1 with PKCE. Clients can register themselves automatically (Client ID Metadata Documents or dynamic client registration), so there is no client ID to copy. Access tokens last one hour and are refreshed silently; refresh tokens rotate on every use and expire after 90 days without use.
Personal access tokens
- 1Open Settings → AI assistants in the OClever dashboard.
- 2Under Access tokens, select Create token. Give it a name you will recognise later (for example
Claude Code – laptop). - 3Choose the workspaces, permissions and expiry.
- 4Copy the token. It starts with
oc_pat_and is shown only once; OClever stores only a fingerprint of it.
Send it as a bearer token in the Authorization header:
HTTP headerAuthorization: Bearer oc_pat_your_token_here
Permissions (scopes)
| Scope | Allows | Plan |
|---|---|---|
read | Every report and lookup tool. Always included. | All paid plans |
write | Create prompts, change prompt status, add competitors, update recommendations. | Growth and above |
spend | Actions that cost coins: collection runs, article drafts, Prompt Lab, Agent Readiness. | Growth and above (Prompt Lab and Agent Readiness: Scale) |
Even with write or spend, every changing tool runs as a preview first and shows what would change and what it costs. Nothing happens until the assistant calls it again with preview: false, which most assistants only do after you confirm.
Workspaces
A connection can use one or more workspaces. If it can use only one, tools use it automatically. If it can use several, the assistant calls list_workspaces and passes a workspace_id; asking “in the Acme UK workspace…” is enough.
Agency client logins only ever see their own workspace and its coins.
Revoking access
- Open Settings → AI assistants.
- Access tokens: select Revoke next to the token. It stops working immediately.
- Connected apps: select Revoke next to the app. All of its tokens stop working immediately.
- Owners and admins can see and revoke every token in the organization.
- Removing a member from your organization revokes everything they connected.
The same page shows recent activity: which tool was called, by which connection, when, and how many coins it used.