# OAuth 2.1

Lenses supports OAuth 2.1. To configure it see [here](/latest/deployment/configuration/hq.md#authconfig). 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:

```yaml
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.

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

#### **Docker Example:**

```bash
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.

<figure><img src="/files/zQJN4cvt2XrXbpMse9NQ" alt=""><figcaption></figcaption></figure>

### 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:

```bash
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

<figure><img src="/files/UoIUZwXiXGZMBjkNf0jz" alt=""><figcaption></figcaption></figure>

***

## Connected Applications

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

{% columns %}
{% column %}

<figure><img src="/files/aqmls9VbXiLCO61LbRkW" alt=""><figcaption></figcaption></figure>

{% endcolumn %}

{% column %}

<figure><img src="/files/ogdLJHpxGjlCrnh8XLmp" alt=""><figcaption></figcaption></figure>

{% endcolumn %}
{% endcolumns %}

Here you can view the details such as the application name, authorization scopes granted, registration method (such as [Dynamic Client Registration](https://datatracker.ietf.org/doc/html/rfc7591)) and the client ID as well as a way to delete/revoke them.

<figure><img src="/files/uVC7IFRy7lwMdnnxLP11" alt=""><figcaption></figcaption></figure>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.lenses.io/latest/user-guide/using/security/oauth-2.1.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.