Connect an MCP host

LeapView exposes the same governed BI tool catalog used by its built-in agent through a tools-only MCP endpoint. The endpoint belongs to each LeapView deployment:

${LEAPVIEW_PUBLIC_URL}/mcp

For example, a deployment whose public URL is https://bi.example.com exposes MCP at https://bi.example.com/mcp. https://leapview.dev hosts the LeapView website and documentation; it is not a shared MCP gateway for independently deployed instances.

LeapView implements stateless Streamable HTTP 2025-11-25. It exposes tools, not MCP resources, prompts, nested conversations, or stdio transport. The built-in agent and MCP use the same catalog, input and output schemas, handlers, authorization, projections, audit path, and execution errors.

Before you connect

Configure the deployment's exact externally reachable HTTPS origin:

LEAPVIEW_PUBLIC_URL=https://bi.example.com
LEAPVIEW_ALLOWED_HOSTS=bi.example.com

The origin must have no path, query, fragment, or credentials. Reverse proxies must preserve the public scheme and host. The resulting OAuth resource and audience are exactly https://bi.example.com/mcp; changing the public URL creates a different resource identity.

An interactive user needs browser authentication and permission to use the agent. Grant USE_AGENT through at least one workspace the principal may access. Each tool call then checks the referenced workspace and the tool's resource privileges and data policies. A workspace is not encoded in the MCP connection URL: query tools accept an explicit workspace, while catalog tools carry workspace identity in returned refs.

The MCP endpoint is independent of LEAPVIEW_AGENT_MODEL and LEAPVIEW_AGENT_API_KEY. External MCP hosts can use LeapView when the built-in model is disabled.

Connect Claude

Claude connects to LeapView as a remote custom connector:

1. In Claude, open Customize, then Connectors.
2. Choose Add custom connector.
3. Name the connector, for example LeapView.
4. Enter your deployment URL followed by /mcp, for example https://bi.example.com/mcp.
5. Leave advanced OAuth client ID and client secret fields empty. LeapView supports automatic client registration and Client ID Metadata Documents.
6. Connect the new connector. Claude opens the LeapView sign-in and consent flow in the browser.
7. Review and approve the mcp:use request, then enable the connector in the conversation where it should be available.

Organization owners may need to add the custom connector before members can connect it. Claude's UI and plan availability can change; use Anthropic's current remote MCP custom connector guide when its labels differ from the steps above.

Other remote MCP clients use the same URL and OAuth discovery flow. The client must support Streamable HTTP and OAuth for protected MCP resources.

Confirm the tool catalog

After connecting, the host's tools/list response contains exactly eight tools:

catalog_search
catalog_list
catalog_get
query_semantic_model
query_dashboard_visual
query_visual
docs_search
docs_read

The same names, input schemas, output schemas, read-only annotations, and handlers are used by built-in chat. There are no model-visible compatibility aliases for the superseded tool catalog. Rediscover tools after upgrading LeapView.

Use catalog_search when the workspace or parent is unknown, catalog_list to browse a known parent, and catalog_get before querying when an exact definition is needed. Follow Use the agent tool catalog for refs, hierarchy, locations, pagination, errors, and query-tool selection. The generated Agent tool reference publishes the same schemas and annotations as tools/list.

Understand the sign-in flow

An unauthenticated MCP request receives an OAuth challenge pointing to protected-resource metadata. For the example deployment, clients discover:

https://bi.example.com/.well-known/oauth-protected-resource/mcp
https://bi.example.com/.well-known/oauth-authorization-server

You can verify that discovery is publicly reachable before configuring a client:

curl -fsS https://bi.example.com/.well-known/oauth-protected-resource/mcp
curl -fsS https://bi.example.com/.well-known/oauth-authorization-server

LeapView's embedded authorization server supports authorization code with S256 PKCE, Dynamic Client Registration, Client ID Metadata Documents, refresh-token rotation, and explicit resource indicators. Browser sessions authenticate the consent page but are not accepted as MCP credentials. The issued OAuth access token is a bearer token on the wire, lasts 15 minutes, and has an exact MCP audience. Refresh tokens last 30 days and rotate when used.

General LeapView API tokens are intentionally rejected at /mcp. They have different audience and delegation semantics and should continue to be used for the REST API and CLI.

Connect an automated workload

Use a dedicated LeapView service principal for a non-interactive MCP client. Grant it USE_AGENT and only the workspace and resource privileges its tools require. Exchange the service-principal ID and secret at the deployment's OAuth token endpoint:

curl -fsS https://bi.example.com/oauth/token \
  -u "$MCP_CLIENT_ID:$MCP_CLIENT_SECRET" \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode grant_type=client_credentials \
  --data-urlencode scope=mcp:use \
  --data-urlencode resource=https://bi.example.com/mcp

Pass the returned access token to the MCP transport as Authorization: Bearer <access-token>. The service-principal secret is presented only to the token endpoint; it is not itself an MCP access token. Rotate and revoke it through the existing service-principal lifecycle.

Use an external authorization server

Set LEAPVIEW_MCP_OAUTH_ISSUER_URL to delegate MCP authorization to an organization-wide issuer. The issuer must publish OpenID Connect discovery and sign JWT access tokens with:

• an audience exactly equal to ${LEAPVIEW_PUBLIC_URL}/mcp;
• a subject that LeapView can map to an existing principal;
• an mcp:use scope.

LeapView still performs live RBAC and data-policy checks for every tool call. In external-issuer mode, clients use the external provider's advertised authorization endpoints and LeapView's embedded authorization endpoints are unavailable. Ensure the provider and client together support the interactive remote-MCP flow you intend to use.

Troubleshoot connections

Successful calls return both MCP structuredContent and equivalent JSON text. Expected tool failures are returned as tool errors; malformed MCP requests use protocol errors. Request cancellation propagates into query execution, and every call is recorded through the agent-tool audit path.

Review Agent integrations, Service principals and API tokens, Audit events, and Production configuration before enabling production clients. Use the generated environment variable reference and Access API reference for exact runtime and principal-management contracts.