> ## Documentation Index > Fetch the complete documentation index at: https://docs.domesystems.ai/llms.txt > Use this file to discover all available pages before exploring further. # dome tool > Manage MCP server connections the gateway proxies for agents `dome tool` registers upstream MCP servers (the "tools" an agent reaches through Dome) and manages their auth, outbound headers, and field classifications. To list the capabilities each agent currently sees, use [`dome agents list`](/cli/connect/agents#list) instead. | Command | | | --------------------------------------- | ------------------------------------------------------------- | | [List](#list) | `dome tool list [workspace-id-or-slug]` | | [Get](#get) | `dome tool get [workspace-id-or-slug]` | | [Add](#add) | `dome tool add [workspace-id-or-slug]` | | [Update](#update) | `dome tool update [workspace-id-or-slug]` | | [Remove](#remove) | `dome tool remove [workspace-id-or-slug]` | | [OAuth connect](#oauth-connect) | `dome tool oauth-connect [workspace-id-or-slug]` | | [OAuth disconnect](#oauth-disconnect) | `dome tool oauth-disconnect [workspace-id-or-slug]` | | [Gateways](#gateways) | `dome tool gateways list\|add\|remove [gateway]` | | [Header list](#header-list) | `dome tool header list ` | | [Header add](#header-add) | `dome tool header add ` | | [Header remove](#header-remove) | `dome tool header remove ` | | [Catalog list](#catalog-list) | `dome tool catalog list [workspace-id-or-slug]` | | [Catalog sync](#catalog-sync) | `dome tool catalog sync [workspace-id-or-slug]` | | [Catalog block](#catalog-block) | `dome tool catalog block ` | | [Catalog deprecate](#catalog-deprecate) | `dome tool catalog deprecate ` | | [Catalog restore](#catalog-restore) | `dome tool catalog restore ` | *** ## List `dome tool list [workspace-id-or-slug]` List MCP server connections. Aliases: `ls`. ## Get `dome tool get [workspace-id-or-slug]` Show details for one tool connection. ## Add `dome tool add [workspace-id-or-slug]` Register a new MCP server. | Flag | Type | Required | Default | Description | | ----------------------------- | ----------------------------- | ---------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--name` | string | Yes | — | Tool name (unique within workspace) | | `--url` | string | Streamable | — | URL (required for `streamable-http`) | | `--command` | string | Stdio | — | Command to exec (required for `stdio`) | | `--arg` | string (repeatable) | No | — | Command argument for `stdio` | | `--protocol` | string | No | `streamable-http` | `streamable-http`, `stdio` | | `--header-literal` | `Name=Value` (repeatable) | No | — | Literal outbound header | | `--header-secret` | `Name=SecretKey` (repeatable) | No | — | Outbound header sourced from a stored secret | | `--header-actas` | `Name` (repeatable) | No | — | Header that reinjects the verified `X-Dome-Act-As` | | `--authorization` | string | No | — | `Authorization` HTTP header value. REQUIRED with `--auth-method=api-key --credential-type=shared`. The server auto-injects the managed `Authorization` header — do not declare it via `--header-secret`. | | `--secret-value` | `KEY=VALUE` (repeatable) | No | — | Advanced: per-tool credential bundle entry for custom secret-source headers. The `Authorization` key is reserved — use `--authorization` instead. | | `--auth-method` | string | No | `none` | `none`, `api-key`, `oauth` | | `--credential-type` | string | No | — | `shared`, `per-user` | | `--oauth-authorize-url` | string | No | — | OAuth: authorize endpoint | | `--oauth-token-url` | string | No | — | OAuth: token endpoint | | `--oauth-revoke-url` | string | No | — | OAuth: revocation endpoint | | `--oauth-registration-url` | string | No | — | OAuth: RFC 7591 registration endpoint (for `client-origin=dcr`) | | `--oauth-client-id` | string | No | — | OAuth: client ID (required when `client-origin=manual`) | | `--oauth-client-secret` | string | No | — | OAuth: client secret | | `--oauth-default-scope` | string (repeatable) | No | — | OAuth: default scope | | `--oauth-client-origin` | string | No | — | OAuth: `dcr` or `manual` | | `--oauth-token-endpoint-auth` | string | No | `auto` | OAuth: `auto`, `client_secret_basic`, `client_secret_post`. `auto` discovers the server's preferred method via RFC 8414 metadata. | | `--field-classification` | `key=value` | No | — | Field sensitivity labels (e.g. `email=PII,phone=PII`) | | `--write-tools` | string | No | — | Comma-separated list of tool names classified as write operations | | `--gateway` | string (repeatable) | No | — | Attach as a tool source to the named [Gateway](/connect/gateways) (name or ID). Without it the connection is unreachable until attached. | When `--auth-method=oauth --credential-type=shared`, `add` automatically prints the URL to start the admin consent flow. Open it in a browser to complete consent. If the flow can't start automatically, run [`oauth-connect`](#oauth-connect) afterwards. ```bash title="Shared OAuth tool (manual client)" theme={"system"} dome tool add \ --name notion \ --url https://mcp.notion.com/mcp \ --auth-method oauth \ --credential-type shared \ --oauth-client-origin manual \ --oauth-authorize-url https://api.notion.com/v1/oauth/authorize \ --oauth-token-url https://api.notion.com/v1/oauth/token \ --oauth-client-id "$NOTION_CLIENT_ID" \ --oauth-client-secret "$NOTION_CLIENT_SECRET" \ --oauth-default-scope read_content \ --oauth-default-scope update_content ``` ```bash title="Per-user OAuth tool (dynamic client registration)" theme={"system"} dome tool add \ --name jira \ --url https://mcp.atlassian.com/v1/sse \ --auth-method oauth \ --credential-type per-user \ --oauth-client-origin dcr \ --oauth-authorize-url https://auth.atlassian.com/authorize \ --oauth-token-url https://auth.atlassian.com/oauth/token \ --oauth-registration-url https://auth.atlassian.com/oauth/clients ``` ## Update `dome tool update [workspace-id-or-slug]` Update an MCP server connection. Only provided flags change. Switching `--auth-method` between `api-key` and `oauth` clears the previously stored credential bundle. | Flag | Type | Description | | ------------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------- | | `--url` | string | New URL | | `--command` | string | New command (stdio) | | `--arg` | string (repeatable) | Replace command args | | `--protocol` | string | `streamable-http`, `stdio` | | `--header-literal` | `Name=Value` (repeatable) | Replace literal-header list | | `--header-secret` | `Name=SecretKey` (repeatable) | Replace secret-header list | | `--header-actas` | `Name` (repeatable) | Replace act-as header list | | `--authorization` | string | New `Authorization` value. Use to rotate an `api-key`+`shared` tool's token. | | `--secret-value` | `KEY=VALUE` (repeatable) | Advanced: replace per-tool credential bundle | | `--auth-method` | string | `none`, `api-key`, `oauth` | | `--credential-type` | string | `shared`, `per-user` | | `--oauth-*` | various | OAuth client config overrides (same shape as `add`). Empty `--oauth-client-secret` keeps the existing secret. | | `--field-classification` | `key=value` | Add or update field classifications | | `--remove-field-classification` | string\[] | Remove field classifications by name | | `--write-tools` | string | Comma-separated write-tools list (replaces current) | ## Remove `dome tool remove [workspace-id-or-slug]` Remove an MCP server connection. ## Gateways `dome tool gateways [gateway-name-or-id]` Manage the connection's tool-source membership in [Gateways](/connect/gateways) from the connection side. Mirrors [`dome gateway tool-sources`](/cli/connect/gateway#tool-sources-add). * `list ` — Gateways this connection is a tool source of. Alias: `ls`. * `add ` — attach as a tool source; every observed tool joins, and newly discovered tools propagate automatically. * `remove ` — detach. Alias: `rm`. ```bash theme={"system"} dome tool gateways add notion prod-tools ``` ## OAuth connect `dome tool oauth-connect [workspace-id-or-slug]` Begin the shared-OAuth admin consent flow. Prints a one-shot URL valid for \~10 minutes. Open it in a browser to complete consent at the upstream's authorization server. After consent, Dome stores the tokens. Only valid for `--auth-method=oauth --credential-type=shared` tools. Per-user OAuth tools trigger consent automatically on each end user's first call. ```bash theme={"system"} dome tool oauth-connect notion ``` ## OAuth disconnect `dome tool oauth-disconnect [workspace-id-or-slug]` Revoke shared OAuth credentials. The OAuth client configuration is preserved, so a subsequent `oauth-connect` reuses the same client. Idempotent. ```bash theme={"system"} dome tool oauth-disconnect notion ``` ## Header list `dome tool header list [workspace-id-or-slug]` List the outbound headers configured on a tool. ## Header add `dome tool header add [workspace-id-or-slug]` Append outbound headers to a tool without replacing the existing list. Combine `--header-literal`, `--header-secret`, and `--header-actas` flags (refer to [`add`](#add) for shapes). ## Header remove `dome tool header remove [workspace-id-or-slug]` Remove outbound headers by name from a tool. ## Catalog list `dome tool catalog list [workspace-id-or-slug]` List the persistent MCP tool catalog for a connection — the tools the gateway has observed on the upstream MCP server. The catalog survives gateway restarts and stays queryable without a live data plane. | Flag | | | ---------------- | -------------------------------------------------------------------------------------------------------------------- | | `--with-schema` | Include input schema in the output (truncated). | | `--seen-since` | Only include tools seen within this window (e.g. `30d`, `24h`). Pass `0` for all-time. Defaults to `720h` (30 days). | | `--show-blocked` | Include blocked tools (hidden by default). | ```bash theme={"system"} dome tool catalog list notion --seen-since 7d ``` ## Catalog sync `dome tool catalog sync [workspace-id-or-slug]` Sync the persistent MCP tool catalog for a `per-user` connection by dispatching exactly one upstream `tools/list` against the calling admin's own per-user credential. Shared connections already pre-warm via the gateway's startup discovery and are rejected client-side. Attach your per-user credential first through the normal magic-link flow (refer to [`oauth-connect`](#oauth-connect) or the per-user provisioning flow in the dashboard), then run this command. Sync works both before any agent traffic (pre-warm) and after (refresh). The result is recorded through the shared catalog observation path and is visible to `dome tool catalog list` immediately afterwards. | Flag | | | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--act-as-sub` | Workspace-verified act-as subject under which the admin attached the per-user credential. Defaults to the calling admin's email. Required when the workspace's act-as verifier does not use email as Sub (e.g. OIDC/HMAC verifiers issuing opaque subs, or `local-auth` which sets Sub to a user UUID). | ```bash theme={"system"} dome tool catalog sync notion ``` Prints four counters: tools observed, inserted, updated schema, and updated last-seen. Requires the `gateway.manage` permission. Returns `FailedPrecondition` when no per-user credential exists at the resolved sub-hash — the error message names both remedies (attach the credential, or pass `--act-as-sub`). ## Catalog block `dome tool catalog block ` Hide a discovered MCP tool from agents. The Gateway filters the tool out of `tools/list` and denies any `tools/call` against it. A block takes precedence over ordinary connection-level access. Blocks persist across re-observation. | Flag | Type | Required | Description | | ----------- | ------ | -------- | --------------------------------------------------------------------------------------------- | | `--message` | string | No | Operator note shown alongside the tool in dashboards and CLI (e.g. `"dangerous mass-delete"`) | Requires the `gateway.manage` permission. Blocked-call attempts emit a `tool.blocked_call_denied` audit event. ```bash theme={"system"} dome tool catalog block notion delete_page --message "dangerous mass-delete; use archive_page" ``` ## Catalog deprecate `dome tool catalog deprecate ` Mark a tool as deprecated. The tool stays callable and visible to agents; the dashboard renders a warning chip and operators see the status in `dome tool catalog list`. Use when an upstream replaces a tool and you want to soft-signal callers without breaking them. | Flag | Type | Required | Description | | ----------- | ------ | -------- | ------------------------------------------- | | `--message` | string | No | Operator note (e.g. `"use create_page_v2"`) | Requires the `gateway.manage` permission. ```bash theme={"system"} dome tool catalog deprecate notion create_page --message "use create_page_v2" ``` ## Catalog restore `dome tool catalog restore ` Return a tool to `active`, clearing any prior block or deprecation. Requires the `gateway.manage` permission. ```bash theme={"system"} dome tool catalog restore notion delete_page ``` `dome tool catalog list ` shows the current `STATUS` column for every observed tool. Blocked tools are hidden by default — pass `--show-blocked` to include them.