Authentication and Toolsets

The Lumar MCP server supports interactive users, shared read-only user credentials, and service accounts. Authentication identifies the principal; Lumar account roles and MCP toolsets then determine what the session can do.

Interactive OAuth

Interactive OAuth is the recommended option for a person using Claude, ChatGPT, Cursor, or another connector UI.

1. The MCP client registers with the server.
2. The browser opens the Lumar sign-in page.
3. The user signs in and selects the product toolsets to grant.
4. The client stores and refreshes the resulting OAuth token.

The server supports Dynamic Client Registration and Client ID Metadata Documents, so standards-compliant MCP clients do not need to be added to a static allowlist.

Access requires the MCP Server subscription addon on an active Lumar account. Removing the addon invalidates continued MCP access after the server's short authorization cache expires.

Static user keys

Shared-credential clients that cannot complete interactive login can send a Lumar user key as a bearer token:

Authorization: Bearer <userKeyId>:<secret>

User-key sessions are always read-only. The server restricts them to context, ai-visibility:read, and analyze:read even if the connection requests a write toolset. Revoking the user key removes access after the credential cache expires.

Service-account keys

Use a service account for CI, scheduled agents, and server-to-server workflows:

Authorization: Bearer lmr_sa_<serviceAccountId>_<secret>

If no Authorization header is present, the HTTP transport also accepts:

x-api-key: lmr_sa_<serviceAccountId>_<secret>

Each service account belongs to one Lumar account and has an assigned role. Unlike user-key sessions, it is not forced to read-only: the role is enforced on every operation, and the session can use the write toolsets selected by its connection.

lumar_get_me identifies this principal with me.isServiceAccount: true and returns its one scoped account. Account-level tools can therefore select that account automatically when accountId is omitted.

See Service Accounts to create service accounts, issue keys, assign the minimum required role, rotate credentials, and revoke keys.

User-bound operations

Some upstream operations require an interactive Lumar user and are not registered in service-account sessions:

• analyze_create_report_task
• analyze_generate_task_ticket_details
• analyze_create_task_external_link
• analyze_request_custom_metric_generation
• aivis_list_google_connections

Use an interactive user session or the Lumar dashboard for those steps. Other service-account operations still depend on the account role and selected toolsets.

caution

Service-account IP allowlists are evaluated against the hosted MCP server's egress address, not the machine running the MCP client. A key restricted to the client's own IP will generally fail through https://mcp.lumar.io/mcp.

Toolsets

Toolsets divide tools by product and trust boundary:

Toolset	Access
context	Identity, account discovery, product entitlements, and remaining account credits. Always enabled.
ai-visibility:read	Read AI Visibility configuration, scores, prompts, brands, citations, mentions, providers, and page runs.
ai-visibility:write	Manage AI Visibility projects/configuration and trigger supported prompt or page operations.
analyze:read	Read projects, crawls, reports, URL details, stored HTML, tasks, exports, SPR results, and custom metrics.
analyze:write	Manage segments/tasks, run crawls and exports, start SPR jobs, and manage custom-metric workflows.
analyze:external	Read or write the authenticated user's connected Jira tenant.
analyze:admin	Create, update, or clone Analyze projects and common project-wide crawl settings.

The context toolset remains available even when no optional product toolset is selected.

OAuth consent

For an OAuth connection, the consent screen is the source of truth. The server records leaf scopes such as toolset:analyze:read or toolset:analyze:admin in the access token and registers only the granted tools.

If Analyze read/write tools are visible but project create/update/clone tools are missing, reconnect and select Lumar Analyze -- Project admin.

Scoped URLs and headers

For service accounts, local development, or another pre-consent connection, select toolsets in the URL:

https://mcp.lumar.io/mcp/x/ai-visibility:read,analyze:read

Or send:

X-MCP-Toolsets: ai-visibility:read,analyze:read

Bare product selectors expand to all of that product's toolsets:

• ai-visibility expands to ai-visibility:read,ai-visibility:write.
• analyze expands to analyze:read,analyze:write,analyze:external,analyze:admin.

Omitting a selection enables all known toolsets, subject to the principal's Lumar role and entitlements. Prefer explicit leaf toolsets for least-privilege automation.

Authorization model

Effective access is the intersection of:

1. The authenticated user's or service account's Lumar account role.
2. Product entitlements on that account.
3. The MCP Server subscription addon.
4. The toolsets selected for the session.
5. Restrictions enforced by the MCP client or AI workspace.

Selecting a toolset does not elevate the underlying Lumar role. A Viewer with a write toolset still cannot perform an operation that requires Editor or Admin access.

Credential safety

• Prefer OAuth for interactive use.
• Store user and service-account keys in a secret manager or the client's secure secret facility.
• Use a separate service-account key for each integration.
• Assign the lowest sufficient role and the smallest toolset set.
• Rotate expiring keys and revoke unused keys.
• Never commit a credential in an MCP or plugin configuration file.