# Native and Compact Tool Surfaces

https://api-docs.lumar.io/docs/lumar-mcp/tool-surfaces

# Native and Compact Tool Surfaces

The Lumar MCP server offers two ways to present the same authorized capabilities. **Native V1** remains the default. **Compact V2** is an opt-in beta that keeps the initial tool list small and discovers operations only when they are needed.

| Surface        | Tools advertised to the MCP client                                                                                 | Best for                                                                |
| -------------- | ------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------- |
| **Native V1**  | Every operation granted by the selected toolsets, such as `analyze_list_projects` or `aivis_get_visibility_scores` | Existing integrations that call Lumar operations directly               |
| **Compact V2** | `lumar_find`, `lumar_read`, and `lumar_act`                                                                        | General-purpose agents that benefit from a smaller initial tool context |

The surface changes presentation, not authorization. Lumar account roles, product entitlements, and the selected [toolsets](./authentication-and-toolsets.md#toolsets) continue to decide which operations and workflow skills are available.

## How Compact V2 works

Compact V2 exposes three tools:

- `lumar_find` searches the operations and bundled workflow skills available to the current connection. Search by capability, workflow, entity, or exact operation ID. Results can include names, summaries, or an operation's current input schema.
- `lumar_read` runs one authorized read-only operation by its stable operation ID. It rejects non-read operations.
- `lumar_act` runs one authorized non-read operation by its stable operation ID. It is marked as destructive so the MCP client can preserve its normal confirmation flow for actions that create, update, delete, trigger jobs, or write to connected services.

A typical Compact V2 flow is:

1. Search with `lumar_find`. Use `detail: "schema"` before invoking an unfamiliar operation.
2. Copy the exact operation ID and arguments from the result.
3. Run the operation through the `invokeWith` tool returned by discovery, either `lumar_read` or `lumar_act`.

For example, an agent looking for a crawl summary can search for `crawl summary`, receive the stable `analyze_get_crawl_summary` operation ID and its argument schema, then pass that ID and those arguments to `lumar_read`.

Discovery returns at most eight matches and can be narrowed with:

- `kind`: `all`, `operation`, or `workflow`
- `product`: `context`, `ai-visibility`, `analyze`, or `monitor`
- `mode`: `read` or `act`
- `detail`: `names`, `summary`, or `schema`

Compact V2 does not expose raw GraphQL or arbitrary code execution. It validates arguments against the original operation schema and calls the same implementation used by Native V1. Account selection, pagination, input-required responses, errors, and per-operation telemetry therefore behave the same on both surfaces.

## Bundled workflow skills

The MCP server bundles workflow skills for common Analyze and AI Visibility tasks. A compatible client can discover them through the MCP skills methods and read their `skill://lumar/.../SKILL.md` resources.

Both surfaces use the same workflow corpus and apply the same toolset and user/service-account eligibility rules. Native V1 skills refer directly to the advertised operation tools. Compact V2 serves an adapted copy that explains how to discover each stable operation ID and run it through `lumar_read` or `lumar_act`. In Compact V2, an agent can also search the skill catalogue with `lumar_find` using `kind: "workflow"`.

The optional [Lumar analytics plugin](./plugins.md) is separate from these server-bundled skills. It configures the MCP connection and installs the same style of guided workflows into supported agent hosts, including hosts that do not yet consume MCP-served skills directly.

## Choose a surface

### Interactive OAuth

The Lumar consent screen shows both surfaces when you connect:

- **Native V1** is selected by default.
- **Compact V2** is labelled beta and must be selected explicitly.

The selection is stored in the access token as `mcp:surface:v1` or `mcp:surface:v2`. Tokens issued before surface selection was introduced continue to use Native V1. Silent reauthorization preserves the existing choice, so reconnect and complete interactive consent to switch an existing connection.

### Service accounts, user keys, and stdio

Connections that do not use interactive OAuth default to Native V1. Select Compact V2 with either:

```text
X-MCP-Surface: compact
```

or, for stdio:

```text
LUMAR_MCP_SURFACE=compact
```

`v2` is accepted as an alias for `compact`; `v1` is accepted as an alias for `native`. An OAuth token's surface scope takes precedence over a header or environment variable.

## Switch or troubleshoot a connection

MCP clients often cache the advertised tool list. After changing surfaces, reconnect or restart the client so it refreshes discovery. Seeing exactly three Lumar tools is expected on Compact V2; use `lumar_find` to discover the underlying operations.

If an expected operation or workflow does not appear in search, check the connection's selected toolsets and the authenticated principal's Lumar role. Compact V2 does not bypass a missing grant.