OAuth 2.1

Understand Lenses OAuth

Lenses supports OAuth 2.1. To configure it see here. User then flow the OAuth flow to login.

MCP Server Integration

Lenses MCP Server can be configured to use OAuth 2.1 for authenticating AI tool requests. This provides secure, enterprise-grade access to Lenses capabilities through Claude, Cursor and other AI applications.

Why OAuth for MCP

OAuth 2.1 is the recommended authentication method for the MCP Server because it:

• Eliminates static keys — No API keys shared with AI tools or stored in configurations

• Provides scope-based access — Grant only the permissions needed (read, write, delete)

• Enables token introspection — Every request is validated against the authorization server

• Supports modern security standards — PKCE (S256), RFC 7662 token introspection, RFC 8414 discovery

How It Works

When you connect your AI tool to an OAuth-configured MCP Server:

1. Discovery — Your AI tool queries the MCP Server's OAuth metadata endpoint

2. Registration — Your AI tool registers itself with Lenses HQ (automatic)

3. Authorization — You authenticate with your Lenses credentials and grant scopes

4. Token Grant — Lenses HQ issues an access token to your AI tool

5. Requests — Your AI tool calls the MCP Server using the token

6. Validation — The MCP Server validates the token with Lenses HQ before processing requests

Configuration

To enable OAuth for the MCP Server, ensure your Lenses HQ configuration includes:

oauth2:
  authorizationServer:
    unauthenticatedIntrospection: true

This allows the MCP Server to validate tokens without client credentials, following OAuth 2.1 best practices.

Setup

To run the MCP Server with OAuth:

Environment Variables:

When OAUTH_ENABLED is set, the MCP Server enables OAuth mode and requires two parameters.

OAUTH_ENABLED=true
LENSES_URL=https://lenses.example.com
MCP_ADVERTISED_URL=http://localhost:8000

Docker Example:

docker run -p 8000:8000 \
  -e OAUTH_ENABLED=true \
  -e LENSES_URL=https://lenses.example.com \
  -e MCP_ADVERTISED_URL=http://localhost:8000 \
  -e TRANSPORT=http \
  lensesio/mcp

Scopes

The MCP Server advertises three OAuth scopes:

Scope	Description
read	Read-only access to topics, environments, connectors, and metadata
write	Create and update connectors, topics, and other resources
delete	Delete connectors, topics, and other resources

When you authenticate, you'll be prompted to grant these scopes. Your token will only grant the scopes you select.

API Key Fallback (Legacy)

For backward compatibility and local testing, the MCP Server also supports static API keys. However, OAuth 2.1 is strongly recommended for production use because it provides superior security and scope-based access control.

If not using OAuth, set the LENSES_API_KEY environment variable instead:

docker run -p 8000:8000 \
  -e LENSES_API_KEY=<YOUR_API_KEY> \
  -e LENSES_URL=https://lenses.example.com \
  lensesio/mcp

Troubleshooting

Token Validation Failures Ensure that:

• Lenses HQ has unauthenticatedIntrospection: true configured

• The MCP_ADVERTISED_URL is correctly set and reachable

• Your OAuth token hasn't expired (tokens are typically valid for 1 hour)

Scope Issues If operations fail with "insufficient scopes," re-authenticate and grant the required scopes during the OAuth flow.

---

VS Code Extension

---

Connected Applications

In Lenses you can view connected applications, navigate to the settings, bottom left, then your account and the OAuth section.

Here you can view the details such as the application name, authorization scopes granted, registration method (such as Dynamic Client Registration) and the client ID as well as a way to delete/revoke them.