MCP Access Tokens

Overview

Prizm issues two distinct token types for programmatic access: API access tokens for REST integrations, and MCP access tokens for MCP clients such as Claude, Cursor, and mcp-remote. The two types must not be used interchangeably. MCP access tokens have two authentication types. Choose one when you create the token:

	OAuth (recommended)	JWT
Best for	Claude custom connectors and Claude.ai	Claude Desktop with a local config file
How Claude authenticates	Sign-in through AuthKit. No long-lived secret is pasted into a config	A Prizm-issued token in the MCP config
What you create	An OAuth client with no client secret	A JWT with an expiry date
What you copy	The MCP URL and the OAuth Client ID	The full `mcpServers` JSON
Tool control	Tools you select on the client	Tools you select on the token

	API access token	MCP access token
UI / `generated_for`	`API`	`MCP`
JWT `token_type`	`api_access_token`	`mcp_authorization`
Purpose	REST APIs (Postman, integrations)	MCP clients (Claude Desktop, Cursor, mcp-remote)
Copied as	Plain JWT string	`mcpServers` JSON config (JWT embedded inside)
Tool scoping	N/A	Optional `tools` list in JWT claims
Auth header style	`Authorization: Bearer <jwt>`	MCP proxy uses `Authorization: Basic <jwt>`

Generating an MCP Access Token

Via the Prizm UI

Open Access Tokens

Navigate to Organization → Platform → Token and click the + icon in the Access Token toolbar. Use the ALL, API, and MCP chips to filter the list.

Access Token list with ALL, API and MCP filter chips and columns for key alias, generated for, token type, status, expiry, creator and creation time — Organization → Platform → Token lists your API and MCP access tokens

Configure the token

Set:

Key Alias — a descriptive name, for example claude-desktop-mcp
Generated For — select MCP (the dialog defaults to API)
Auth Type — select OAuth (recommended) or JWT
Expires On — JWT only. Choose an appropriate expiration date. OAuth clients don’t use an expiry date, because access is governed by OAuth sign-in and refresh
Purpose — a short description of what the token is for
Available Tools — select at least one MCP tool (required for MCP tokens)

Click Create OAuth Client for an OAuth client, or Create Token for a JWT.

Add Access Token dialog with Key Alias, Generated For, Expires On, Purpose, and Cancel and Create Token buttons — The Add Access Token dialog

Copy the token

After creating the token, use the copy action from the table. For an OAuth client, copy returns the MCP URL and the Client ID:

{
  "mcp_url": "https://<your-prizm-mcp-host>/mcp",
  "client_id": "<your-oauth-client-id>"
}

For a JWT, copy returns the full mcpServers JSON config, not a bare JWT.

Change a token’s tool access

The person who creates an MCP token decides which tools it can use. You can update the token’s tool access after it has been generated, so you no longer need to create a new token to widen or narrow its scope. Prizm enforces the updated scope on the next request (see Tool scope enforcement).

Via the API

Use a normal logged-in session or API bearer token for these calls — not the MCP token itself. Step 1 — List available MCP tools (for scoping)

GET {{baseUrl}}api/v1/ai_agent/mcp/tools
Authorization: Bearer <API_OR_SESSION_TOKEN>

Example response:

{
  "success": true,
  "message": "MCP tools retrieved successfully",
  "data": [
    { "name": "search_assets", "description": "...", "domain": "asset" },
    { "name": "create_metrics", "description": "...", "domain": "metrics" },
    { "name": "run_metric", "description": "...", "domain": "metrics" }
  ]
}

Use the name values when populating the token’s tools array. Step 2 — Create the MCP access token

POST {{baseUrl}}api/v1/auth/access_token/
Authorization: Bearer <API_OR_SESSION_TOKEN>
Content-Type: application/json

Request body:

{
  "key_alias": "claude-desktop-mcp",
  "generated_for": "MCP",
  "expired_at": "2027-01-01T00:00:00Z",
  "is_active": true,
  "purpose": "MCP client access",
  "tools": [
    "search_assets", "create_metrics", "run_metric",
    "get_lineage", "summary"
  ]
}

The response data.token contains the mcpServers config ready to paste into your client:

{
  "mcpServers": {
    "prizm-ai": {
      "command": "/bin/bash",
      "args": [
        "-c",
        "while true; do npx mcp-remote https://<saas-host>/mcp/ --header 'Authorization: Basic <MCP_JWT>'; sleep 10; done"
      ],
      "enabled": true,
      "autoConnect": true
    }
  }
}

Retrieve tokens later

# Get a single token
GET {{baseUrl}}api/v1/auth/access_token/{{accessTokenId}}
Authorization: Bearer <API_OR_SESSION_TOKEN>

# List all MCP tokens
POST {{baseUrl}}api/v1/auth/access_token/list
Authorization: Bearer <API_OR_SESSION_TOKEN>
Content-Type: application/json

{
  "pagination": { "page": 1, "pageSize": 10 },
  "filters": [{ "column": "generated_for", "operator": "equals", "value": "MCP" }]
}

Token Verification

This section applies to JWT tokens. OAuth clients don’t issue a long-lived token that you paste into a config. When generated_for = MCP, the copied value is not a bare JWT — it is the mcpServers config with the JWT embedded in the args string:

{
  "mcpServers": {
    "prizm-ai": {
      "command": "/bin/bash",
      "args": ["-c", "while true; do npx mcp-remote <url> --header 'Authorization: Basic <MCP_JWT>'; sleep 10; done"],
      "enabled": true,
      "autoConnect": true
    }
  }
}

Extract the JWT from the args string — it is the value that follows Authorization: Basic. Decode the JWT locally:

# macOS / Linux — decode payload (middle segment)
python3 - <<'PY'
import base64, json, sys
token = sys.argv[1]
payload = token.split(".")[1]
payload += "=" * (-len(payload) % 4)
print(json.dumps(json.loads(base64.urlsafe_b64decode(payload)), indent=2))
PY "<MCP_JWT>"

Or paste it into jwt.io (decode only — never share secrets in external tools).

Expected JWT claims

Claim	Expected value
`token_type`	`mcp_authorization`
`purpose`	`Model Context Protocol Authentication`
`organization_id`	Your org UUID
`organization_name`	Your org name
`tools`	List of allowed tool names (if scoped)
`user_id` / `email` / `username`	Present when created by a user
`exp` / `iat`	Expiry / issued timestamps

If token_type is api_access_token, this is an API token — it will not work as an MCP client credential.

Verification checklist

Before connecting a client, confirm:

generated_for is MCP
Copied payload contains mcpServers.prizm-ai
JWT token_type is mcp_authorization
JWT tools matches the tools you selected
JWT is not expired (exp is in the future)
Token row shows is_active = true in the Access Token list (the Status toggle is on) or in the API

Client Integration

Connect Claude with OAuth (recommended)

Use this for Claude custom connectors and Claude.ai. First create an OAuth client as described above, and copy the mcp_url and client_id. There is no client secret.

Add a custom connector in Claude

In Claude, add a custom MCP connector (a remote MCP server).

Enter the Prizm values

Set the server URL to the mcp_url value, which must end with /mcp. Set the OAuth Client ID to the client_id value. Leave the client secret empty.

Complete the browser sign-in when Claude prompts you (AuthKit).

Confirm the connection

Confirm the connector connects and that only the tools you selected appear.

Connect Claude Desktop with a JWT

Use this when you need the Claude Desktop mcpServers setup with mcp-remote.

Copy the mcpServers config

From Organization → Platform → Token, copy the MCP token. This returns the full mcpServers JSON.

Paste into your MCP client config

For Claude Desktop, open claude_desktop_config.json and paste the mcpServers block. The config already embeds the auth header and points mcp-remote at the Prizm MCP gateway.Prizm AI MCP server path: {{baseUrl}}api/v1/ai_agent/mcp/prizm-ai

Restart the client

Fully restart your MCP client and confirm that only the tools included in the token’s scope appear in the tools list.

Treat a JWT like a password. Anyone who has it can call the tools you allowed until it expires or is revoked.

Tool scope enforcement

The Prizm MCP server enforces tool scope at request time using MCPAuthenticationMiddleware:

The JWT is verified on every request
If the JWT has a tools claim, only those tools are callable or listed
Tokens without a tools claim are treated as unrestricted

Calling a tool outside the granted scope returns:

Tool '<tool_name>' is not permitted for this access token.

Available MCP Tools

Prizm AI MCP tools (user-facing, token-scoped)

These tools are exposed via Prizm AI MCP and are selectable when creating an MCP access token (GET /api/v1/ai_agent/mcp/tools). The live list may grow — always fetch from the API for the current set.

Tool	Domain
`search_assets`	asset
`list_assets_by_scope`	asset
`create_source`	source
`create_metrics`	metrics
`run_metric`	metrics
`metrics_collect`	metrics
`recommend_business_metrics`	metrics
`manage_metric_alert_mute`	metrics
`get_lineage`	lineage
`manage_schedule`	schedule
`change_schedule_state`	schedule
`search_governance`	governance
`create_domain`	governance
`create_glossary`	governance
`create_categories`	governance
`create_terms`	governance
`create_tags`	governance
`create_products`	governance
`recommend_terms`	governance
`recommend_governance_entities`	governance
`recommend_semantic_metric`	governance
`link_semantic_to_assets`	governance
`unlink_semantic_from_assets`	governance
`extract_term_rules`	governance
`create_dashboard`	chart
`summary`	common

Metrics MCP tools (service / internal)

A separate FastMCP server in prizm-metrics used by platform pipelines at {{baseUrl}}api/v1/metrics/mcp. These are write-oriented service tools and are not part of a user’s MCP access token scope.

Tool	Purpose
`create_metrics`	Bulk create metric run values
`create_alerts`	Bulk create/update alerts (upsert on asset + metric_detail + run)
`create_profiles`	Bulk create/update profiles

create_alerts — example payload

{
  "alerts": [
    {
      "asset_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "metric_detail_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "run_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "value": 12.5,
      "threshold": { "operator": ">", "value": 5 },
      "priority": "HIGH",
      "marked_as": "ACTIVE",
      "message": "Threshold breached"
    }
  ]
}

create_metrics — example payload

{
  "metrics": [
    {
      "name": "Null Percentage — customer_id",
      "metric_type": "CONDITIONAL",
      "metric_detail_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "value": 4.2
    }
  ]
}

create_profiles — example payload

{
  "profiles": [
    {
      "asset_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "level": "TABLE",
      "dimension": "Volume",
      "category": "Row Count",
      "subcategory": "Total",
      "profile_type": "NUMERIC",
      "profile_value": { "row_count": 125000 },
      "run_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    }
  ]
}

Quick Verification Flow

GET /api/v1/ai_agent/mcp/tools → pick the tool names you need
POST /api/v1/auth/access_token/ with generated_for: "MCP" and your selected tools
Copy data.token.mcpServers from the response
Decode the JWT — confirm token_type = mcp_authorization and tools matches
Paste mcpServers into your MCP client config and restart
Confirm only scoped tools appear in the client
Call an allowed tool → success
Call a disallowed tool → Tool '...' is not permitted for this access token.

Get Started

Core Concepts

Platform

Architecture

Data Sources

Integrations

Security & Access Control

Deployment

Help

Settings

MCP

Release Notes

Overview

Generating an MCP Access Token

Via the Prizm UI

Change a token’s tool access

Via the API

Token Verification

Expected JWT claims

Verification checklist

Client Integration

Connect Claude with OAuth (recommended)

Connect Claude Desktop with a JWT

Tool scope enforcement

Available MCP Tools

Prizm AI MCP tools (user-facing, token-scoped)

Metrics MCP tools (service / internal)

Quick Verification Flow

​Overview

​Generating an MCP Access Token

​Via the Prizm UI

​Change a token’s tool access

​Via the API

​Token Verification

​Expected JWT claims

​Verification checklist

​Client Integration

​Connect Claude with OAuth (recommended)

​Connect Claude Desktop with a JWT

​Tool scope enforcement

​Available MCP Tools

​Prizm AI MCP tools (user-facing, token-scoped)

​Metrics MCP tools (service / internal)

​Quick Verification Flow

Overview

Generating an MCP Access Token

Via the Prizm UI

Change a token’s tool access

Via the API

Token Verification

Expected JWT claims

Verification checklist

Client Integration

Connect Claude with OAuth (recommended)

Connect Claude Desktop with a JWT

Tool scope enforcement

Available MCP Tools

Prizm AI MCP tools (user-facing, token-scoped)

Metrics MCP tools (service / internal)

Quick Verification Flow