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 Desktop, Cursor, and mcp-remote. The two types must not be used interchangeably.

	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 Settings → Organization → Access Tokens and click Add token.

Configure the token

Set:

Key alias — a descriptive name, for example claude-desktop-mcp
Generated for — select MCP
Expiry — choose an appropriate expiration date
Tools — select at least one MCP tool (required for MCP tokens)

Copy the token

After creating the token, use the copy action from the table. For MCP tokens, copy returns the full mcpServers JSON config — not a bare JWT.

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

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 Tokens UI or API

Client Integration

Copy the mcpServers config

From Settings → Organization → Access Tokens, 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

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

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

API Reference

Overview

Generating an MCP Access Token

Via the Prizm UI

Via the API

Token Verification

Expected JWT claims

Verification checklist

Client Integration

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

​Via the API

​Token Verification

​Expected JWT claims

​Verification checklist

​Client Integration

​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

Via the API

Token Verification

Expected JWT claims

Verification checklist

Client Integration

Tool scope enforcement

Available MCP Tools

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

Metrics MCP tools (service / internal)

Quick Verification Flow