> ## 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. # Tools > MCP tools for managing upstream MCP server connections and their catalogs Tool-management tools register the MCP servers that Gateways proxy for agents. Each connection represents an upstream MCP server agents access through Dome. These tools require workspace context. For Gateway membership and access grants, refer to [Gateways](/reference/mcp/gateway). For LLM model connections, refer to [Models](/reference/mcp/models). ## Tool CRUD ### dome\_tool\_list List MCP server connections in the active workspace. Returns name, URL, protocol, auth method, outbound headers, and field classifications for each. | Parameter | Type | Required | Description | | --------- | ---- | -------- | ------------- | | — | — | — | No parameters | **Permission:** `gateway.view` ```json title="Example tool call" theme={"system"} { "name": "dome_tool_list" } ``` ### dome\_tool\_get Get an MCP server connection by name. | Parameter | Type | Required | Description | | --------- | ------ | -------- | ----------- | | `name` | string | Yes | Tool name | **Permission:** `gateway.view` ### dome\_tool\_add Add a new MCP server connection. Connections route the gateway to external MCP servers agents reach through Dome. | Parameter | Type | Required | Description | | ----------------------- | ------ | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | string | Yes | Tool name (unique within workspace) | | `url` | string | Yes (streamable-http) | Tool URL | | `command` | string | Yes (stdio) | Command to exec | | `args` | array | No | Command args for `stdio` | | `protocol` | string | No | `streamable-http`, `stdio` (default: `streamable-http`) | | `headers` | array | No | Outbound headers. Each entry: `{name, source, value, secret}`. `source` is `literal` (with `value`), `secret` (with `secret` key name), or `actas` (no value/secret — reinjects the verified `X-Dome-Act-As`). `stdio` rejects headers. `Authorization` is reserved for the managed auth flow. | | `authorization` | string | No | `Authorization` HTTP header value. REQUIRED when `auth_method=api-key` and `credential_type=shared`. Forbidden otherwise. The server auto-injects the matching managed `Authorization` header — do not declare it manually. | | `secret_values` | object | No | Advanced: per-tool credential bundle for custom secret-source headers. `Authorization` is reserved. | | `auth_method` | string | No | `none`, `api-key`, `oauth` | | `credential_type` | string | No | `shared`, `per-user` | | `oauth` | object | No | OAuth client config (required when `auth_method=oauth`) | | `field_classifications` | object | No | Field sensitivity classifications (e.g. `{"email": "PII"}`) | | `write_tools` | array | No | Tool names classified as write operations | | `gateways` | array | No | [Gateway](/connect/gateways) names to attach the connection to as a tool source at create time. Without it the connection is unreachable until attached (`dome_gateway_tool_source_add`). | **Permission:** `gateway.manage` The `oauth` object accepts: | Field | Description | | ---------------------------- | -------------------------------------------------------- | | `authorize_url` | Authorization endpoint URL | | `token_url` | Token endpoint URL | | `revoke_url` | Revocation endpoint URL | | `registration_url` | RFC 7591 registration endpoint (for `client_origin=dcr`) | | `client_id` | OAuth client ID | | `client_secret` | OAuth client secret | | `default_scopes` | Array of default scopes | | `client_origin` | `dcr` or `manual` | | `token_endpoint_auth_method` | `auto`, `client_secret_basic`, or `client_secret_post` | When `auth_method=oauth` and `credential_type=shared`, the response includes `oauth_connect_url` — open it in a browser to complete consent. ```json title="Shared OAuth tool" theme={"system"} { "name": "dome_tool_add", "arguments": { "name": "notion", "url": "https://mcp.notion.com/mcp", "auth_method": "oauth", "credential_type": "shared", "oauth": { "authorize_url": "https://api.notion.com/v1/oauth/authorize", "token_url": "https://api.notion.com/v1/oauth/token", "client_id": "...", "client_secret": "...", "client_origin": "manual", "default_scopes": ["read_content", "update_content"] } } } ``` ### dome\_tool\_update Update an existing MCP server connection. Only provided fields are changed. | Parameter | Type | Required | Description | | ------------------------------ | ------ | -------- | ------------------------------------------------------------------ | | `name` | string | Yes | Tool name to update | | `url` | string | No | New URL | | `protocol` | string | No | New protocol | | `headers` | array | No | Replace the full outbound header list. Omit to keep current. | | `authorization` | string | No | Rotate an `api-key`+`shared` tool's token | | `secret_values` | object | No | Advanced: replace per-tool credential bundle. Empty `{}` wipes it. | | `auth_method` | string | No | New auth method | | `credential_type` | string | No | New credential scope | | `oauth` | object | No | OAuth client config patch. Empty `client_secret` keeps existing. | | `field_classifications` | object | No | Add or update field classifications | | `remove_field_classifications` | array | No | Remove field classifications by name | | `write_tools` | array | No | Replace write-tools list | **Permission:** `gateway.manage` Switching `auth_method` between `api-key` and `oauth` clears the previously stored credential bundle. ### dome\_tool\_oauth\_connect Begin the shared-OAuth admin consent flow for a tool. Returns a one-shot URL the operator opens in a browser to consent at the upstream's authorization server. Only valid for `auth_method=oauth`, `credential_type=shared`. Per-user OAuth tools trigger consent automatically on each end user's first call. | Parameter | Type | Required | Description | | --------- | ------ | -------- | ----------- | | `name` | string | Yes | Tool name | **Permission:** `gateway.manage` The response includes `oauth_connect_url` and `oauth_connect_expires_at`. Open the URL within \~10 minutes. ### dome\_tool\_oauth\_disconnect Disconnect (revoke) shared OAuth credentials. The OAuth client configuration is preserved, so re-running connect reuses the same client. Idempotent. Marked destructive. | Parameter | Type | Required | Description | | --------- | ------ | -------- | ----------- | | `name` | string | Yes | Tool name | **Permission:** `gateway.manage` ### dome\_tool\_remove Remove an MCP server connection from the active workspace. Marked destructive. | Parameter | Type | Required | Description | | --------- | ------ | -------- | ------------------- | | `name` | string | Yes | Tool name to remove | **Permission:** `gateway.manage` Removing a tool disconnects all agents currently routing through it. Update or re-route agents first. ## Tool Catalog ### dome\_tools\_for\_connection List the operations Dome has discovered on one MCP server connection. This reads the stored catalog and does not apply Gateway membership or agent rules. | Parameter | Type | Required | Description | | ------------- | ------- | -------- | ---------------------------------------------------------------------------------------------------------- | | `name` | string | Yes | Tool name | | `seen_since` | string | No | Include operations seen within this duration, such as `30d` or `24h`. Pass `0` for all recorded operations | | `with_schema` | boolean | No | Include each operation's input schema. Defaults to `true` | **Permission:** `gateway.view` ```json title="List discovered operations" theme={"system"} { "name": "dome_tools_for_connection", "arguments": { "name": "notion", "with_schema": false } } ``` ## Tool Lifecycle Transition individual MCP tools (the items inside a connection's catalog) through `active` → `deprecated` → `blocked`. Status persists across re-observation — once set, only an explicit restore returns the tool to `active`. ### dome\_tool\_block Hide an MCP tool from agents. The Gateway filters it out of `tools/list` and denies any `tools/call` against it; blocked-call attempts emit a `tool.blocked_call_denied` audit event. A block takes precedence over ordinary connection-level access. | Parameter | Type | Required | Description | | ------------ | ------ | -------- | --------------------------------------------------------- | | `connection` | string | Yes | MCP connection name | | `tool` | string | Yes | Tool name as observed in the catalog (e.g. `delete_page`) | | `message` | string | No | Operator note shown in dashboards | **Permission:** `gateway.manage` ```json title="Block a dangerous tool" theme={"system"} { "name": "dome_tool_block", "arguments": { "connection": "notion", "tool": "delete_page", "message": "dangerous mass-delete; use archive_page" } } ``` ### dome\_tool\_deprecate Mark a tool as deprecated. The tool stays callable and visible to agents — the dashboard surfaces a warning chip and the status flows through the catalog. Use when an upstream supersedes a tool and you want to soft-signal callers. | Parameter | Type | Required | Description | | ------------ | ------ | -------- | ------------------------------------------- | | `connection` | string | Yes | MCP connection name | | `tool` | string | Yes | Tool name as observed in the catalog | | `message` | string | No | Operator note (e.g. `"use create_page_v2"`) | **Permission:** `gateway.manage` ### dome\_tool\_restore Restore a tool to `active`, clearing any prior block or deprecation. | Parameter | Type | Required | Description | | ------------ | ------ | -------- | ------------------------------------ | | `connection` | string | Yes | MCP connection name | | `tool` | string | Yes | Tool name as observed in the catalog | **Permission:** `gateway.manage` ## Next steps Attach backends under Connect. Named Gateways and grants are a separate tool group: * [Tools](/connect/resources/tools) * [Models](/connect/resources/models) * [Gateways](/reference/mcp/gateway)