Agent integrations

LeapView conversations are global and owned by the authenticated principal. Project resources are governed catalog assets: a resource-aware tool uses an exact {kind,id} reference, then enforces the principal's privileges, any REST credential restrictions, data policies, and the governed query layer.

Curated tool catalog

Built-in chat, MCP discovery, and leapview agent tools expose one governed catalog. Its discovery, query, and documentation subset remains read-only; the dashboard-authoring subset adds the twelve bounded authoring tools documented in Dashboard authoring and promotion.

Main chat can create and edit private dashboard drafts when explicitly requested. Each tool still checks the authenticated user's dashboard and semantic-model permissions, records server-bound provenance, and uses exact revisions for edits. Inside Builder, the agent targets only the open draft and selected page. Embedded dashboard and Data Explorer chat remain read-only. These chat surfaces do not expose publishing, archiving, forking, deleting, or visibility changes. A successfully validated generated dashboard opens beside the same conversation.

  • catalog_search searches authorized resources in the server-bound Project when a resource's location is unknown, including visible semantic metric and dimension names and labels.
  • catalog_list browses the server-bound Project graph. Omit parent to list authorized resources across the active graph, pass an authorized active Project ref to list the same root, or pass a returned {kind,id} resource ref to browse its dependencies.
  • catalog_get returns the compact definition for one exact ref. Shared visuals and filters may require one of the returned dashboard/page locations.
  • query_semantic_model executes governed semantic queries.
  • query_dashboard_visual queries one existing dashboard visual.
  • query_visual creates a read-only visualization from governed semantic fields.
  • docs_search and docs_read search and read the version-matched product documentation.

Catalog search and list silently omit inaccessible resources. Exact lookup returns the same not-found result for missing and inaccessible refs. These discovery/query/documentation tools are read-only, idempotent, non-destructive, and closed-world. Dashboard authoring is the explicit exception: its twelve tools can create private drafts and apply the four bounded intents or lifecycle commands, while still enforcing project-resource grants, governed fields, exact revisions, and no access to connections, raw sources, lineage, refresh runs, raw SQL, credentials, semantic-model mutation, or data mutation.

See Use the agent tool catalog for refs, hierarchy, pagination, shared-resource locations, tool-selection guidance, and stable error behavior. Use the generated Agent tool reference for exact schemas and metadata.

Keep a chat visual

Open a visual card in chat to inspect its chart. Save keeps it as a saved exploration.

For a visual created by the agent, choose Add to dashboard to select an editable dashboard and page or create a new private dashboard. The picker shows compatible dashboards that you can edit or copy. Published dashboards use Create copy and add, which creates a private editable copy containing the visual. The visual retains its semantic query and filters.

After adding the visual, choose Open dashboard to inspect it in the editor, or Add another visual to return to chat. The next dashboard picker remembers the dashboard and page you selected.

Product documentation tools

The built-in agent and deployment MCP catalog expose docs_search and docs_read. Documentation search returns ranked, bounded matches from the immutable documentation index embedded in the running LeapView release. Each page reports count and hasMore; continue with its opaque, snapshot-bound nextCursor when needed. Each match includes a stable doc: ID, documentation path, public URL, summary, and focused excerpt.

Pass a returned ID to docs_read. Reads are line- and byte-bounded and return nextOffset when more content remains. Continue from that offset only when the current window is insufficient. The tools can read authored guides and generated CLI, API, configuration, and visual references, but cannot access arbitrary deployment files or execute documented operations.

Configure the built-in model provider

LeapView platform admins manage the instance-wide chatbot in Agent Settings. Project admins and chatbot users cannot change its provider or model.

  1. Choose a provider preset or enter a compatible endpoint, then enter the model identifier.
  2. Select the supported API mode and optional reasoning effort. Unset reasoning uses the provider default; none explicitly disables reasoning where supported.
  3. Enter a provider API key, or leave the key field blank to retain the saved credential. Changing the endpoint requires explicitly entering a credential for that endpoint.
  4. Select Test connection. LeapView sends a small synthetic tool round-trip, never project data. This makes provider API calls and may incur a small charge.
  5. Select Save and activate within five minutes. Changing any field requires another test. Failed tests leave the active configuration unchanged.

The configuration applies to new requests without restarting LeapView. Active requests retain their original configuration. Administrator revisions survive restart, including an explicitly disabled agent. Queued admin-managed runs retain their configuration revision across restart. Legacy queued runs cannot silently resume with a newly selected administrator provider.

Test previous configuration tests the preceding revision; Restore tested revision activates it as a new revision. Provider keys must still be valid for restoration. Ordinary message and tool history remains usable after a provider change; opaque provider reasoning state is only replayed to its original model, endpoint, and credential.

Deployment prerequisite: credential encryption

Administrator-managed agent settings use the shared customer credential store. Configure a private credential-keyring-v1 file through LEAPVIEW_CREDENTIAL_KEYRING_FILE, bound to the initialized instance identity, and declare the customer owner with admin credentials setup --owner while the application is stopped. Keep an independent encrypted recovery copy of that keyring and retain keys needed by supported database backups.

Test connection saves an encrypted immutable version and validates that exact version against the proposed provider configuration. Save and activate drains credential-backed work, commits the configuration reference and audit together, then installs the committed runtime before admitting new work. A failed response can mean activation is pending; reload settings before retrying. Testing the same pending change refreshes its validation without replacing its version. Cancel pending change can abandon an uncommitted change; a committed change must be recovered, or replaced through another validated configuration.

Configuration history contains exact version references. Saved keys never appear in configuration reads, browser signals, or audit payloads. Historical references retain their original destination and credential when a run resumes or an administrator tests an earlier configuration.

The old LEAPVIEW_AGENT_CREDENTIAL_KEY value is unused. Legacy encrypted agent revisions are rejected with explicit setup guidance; they are never silently imported, overwritten, or erased. Retain the old deployment and its recovery material before moving across this incompatible credential format. Explicitly re-enter provider credentials using the new setup; ordinary image rollback is not a credential-format migration procedure.

Existing deployment-managed configuration

Until an administrator saves a configuration, existing LEAPVIEW_AGENT_API_KEY, LEAPVIEW_AGENT_BASE_URL, LEAPVIEW_AGENT_MODEL, and optional LEAPVIEW_AGENT_REASONING_EFFORT remain startup configuration. Both key and model are required to enable the legacy agent. Shared templates do not select a model or reasoning effort. Luna support remains available when explicitly selected.

Existing deployments may still use LEAPVIEW_AGENT_CONFIG_FILE, a protected JSON file containing enabled, apiKey, model, baseUrl, and optional reasoningEffort. Valid revisions apply to new requests; invalid revisions retain the last known-good configuration. Environment changes require a restart.

The first successful admin save transfers configuration ownership to LeapView. Afterward, environment settings and file reloads cannot override that decision, even if the admin disables the agent. The administration page identifies the configuration source. Do not delete database revisions to switch ownership back.

Supported provider behavior

The Responses integration supports explicit model identifiers and reasoning settings. Chat Completions supports compatible tool-calling providers; explicit reasoning effort is rejected unless the adapter implements it. DeepSeek V4 currently requires non-thinking mode (none); full thinking support is not implemented. Native Claude support is not implied by the custom endpoint field. Connection testing checks the actual selected model and protocol.

The MCP endpoint is independent of this chatbot provider configuration. External MCP hosts can use LeapView tools while the built-in chatbot is disabled.

Ask through the CLI

leapview agent ask \
  --target "$LEAPVIEW_TARGET" \
  --token "$LEAPVIEW_API_TOKEN" \
  "Which categories contributed most to revenue in the sales project?"

Use --conversation <id> to continue an existing principal-owned conversation and --format json for machine processing. List conversations with bounded pagination through leapview agent conversations. The CLI follows the asynchronous run to a terminal state.

Integrate through REST

The generated Agent API is rooted at /api/v1/agent and exposes global conversation creation, update, archive, messages, runs, and run events. The removed /api/v1/workspaces/{workspace}/agent routes have no compatibility aliases.

A typical client creates or selects a conversation, starts a run, records its identity, follows the run/event surface to a documented terminal state, renders the assistant message and tool evidence, and archives conversations according to retention policy. List endpoints use opaque pagination tokens.

Integrate through MCP

Set LEAPVIEW_PUBLIC_URL to the deployment's canonical HTTPS origin, then give an MCP host such as Claude the deployment-specific URL ${LEAPVIEW_PUBLIC_URL}/mcp. The host discovers authorization automatically and opens LeapView's sign-in and consent flow. LeapView implements Streamable HTTP 2025-11-25 with stateless JSON responses and exposes tools only—no resources, prompts, nested conversation tools, or stdio transport.

MCP and built-in chat consume the same catalog, schemas, handlers, authorization, projections, audit path, and execution errors. Successful tool calls return both structuredContent and equivalent JSON text. MCP access requires the OAuth mcp:use scope; catalog operations additionally require RESOURCE_READ, while data tools require RESOURCE_USE. Rediscover tools after a LeapView upgrade instead of caching schemas across releases.

For dashboard authoring, actor and provenance are server-bound. Tool inputs do not accept an actor, conversation, or tool-call identity: the server records the authenticated principal as actorId, the active conversation as conversationId, the invocation identity as toolCallId, and origin: agent. See the exact tool names and create/fork/promotion flow in Dashboard authoring and promotion.

By default, LeapView is the MCP authorization server. It supports authorization code with S256 PKCE, refresh-token rotation, OAuth protected-resource and authorization-server discovery, Client ID Metadata Documents, and Dynamic Client Registration. The user approves the coarse mcp:use scope; live LeapView RBAC and data policies remain authoritative for every tool call. Access tokens last 15 minutes and refresh tokens last 30 days.

General LeapView API tokens and browser-session cookies are intentionally rejected at /mcp. A development bearer token remains available only with the local development bypass. Automated MCP clients use an existing LeapView service-principal ID and secret with the OAuth client_credentials grant, the mcp:use scope, and an exact resource of ${LEAPVIEW_PUBLIC_URL}/mcp.

To delegate MCP authorization to an organization-wide provider, set LEAPVIEW_MCP_OAUTH_ISSUER_URL. The issuer must publish OpenID Connect discovery and sign JWT access tokens whose audience is exactly ${LEAPVIEW_PUBLIC_URL}/mcp, whose subject identifies the user, and whose scope contains mcp:use. LeapView maps the external subject/email to a principal, then applies the same live authorization checks. In this mode clients use the external provider's advertised authorization endpoints; LeapView's embedded authorization endpoints are unavailable.

Cross-origin MCP requests are rejected. OAuth tokens are bearer credentials on the wire, so deploy only behind HTTPS and never place them in URLs or logs. Follow Connect an MCP host for deployment configuration, Claude setup, OAuth discovery, service-principal automation, and troubleshooting.

Validate answers and operate safely

Natural-language output is not a replacement for governed results. Present tool evidence, resource identity, filters, and relevant time or deployment context so a user can validate claims. Use deterministic semantic or dashboard queries for automated decisions that cannot tolerate interpretive variation.

Test empty results, authorization failures, project-scoped credentials, ambiguous questions, provider timeouts, cancelled runs, and active deployment changes. Audit conversation and tool activity, apply bounded retention with leapview admin maintenance, and never log provider API keys or raw sensitive prompts into general diagnostics.

See Service principals and API tokens and the generated agent CLI reference.