Skip to main content
The Userplane MCP server uses OAuth 2.1 for authentication. AI clients handle the OAuth flow automatically when you first connect. No API keys or manual token management required.

​
How it works

The MCP server implements the following standards: The server uses a single OAuth scope: mcp:tools.

​
What happens when you connect

1

Add the server URL

You add https://api.userplane.io/mcp to your AI client’s MCP settings.
2

First tool call triggers OAuth

When you ask your agent to do something that requires Userplane data, the client initiates the OAuth flow.
3

Sign in via browser

A browser window opens. Sign in with your Userplane credentials.
4

Approve access

The consent screen shows the requesting client and the mcp:tools scope. Click Allow.

OAuth consent screen

5

Connection established

The client receives an access token and can make authenticated tool calls. Tokens refresh automatically — you won’t need to sign in again unless you revoke access.

​
Permissions

MCP tools respect the same workspace roles as the Userplane dashboard and REST API.
Your workspace role determines what operations are available through the MCP server. If you receive a permission error, check your role in Workspace Settings > Team.

​
Security

  • Per-client registration — each AI client (Claude, Codex, Cursor, VS Code, ChatGPT) registers as a separate OAuth client. Revoking one client’s access does not affect others.
  • Token scoping — access tokens are scoped to mcp:tools and carry no broader permissions.
  • JWT verification — every request is verified against Userplane’s JWKS endpoint with issuer and audience checks.
  • No shared secrets — no API keys or client secrets are shared with the AI client. All clients use PKCE (public client flow).

​
Managing connections

Each authorized MCP client appears in your account’s Connected Apps list. From there you can review permissions, check authorization dates, and revoke access. To revoke a specific client’s access:
  1. Go to Account Settings > Connections.
  2. Locate the client and open the actions menu (three dots).
  3. Select Revoke Access, type the application name to confirm, and click Revoke.
The client loses access immediately. Other connected clients are not affected.
For the full walkthrough including screenshots, see Connected Apps.
The Userplane REST API uses uspl_ API keys for authentication (see API Authentication). The MCP server uses OAuth 2.1 instead — the two authentication methods provide access to the same underlying resources through different interfaces.