MCP surface and scopes¶

When an MCP client connects to MEHO, it does not see one tool per vendor operation. It sees a small, stable set of meta-tools that works the same way for every connector and every product version. That set is deliberately tiered by trust: a default agent session gets a narrow working surface, the operator planes are hidden until a session explicitly asks for them, and a few human-decision verbs have no MCP path at all.

This page explains the three tiers, how a client opts into the operator planes, and why an agent can never approve its own work. It is the same model whichever client you wired in Connect clients.

The default working surface (26 tools)¶

Every session lists the 26-tool working surface with no elevation — enough to discover connectors, run governed operations, page large results, and coordinate with other operators. The tools group into ten families:

Family	Tools
Health	`meho_status`
Connectors	`meho_connector_list`
Operation discovery	`list_operation_groups`, `search_operations`
Execution	`call_operation`, `preview_operation`
Result handles	`result_query`
Knowledge	`search_knowledge`, `add_to_knowledge` (plus the capability-gated docs add-on: `ask_docs`, `search_docs`, `read_docs`, `list_doc_collections`)
Memory	`search_memory`, `add_to_memory`
Broadcast	`meho_broadcast_recent`, `meho_broadcast_announce`, `meho_broadcast_watch`
Targets and topology	`list_targets`, `query_topology`
Runbooks (run family)	`meho_runbook_start`, `meho_runbook_next`, `meho_runbook_abort`, `meho_runbook_list_runs`, `meho_runbook_list_templates`, `meho_runbook_show_template`

Four of the 26 — the grounded-documentation add-on tools ask_docs, search_docs, read_docs, and list_doc_collections — appear only when the tenant has provisioned the meho-docs capability. A session without that capability lists the other 22.

The working surface is the same across every connector. An agent picks a connector, lists its operation groups, searches for the operation it needs, previews it, and calls it — the vendor's own identifiers stay in the operation id, never in a tool name.

The discovery-and-execution ladder¶

A useful session almost always walks the same rungs:

meho_connector_list — which connectors can this session reach.
list_operation_groups — the enabled operation groups on one connector, each with a "when to use this group" description.
search_operations — find the operation, optionally scoped to a group.
preview_operation / call_operation — preview, then run against a target.
result_query — page a large, set-shaped result back from its handle.

The operator planes (behind `mcp:admin`)¶

The governance and lifecycle tools — connector lifecycle and ingest, agents / principals / grants, scheduler, sensors, broadcast overrides, runbook template authoring, topology mutations, target registration, doc-collection create/delete, memory promotion, approvals read, and audit query — form a second tier of 53 operator-plane tools. They are absent from a default session's tool list and refused at call time, and they appear only for a session that explicitly requested the mcp:admin OAuth scope.

Elevation is a per-session, explicit opt-in — not a standing role. A session must choose to hold the operator planes; it never carries them by default on the strength of its identity. That is what keeps a routine agent session from reaching the governance controls it does not need.

How a client requests elevation¶

The client asks for the extra scope, and your realm mints it into the token only on request (the realm grants mcp:admin request-only):

Claude Code plugin — set the MEHO_MCP_SCOPES environment seam to the space-separated scopes you want, adding mcp:admin:
```
MEHO_MCP_SCOPES="mcp:read mcp:execute offline_access mcp:admin"
```
The variable replaces the whole default list. Keep offline_access in it, so the login still lasts between uses.
Claude Desktop .mcpb bundle — set the bundle's OAuth scopes (scopes) user-config field to the same value in the install dialog.

The meho-mcp client on your realm must offer mcp:admin as an optional client scope first. If it does not, Keycloak refuses the whole login with invalid_scope and issues no token — it does not drop the scope silently. Leave the scope off entirely and the session stays on the 26-tool working surface, which is the right default for almost every agent.

Which tenant a session works in¶

One login can belong to several tenants. MEHO works in one tenant per request: the tenant that the Meho-Tenant header names (a tenant name or ID). A client sends the same header on every request of a session, so one MCP session works in one tenant from start to end. No tool switches the tenant inside a session. So an agent stays in the tenant the person chose.

Your login has one tenant: set nothing. Nothing changes for you.
Your login has several tenants: set the tenant before the session starts:
- Claude Code plugin — MEHO_TENANT="<tenant name or ID>" in your shell profile or in ~/.config/meho/plugin.env.
- Claude Desktop .mcpb bundle — the Tenant field in the extension settings.
- Claude Code without the plugin — a Meho-Tenant entry under headers in .mcp.json; see Claude Code.
No tenant set, several tenants: the session may only call meho_status. It lists your tenants and your role in each. MEHO refuses every other tool until you set a tenant and start a new session.
To switch tenant: change the setting, then start a new session. The first session in a tenant opens a browser login once more, because the shim keeps one saved login per tenant setting.
A tenant you are not a member of: MEHO refuses the session with tenant_not_member.

The human-only decision verbs (no MCP path)¶

Three verbs have no MCP registration under any scope, elevated or not:

meho_approvals_approve
meho_approvals_reject
meho_agents_grant_elevate

Approving an operation, rejecting it, or granting an agent more access are human decisions. They are absent from every session's tool list, and a direct tools/call on any of them is refused before the tool registry is even consulted, with a remediation that names the human path: the operator console approvals queue, or the concrete CLI verb (meho approvals approve <request-id>, meho approvals reject <request-id> --reason <text>, meho agent grant elevate …).

This is why an agent can never approve its own work. A model session that parks a risky operation cannot hold the button that clears its own gate — that decision moves to a person at the console or the CLI. Elevating to mcp:admin does not change this: the three verbs are not "operator-plane tools you can unlock", they simply do not exist on MCP.

Naming that trips people up¶

A few names on the working surface are easy to get wrong. Getting them right saves a round of -32602 errors:

call_operation's operation argument is op_id — the operation identifier from search_operations, not a field called op or operation.
call_operation's target resolves by name — the human-readable target name, not the UUID that list_targets returns.
The broadcast tools carry the meho_ prefix — meho_broadcast_recent, meho_broadcast_announce, meho_broadcast_watch. Drop the prefix and the name is not a registered tool.

The full tool inventory¶

This page describes the tiering, not every row. The complete per-tool inventory — each tool, its surface tier, and the claim that gates it — is published as a generated MCP tool reference in the Reference section, generated from the live tools/list snapshot so it cannot drift from the product.