Discover and Govern Connector Tools

Purpose

Review discovered MCP tools, declare their schemas and behavior in YAML, and enable approved tools for a Team.

Prerequisites

• Register and authenticate the server using Connector administration.
• Use organization.owner or organization.admin with organization.settings.manage for discovery and administrative review; have access to reviewed organization YAML.
• Use team.allowance.manage for Team allowance and the exact key/deployment manager for execution policy.

Procedure

1. Open Connectors, select the server, and select Refresh connection.
2. Review Discovery diff and its declared/discovered schema hashes. Under Declare, choose which new or drifted candidates to include and their classifications. Review approval, rules, automatic execution and pricing in the copied YAML before changing the file.
3. Edit YAML, then operator preflight and a coordinated gateway/Console restart. Review preflight warnings before restarting.
4. Enable the tool or tool set in the Team, and add it to the intended key/deployment policy when needed.
5. Make a synthetic governed call and verify its canonical decision under Observe → Requests.

Discover tools

Select Refresh connection. Mission Control connects with the server credential from the active organization configuration, not the administrator's inbound credential. The button reports Discovered n tools (or why discovery failed). A successful discovery stores one shared result for the organization and server: bounded server name/version/protocol metadata (2026-07-28) plus tool name, description, canonical input schema, and SHA-256 schema hash. The result does not vary by the administrator who ran discovery. The official client validates modern tool definitions and x-mcp-header declarations before they enter the catalog. Invocation reuses that resolved definition so custom headers are present on the first outbound call rather than learned through a rejected call and retry. Discovery does not store a server credential or execute a business tool.

Expected result: the server page shows the configured Headers authentication mode. File inspection alone shows credential resolution unavailable; it does not assert that a provider accepted the credentials. Gateway startup refuses missing referenced secrets. Refresh connection, scheduled checks, and later tool calls use the same prepared header set. Literal values are never treated as secret references, and actual values do not appear in the server-page projection, invocation history, traces, or ordinary logs.

If validation reports an invalid configuration, check for an empty header map, duplicate names that differ only by case, a reserved name, both/neither value fields, an unsupported value character, or a size-limit violation. If it reports a missing env/NAME, set the nonempty variable, restart the gateway, and run preflight again. Invalid configuration refuses startup; it does not replace a running process before restart.

The Discovery diff compares the latest successful discovery with the loaded YAML declaration:

Endpoint and connection diagnostics describe the server; each tool row shows its classification, discovery state and shortened schema hashes. Canonical invocation evidence is under Observe → Requests.

State	Eligible	Meaning and action
Matched	Yes when server enabled	Name exists in both places and hashes match.
Undeclared	No	Server advertised a tool not approved in YAML. Review it, then declare it with Declare below.
Schema drift	No	Declared and discovered hashes differ. Review schema and downstream impact; then update YAML deliberately, with Declare.
Missing	No	YAML declares a tool absent from latest successful discovery. Confirm server version or remove the declaration through review.

A disabled server makes even matched tools ineligible. Settings managers use Connector diagnostics and Discovery diff to inspect authorization failure, unavailable tools and schema changes. Connection state is diagnostic; it does not grant tool authority.

Declare discovered tools

Under the discovery diff, Declare turns what discovery found into the exact tools: block for the server. Every undeclared or drifted tool appears with a checkbox (selected by default) and a classification: a drifted tool keeps its declared classification, a new one starts as data. The block below reproduces the whole declaration: matched tools as they are, selected drifted tools with the discovered hash, selected new tools, and nothing for tools discovery no longer lists (the panel names them). Copy YAML puts the block on the clipboard; paste it over the server's tools: in the reviewed organization YAML, then have the operator validate the files and restart gateway and Console. Open your configuration repository separately; the current page provides Copy YAML, not a repository shortcut.

Declare is available only with organization.settings.manage. Its manager-only reader loads the complete validated declarations; generic catalog metadata does not expose rule definitions. The copied block preserves existing approval, rules, autoExecute and costPerCallMicros, including an explicit zero price. Choosing a drifted candidate changes only its reviewed classification and schema hash; excluding it retains its existing declaration. Missing discovered tools are omitted and named in the panel.

Declare writes nothing itself and Copy YAML does not activate configuration. Reviewed file edits, operator preflight and a coordinated gateway/Console restart remain the way a declaration changes.

Declare and classify a tool

Copy the discovered name and hash into YAML and choose exactly one classification:

• data — retrieves or reads information.
• decision — returns a business decision without applying its side effect.
• action — creates an external side effect.

Restart with the reviewed catalog and refresh the connection again. The public tool name becomes <server-id>__<tool-name> and the catalog resource id is tool:<server-id>/<tool-name>. A declared, matched tool is still Not enabled in every team until a team admin enables it on the team home; see Enable models and tools in a team.

An action tool pauses for a person's approval when it is called on /mcp or run inside a model loop, unless its declaration says approval: none; a data or decision tool never pauses unless declared approval: required. Managed deployments use separate durable conversation consent for their exact stored action and original funding. See Approvals.

tools:
  - name: create-ticket
    classification: action
    schemaHash: sha256:7b1a4c0f2d9e8b6a5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a8b7c6d5e4f3a2b
    approval: required

Allow automatic execution inside model calls

A developer can attach the governed tools to a Chat Completions or Responses call and ask the gateway to run some of them inside the call instead of returning every call to their code; see Governed tools on a model call. The gateway runs a tool that way only when three things agree: the request named it, the caller may see it, and its declaration says so:

tools:
  - name: lookup-customer
    classification: data
    schemaHash: sha256:1dc63095e8672403bbe40fa26719d175e695c0167f6daad6b9655f6506491f01
    autoExecute: true

autoExecute defaults to false. It is a per-tool decision, not a classification: marking an action tool is allowed. An action tool that keeps the default approval: required still pauses for a person inside the loop (see Approvals); when it also says approval: none, Preflight reports the warning Action tool server/tool is marked autoExecute and needs no approval; the gateway loop will run it without a person's approval. so the reviewer sees the unattended combination before restarting. The flag changes nothing for /mcp calls, for Chat approvals, or for tools the team has not enabled; a request that does not opt in never triggers a tool.

Tool sets

A tool set is a named bundle of declared tools, declared at the top level of the organization YAML and treated as one catalog resource, toolset:<id>:

toolSets:
  - id: support
    name: Support tools
    tools:
      - crm/lookup-customer
      - crm/create-ticket

A Team allowance can explicitly follow a tool set; selected key/deployment policy can follow it too. Current loaded membership expands inside catalog ∩ Team allowance ∩ key policy. This never widens schema/discovery/server eligibility. Empty or absent sets grant nothing. A content checkbox in Builder selects a requirement; it is not itself an API grant. Review execution policy during deployment preflight.

Rules on arguments and results

A rule blocks, redacts or only detects content in a tool's arguments before any credential is prepared, and in its results before they reach the caller and before capture. Rules live in the reviewed YAML at three levels and are evaluated in that order for every tool they cover: the organization (rules at the top level covers every tool of every Connector), a Connector (rules under the server covers its tools) and one tool (rules under the declaration).

rules:
  - id: secrets
    action: detect
    match:
      secrets: true

connectors:
  - id: crm
    # …
    rules:
      - id: no-bulk-export
        action: block
        applies: arguments
        argument: query
        match:
          regex: "export all"
    tools:
      - name: lookup-customer
        classification: data
        schemaHash: sha256:1dc63095e8672403bbe40fa26719d175e695c0167f6daad6b9655f6506491f01
        rules:
          - id: card-numbers
            action: redact
            applies: results
            match:
              regex: "\\b[0-9]{13,19}\\b"

• block refuses the call. On arguments the decision is rejected with error_code: rule_blocked and nothing is dispatched; on results the call has run, the decision fails with rule_blocked, and the caller receives the fixed error instead of the result. On /mcp the client sees HTTP 200 / JSON-RPC -32603 with the fixed message Tool invocation blocked by policy and data.code: "rule_blocked"; a model loop feeds the same text to the model.
• redact replaces every match with [redacted:<rule id>]; a maxLength match is cut to the limit and marked …[truncated:<rule id>], and an allow match replaces the whole value. Redacted arguments are what the upstream receives and what an approval stores; redacted results are what the caller and the capture see.
• detect changes nothing and records the rule on the decision.

applies chooses arguments, results or both (the default). argument limits an argument rule to one top-level argument; otherwise every string in the arguments is inspected. Result rules inspect the text items of the MCP result only. match names exactly one matcher: regex (an RE2 expression), maxLength, allow (the only accepted values) or secrets: true (built-in shapes: AWS access keys, GitHub, Slack, Google and Stripe live keys, PEM private keys, bearer tokens, and api_key, secret, token or password assignments). Rule ids are unique across the file, and Preflight refuses a duplicate id, an invalid regex, and an argument or allow rule that applies to results only; see Rules for every field.

regex and secrets run in RE2, so matching time grows linearly with the text and crafted arguments or results cannot stall the gateway. RE2 has no look-around ((?=…), (?<=…) and their negative forms) and no backreferences (\1, \k<name>); \d, \w, \s and \b are ASCII-only. A pattern using JavaScript-only syntax, or one too large for RE2's fixed memory such as \p{L}{100}, fails config:check and startup with Rule <id> has an invalid regex. Rewrite it to match the text it needs, for example id=[0-9]+ instead of (?<=id=)[0-9]+ (the marker then also covers id=); see Regular expressions for more rewrites.

Rule matching is bounded per decision (the argument rules of a call, or its result rules): at most 100,000 searches and 8,388,608 characters read plus 4 for every inspected character. A decision reaches a limit only with more than about a thousand matches of one expression in the same text or 100,000 searches, for example 100,000 argument strings checked by one rule. Then the rule being evaluated and every later regex or secrets rule count as matching: block refuses the call or result with rule_blocked, redact replaces the rest of the unsearched text with [redacted:<rule id>], and detect records the rule.

Each search reads at most 1,310,720 bytes of UTF-8, which is 1,310,720 ASCII characters and at least 436,905 characters of any text. Longer text, such as a very large result, is searched in windows that overlap by half. A regex that can match text longer than that overlap, meaning any *, + or {n,}, counts as matching such text unless a window finds a match. So a block rule like DROP\s+TABLE blocks a multi-megabyte result even without a match, and a redact rule replaces the text from where it could not finish. Bound the repetition, for example DROP\s{1,100}TABLE, to keep such a rule exact on large results. secrets: true fails closed only for a private-key block or a whitespace-padded assignment longer than a whole window. See Regular expressions.

One rule is recorded per decision: the first blocking rule, else the first redacting one, else the first detecting one, in declaration order. Canonical Request detail shows Rule, Rule action and Approval metadata. Matched content itself is never recorded, logged or returned. An Open approval id link appears only when the viewer may read that approval; request metadata does not grant its private arguments or decision note.

Inspect a tool

The eligible tool’s detail page shows its name, tool:<server-id>/<tool-name> identifier and the current authorization boundary. It requires catalog access and does not expose a schema or invocation-history pane. Review classification/state/hashes in the manager’s Discovery diff. An ineligible tool’s detail remains unavailable; use the discovery row to diagnose it.

Invocation history

Use Observe → Requests, filtered to the tool resource, for canonical outcomes, correlation and governance evidence. This is separately authorized from catalog or settings access. Captured diagnostic content needs its own content permission; no credential appears in the request record.

The catalog-authorized Connectors overview lists configured servers and eligible tool names/counts. Only settings managers can open server diagnostics, declarations and company authorization actions. Managers read matching gateway boot status once per list/detail view; other readers see Gateway status unavailable rather than a guessed current state. Opening the page performs no business probe. The gateway's tools/list reads the shared stored discovery and applies the requesting caller's Team allowance, key policy and authorization locally. It never performs caller-specific upstream discovery and returns only tools that are eligible, enabled in the key's team, and covered by the caller's access.

Verification and failure recovery

Require Matched, an enabled server and Team resource, and caller access before testing. Discovery alone does not enable tools. A schema drift or missing state fails closed: review the server change, update the declaration deliberately, run config:check, restart gateway/Console and refresh again. Correct credentials through Connector administration. Running processes keep their loaded configuration until restart; there is no Console Apply or saved-revision activation step.

Bounded tool charges

For tools under finite spend caps, configure the actual tool's costPerCallMicros in reviewed YAML. An explicit 0 declares known-zero cost; absent pricing remains unknown and can be refused before dispatch. Every physical business call is counted once, with no model-token charge; model rounds are metered separately. Restart gateway/Console after price changes. See tool pricing.

Related links

• Use MCP from code
• Configuration workflow
• Approvals