> ## Documentation Index
> Fetch the complete documentation index at: https://help.cryptolens.io/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP server

> Connect AI agents and MCP clients to your Devolens account to query usage analytics and manage licenses and customers.

Devolens hosts a remote MCP (Model Context Protocol) server at:

```text theme={null}
https://mcp.devolens.com/mcp
```

Connecting it to an MCP client such as Claude, ChatGPT, or Codex lets an AI agent work with your Devolens account directly: query the usage analytics behind the [KPI dashboards](/feature/web-ui/kpi-dashboards), look up and manage license keys, and manage customers. The agent can only use the permissions you grant.

The skills and `llms.txt` files described in [AI-assisted integration](/getting-started/build-with-ai) help an agent write your integration code. The MCP server is different: it lets an agent act on your live account.

## Available tools

| Tool group             | Examples                                                                           | What it allows                                                                        |
| ---------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| Usage analytics        | `ai_getDailyAggregates`, `ai_getKeyUsageSummaries`, `ai_getLicenseActivityBuckets` | Read the aggregated license activity and usage data that powers the KPI dashboards.   |
| Products and templates | `product_list`, `licenseTemplate_list`                                             | List products and license templates.                                                  |
| License keys           | `key_get`, `key_list`, `key_create`, `key_extend`, `key_block`                     | Read license keys and, if permitted, create, extend, block, or otherwise manage them. |
| Customers              | `customer_list`, `customer_licenses`, `customer_add`                               | Read customers and their licenses and, if permitted, add, edit, or remove customers.  |

Each tool maps to a Web API endpoint and requires the corresponding [access token](https://app.cryptolens.io/User/AccessToken#/) permission. A connection that was only granted analytics permissions cannot create or block keys.

## Enable MCP access

MCP access is disabled by default and is currently available for company accounts only.

1. Open [Security settings](https://app.cryptolens.io/Security#mcp-access) and enable MCP access.
2. Connected clients appear under [Connected Apps](https://app.cryptolens.io/Security/ConnectedApps), where you can review the permissions granted to each connection and revoke it at any time.

## Connect a client

<Tabs>
  <Tab title="Claude Code">
    ```bash theme={null}
    claude mcp add --transport http devolens https://mcp.devolens.com/mcp
    ```

    Run `/mcp` inside Claude Code to start the authorization flow.
  </Tab>

  <Tab title="Claude Desktop and claude.ai">
    Go to **Settings → Connectors → Add custom connector** and enter `https://mcp.devolens.com/mcp` as the URL.
  </Tab>

  <Tab title="ChatGPT">
    Custom MCP connectors require a paid ChatGPT plan and developer mode, which you can enable under **Settings → Apps & Connectors → Advanced settings**.

    1. Go to **Settings → Apps & Connectors → Create**.
    2. Name the connector (for example `Devolens`) and enter `https://mcp.devolens.com/mcp` as the MCP server URL.
    3. Select **OAuth** as the authentication method and complete the Devolens authorization flow.
    4. In a new chat, enable the connector from the tools menu to make it available to the model.

    Depending on your plan and ChatGPT version, token-based authentication may also be available when creating the connector. In that case, you can provide a Devolens [access token](https://app.cryptolens.io/User/AccessToken#/) instead of completing the OAuth flow, as described in the next section.
  </Tab>

  <Tab title="Codex">
    Add the server to `~/.codex/config.toml` (shared by the Codex CLI and IDE extension):

    ```toml theme={null}
    [mcp_servers.devolens]
    url = "https://mcp.devolens.com/mcp"
    ```

    Then authenticate with:

    ```bash theme={null}
    codex mcp login devolens
    ```

    To use an access token instead of OAuth, add the `token` header to the server entry:

    ```toml theme={null}
    [mcp_servers.devolens]
    url = "https://mcp.devolens.com/mcp"
    http_headers = { token = "<your access token>" }
    ```
  </Tab>

  <Tab title="VS Code (GitHub Copilot)">
    Add the server to `.vscode/mcp.json` in your workspace, or to your user-level MCP configuration:

    ```json theme={null}
    {
      "servers": {
        "devolens": {
          "type": "http",
          "url": "https://mcp.devolens.com/mcp"
        }
      }
    }
    ```

    VS Code starts the authorization flow when the server first connects. To use an access token instead, add a `headers` object with a `token` entry.
  </Tab>

  <Tab title="Cursor and other clients">
    Add the server to your client's MCP configuration, for example:

    ```json theme={null}
    {
      "mcpServers": {
        "devolens": {
          "url": "https://mcp.devolens.com/mcp"
        }
      }
    }
    ```
  </Tab>
</Tabs>

When the client connects for the first time, your browser opens a Devolens authorization page. Sign in and choose the exact permissions the client should have. These are the same permissions used by [access tokens](https://app.cryptolens.io/User/AccessToken#/), and presets are available for common setups such as read-only access, usage analytics, license operations, and customer management.

Completing the flow creates an access token named "Devolens MCP OAuth" scoped to exactly the permissions you selected. Revoking the connection under [Connected Apps](https://app.cryptolens.io/Security/ConnectedApps) removes the client's access.

## Authenticate with an access token

Instead of the browser-based authorization flow, you can authenticate by sending an existing access token in the `token` header. This is useful for headless environments, CI pipelines, and automations, or when you want to reuse a token whose permissions you have already narrowed down.

```json theme={null}
{
  "mcpServers": {
    "devolens": {
      "url": "https://mcp.devolens.com/mcp",
      "headers": {
        "token": "<your access token>"
      }
    }
  }
}
```

In Claude Code:

```bash theme={null}
claude mcp add --transport http devolens https://mcp.devolens.com/mcp --header "token: <your access token>"
```

You can create and manage access tokens [here](https://app.cryptolens.io/User/AccessToken#/). We recommend creating a dedicated token for each MCP client with only the permissions it needs.

## Security recommendations

* Grant the minimum permissions for the task. For reporting and dashboards, analytics permissions are enough; key and customer write permissions are only needed if the agent should change your account.
* Data returned by the tools is processed by the AI model you use, so only grant read access to data you are comfortable sharing with your AI provider.
* Narrowing permissions also reduces, and can eliminate, the personal data that reaches the model. A connection limited to analytics permissions returns aggregated usage data, whereas customer permissions expose names and email addresses, and key permissions can expose fields such as notes and machine codes. This supports a data-minimization approach under GDPR and similar regulations.
* When you authenticate with an access token, you can additionally use [feature lock for data masking](/security/safeguarding-measures#using-feature-lock-for-data-masking) to hide individual fields, such as notes, from license key responses.
* Review [Connected Apps](https://app.cryptolens.io/Security/ConnectedApps) periodically and revoke connections you no longer use.
* Every tool call is executed as a regular Web API request, so MCP activity is recorded in the Web API log and can be audited like any other API usage.

## Example prompts

| Goal                  | Prompt                                                                                                                                                                                                                                                                                                                     |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Review activity       | `Show daily license activations for product <product id> over the last 30 days.`                                                                                                                                                                                                                                           |
| Find heavy usage      | `Which license keys had the most activity last week?`                                                                                                                                                                                                                                                                      |
| Customer lookup       | `Find the customer <name> and list their licenses.`                                                                                                                                                                                                                                                                        |
| Issue a trial         | `Create a 30-day trial key for product <product id>.`                                                                                                                                                                                                                                                                      |
| Support and debugging | `The customer <name> reports that their license fails to activate. Look up their license and recent activity and explain the likely cause.`                                                                                                                                                                                |
| Find anomalies        | `Which products have unusual activation patterns?`                                                                                                                                                                                                                                                                         |
| Business related      | `Which customers may be under-licensed?`<br />`Show me customers that might be at risk of churning due to inactivity.`<br />`Which trial users show the strongest conversion signals?`<br />`Are there signs that customers are sharing licenses internally?`<br />`Which customers appear ready for usage-based pricing?` |