Tools - Dome

Overview

Tools are one of the resource types Dome makes available to agents, alongside models. When you add a tool, Dome stores its server endpoint, credentials, and egress headers. Dome records the operations the server exposes once the gateway connects to it. The typical workflow is:

Add a tool for the upstream MCP server.
If the server requires credentials, configure upstream authentication.
Attach the tool to a Gateway to make it available through a Dome endpoint.
Allow the Gateway on the agent.
Verify discovery to confirm which operations the agent can use.

Upstream authentication

The gateway authenticates to the upstream with credentials you configure on the tool. Agent API keys authenticate inbound requests to Dome and never pass through as upstream credentials. Dome stores upstream secrets and injects them only at egress. Two settings control which credential the gateway sends.

The authentication method defines how the server verifies a request.

Auth method	When the upstream
`none`	Requires no credential
`api-key`	Accepts a static API key or bearer token
`oauth`	Supports OAuth 2.0 or 2.1

The credential type defines whose credential the gateway sends.

With shared credentials, every request reaches the upstream under the same service account. With per-user credentials, each request uses a credential linked to the verified end user, so the upstream applies that user’s permissions.

Credential type	What the gateway sends
`none`	No credential
`shared`	One workspace-managed credential for every call
`per-user`	One credential per verified act-as subject

The two settings are not independent. The none method accepts only the none credential type, and api-key and oauth each require shared or per-user. When you omit the credential type, Dome pairs it with the method: none with none, api-key with shared, and oauth with per-user. OAuth also requires the streamable-http protocol, so a stdio tool cannot use it. You can set authentication when you add a tool or change it later.

Egress headers

Egress headers are values the gateway adds on the outbound request to the upstream. A header can be a literal string, a stored secret, or the verified act-as identity from the inbound request. Only a Streamable HTTP tool can carry them, because a stdio tool has no HTTP request to attach them to. An act-as header sends the verified end-user identity to the upstream, and Dome accepts only OIDC or HMAC verification. Dome denies any call that carries no verified identity or that used a weaker verification method. An act-as header is not valid on a tool that authenticates with OAuth. You can set headers when you add a tool, change them on update, or manage them individually.

Discovered tools

After the gateway connects to an upstream server, every operation that server exposes appears in the tool’s catalog. You can change the status of one operation without removing the entire tool. For example, you can block delete_page while keeping create_page available to agents.

Status	Behavior
`active`	Discoverable and callable when rules allow
`deprecated`	Callable, with a catalog warning
`blocked`	Hidden from discovery and denied on invocation

Blocking an operation denies it even if another rule would permit it. Status persists when the gateway observes the operation again. Only a restore returns it to active. Refer to Manage discovered tools for the operations that change these statuses.

Requirements

Before you begin:

Authenticate to Dome and select a workspace
Have the upstream MCP endpoint (URL for Streamable HTTP, or a local command for stdio)
Have upstream credentials when the server requires them
Have a Gateway ready when you want the tool reachable

Permissions

Tool connection operations require platform permissions. Each operation states its required permission inline.

Default roles	Permission	Grants
All workspace roles	`gateway.view`	List tools and inspect discovered operations
`admin`, `operator`	`gateway.manage`	Add, update, and remove tools and manage discovered operations

Add tool

Add a tool for one upstream MCP server. Use Streamable HTTP for a remote server or stdio for a local process. You can set upstream authentication, egress headers, and Gateway membership in the same call.

Requires gateway.manage.

CLI
MCP
API
Agent

dome tool add \
  --name notion \
  --url "https://mcp.notion.com/mcp" \
  --protocol streamable-http \
  --gateway prod-tools

If you do not define --gateway, the tool stays unreachable until you attach it.Add --auth-method, --credential-type, and header flags if the upstream needs them.

Reference: dome tool add

Tool: dome_tool_add

{
  "name": "notion",
  "url": "https://mcp.notion.com/mcp",
  "protocol": "streamable-http",
  "gateways": ["prod-tools"]
}

Reference: dome_tool_add

POST /dome.mgmt.v1.Management/CreateMCPServerConnection
Content-Type: application/json

{
  "workspace_id": "{{WORKSPACE_ID}}",
  "name": "notion",
  "protocol": "streamable-http",
  "protocol_config": {
    "url": "https://mcp.notion.com/mcp"
  }
}

The endpoint returns the new tool’s UUID, which every other management call uses to address it.

Reference: CreateMCPServerConnection

Attach an MCP server

Add a Streamable HTTP tool named "notion" at https://mcp.notion.com/mcp. Attach it to the "prod-tools" Gateway.

A tool remains unavailable to agents until you attach it to a Gateway. You can configure authentication and headers before attaching it.

Update tool

Update a tool to change its connection or security settings. You can change its URL, protocol, authentication, headers, or the operations Dome treats as writes. Switching between api-key and oauth clears the previously stored credentials. A header list always replaces the existing list rather than merging into it. How the other fields merge depends on the interface you use.

Requires gateway.manage.

CLI
MCP
API
Agent

dome tool update notion \
  --url "https://mcp.notion.com/mcp"

Only the flags you pass change.

Reference: dome tool update

Tool: dome_tool_update

{
  "name": "notion",
  "url": "https://mcp.notion.com/mcp"
}

Only the parameters you send change.

Reference: dome_tool_update

POST /dome.mgmt.v1.Management/UpdateMCPServerConnection
Content-Type: application/json

{
  "workspace_id": "{{WORKSPACE_ID}}",
  "connection_id": "{{CONNECTION_ID}}",
  "protocol": "streamable-http",
  "protocol_config": {
    "url": "https://mcp.notion.com/mcp"
  }
}

Send the record’s full state. The endpoint overwrites protocol, protocol_config, field_classifications, and write_tools with whatever the request carries, so omitting protocol_config clears the URL and headers. Read the tool with GetMCPServerConnection first and send back everything you want to keep. auth_method, credential_type, auth_config, and name are the exceptions, where an empty value preserves the stored one.

Reference: UpdateMCPServerConnection

Update a tool

Update the "notion" tool URL to https://mcp.notion.com/mcp.

Change upstream authentication

You can change how the gateway authenticates to the upstream. Refer to Upstream authentication for the methods and credential types.

Shared API key

Use a shared bearer token when every call should present the same upstream credential. Dome stores the secret and injects it at egress. Agents never receive the raw upstream credential.

CLI
MCP
API
Agent

dome tool update internal-search \
  --auth-method api-key \
  --credential-type shared \
  --authorization "Bearer $SEARCH_TOKEN"

On create, the same flags work with dome tool add.

Reference: dome tool update

Tool: dome_tool_update

{
  "name": "internal-search",
  "auth_method": "api-key",
  "credential_type": "shared",
  "authorization": "Bearer {{SEARCH_TOKEN}}"
}

Reference: dome_tool_update

POST /dome.mgmt.v1.Management/UpdateMCPServerConnection
Content-Type: application/json

{
  "workspace_id": "{{WORKSPACE_ID}}",
  "connection_id": "{{CONNECTION_ID}}",
  "auth_method": "api-key",
  "credential_type": "shared",
  "secret_values": {
    "Authorization": "Bearer {{SEARCH_TOKEN}}"
  }
}

Send protocol and protocol_config alongside these fields, as described in Update tool.

Reference: UpdateMCPServerConnection

Set shared API-key authentication

Set the "internal-search" tool to shared API-key authentication with my bearer token.

Shared OAuth

Configure the OAuth client on the tool, then connect OAuth to complete admin consent. When the upstream publishes RFC 8414 metadata, the gateway discovers its OAuth endpoints. Otherwise, you can provide the authorization, token, revocation, and registration URLs. The gateway supports manual and dynamic client registration.

Per-user credentials

You can set credential type to per-user when upstream authorization must follow the end user. Each request must include a verified act-as identity. Configure runtime act-as authentication in Develop. When an end user has no credential yet, Dome returns 401 with a short-lived provision_url. The user opens that URL to enter an API key or complete OAuth consent, and the call succeeds on retry. Discovery flags the tool as needing credentials until provisioning finishes. Refer to Errors and denials for how a runtime should surface the prompt and retry. For per-user tools, sync the catalog after the admin attaches a per-user credential, so observed operations appear before agent traffic.

Change egress headers

You can change which egress headers the gateway sends, including an act-as header when the upstream needs the verified end user. Refer to Egress headers. An act-as header is not valid on a tool that authenticates with OAuth, and the update fails when you combine them.

CLI
MCP
API
Agent

dome tool update crm \
  --header-actas X-Verified-User

To append without replacing the full list, use Add headers.

Reference: dome tool update

Tool: dome_tool_update

{
  "name": "crm",
  "headers": [
    {"name": "X-Verified-User", "source": "actas"}
  ]
}

Reference: dome_tool_update

POST /dome.mgmt.v1.Management/UpdateMCPServerConnection
Content-Type: application/json

{
  "workspace_id": "{{WORKSPACE_ID}}",
  "connection_id": "{{CONNECTION_ID}}",
  "protocol": "streamable-http",
  "protocol_config": {
    "url": "https://crm.example.com/mcp",
    "headers": [
      {"name": "X-Verified-User", "source": "actas"}
    ]
  }
}

Headers live inside protocol_config, which the endpoint overwrites, so send the URL and any headers you want to keep in the same call.

Reference: UpdateMCPServerConnection

Forward verified act-as identity

Update the "crm" tool to forward verified act-as identity in X-Verified-User.

Get tool

Retrieve a tool by name to inspect its endpoint, protocol, authentication, and Gateway membership. This information helps you verify its configuration before an update or troubleshoot why agents cannot reach it.

Requires gateway.view.

CLI
MCP
API
Agent

dome tool get notion

Reference: dome tool get

Tool: dome_tool_get

{
  "name": "notion"
}

Reference: dome_tool_get

POST /dome.mgmt.v1.Management/GetMCPServerConnection
Content-Type: application/json

{
  "workspace_id": "{{WORKSPACE_ID}}",
  "connection_id": "{{CONNECTION_ID}}"
}

The management API addresses a tool by UUID rather than by name. Call ListMCPServerConnections to resolve a name to its ID.

Reference: GetMCPServerConnection

Get a tool

Get the "notion" tool and confirm its auth method and Gateway membership.

List tools

Retrieve the tools in a workspace with their protocols and authentication methods. Use the list to find the tool you want to update or remove.

Requires gateway.view.

CLI
MCP
API
Agent

dome tool list

Reference: dome tool list

Tool: dome_tool_list

{}

Reference: dome_tool_list

POST /dome.mgmt.v1.Management/ListMCPServerConnections
Content-Type: application/json

{
  "workspace_id": "{{WORKSPACE_ID}}"
}

Reference: ListMCPServerConnections

List tools

List the tools in this workspace.

Remove tool

Remove a tool to delete its upstream record from the workspace, along with the authentication and header configuration stored on it.

Requires gateway.manage.

Removing a tool disconnects every agent currently routing through it. Update or re-route agents first.

CLI
MCP
API
Agent

dome tool remove notion

Reference: dome tool remove

Tool: dome_tool_remove

{
  "name": "notion"
}

Reference: dome_tool_remove

POST /dome.mgmt.v1.Management/DeleteMCPServerConnection
Content-Type: application/json

{
  "workspace_id": "{{WORKSPACE_ID}}",
  "connection_id": "{{CONNECTION_ID}}"
}

Reference: DeleteMCPServerConnection

Remove a tool

Remove the "notion" tool after confirming no agents still depend on it.

Manage discovered tools

Catalog status lets you block or deprecate individual operations without removing the entire tool. Status persists when the gateway observes the operation again. Only a restore returns it to active. Refer to Discovered tools for the behavior of each status. You can block, deprecate, and restore operations through the CLI and MCP. The API reference documents catalog sync only.

List catalog

Retrieve the operations Dome has recorded for a tool. Because Dome stores the catalog, you can inspect it when the upstream server is unavailable. The result covers everything Dome discovered on the server, not what one agent can call.

Requires gateway.view.

CLI
MCP
Agent

dome tool catalog list notion --seen-since 7d

Blocked entries are hidden unless you pass --show-blocked. Use --with-schema when you need input schemas.

Reference: dome tool catalog list

Tool: dome_tools_for_connection

{
  "name": "notion",
  "with_schema": false
}

Reference: dome_tools_for_connection

List discovered operations

List the operations Dome has discovered on the "notion" tool.

Sync catalog

Sync the catalog to discover operations on a per-user tool before agent traffic begins. The gateway calls upstream tools/list with the administrator’s per-user credential, so that credential must already be attached. Shared tools sync when the gateway starts and reject manual sync.

Requires gateway.manage.

dome tool catalog sync notion

Reference: dome tool catalog sync

POST /dome.mgmt.v1.Management/SyncMCPServerConnectionTools
Content-Type: application/json

{
  "workspace_id": "{{WORKSPACE_ID}}",
  "connection_id": "{{CONNECTION_ID}}"
}

Add act_as_sub when the administrator’s act-as subject is not their email. Dome resolves the credential by that subject, and the call fails when no credential is stored for it.

Reference: SyncMCPServerConnectionTools

Block

Block a discovered operation to hide it from agents and deny calls to it. A block overrides any rule that would otherwise permit the operation. A blocked operation drops out of the catalog listing, so confirming a block means asking for blocked entries as well.

Requires gateway.manage.

CLI
MCP
Agent

dome tool catalog block notion delete_page \
  --message "Use archive_page instead"

Reference: dome tool catalog block

Tool: dome_tool_block

{
  "connection": "notion",
  "tool": "delete_page",
  "message": "Use archive_page instead"
}

Reference: dome_tool_block

Block a discovered tool

Block "delete_page" on the "notion" tool and recommend "archive_page".

Deprecate

Deprecate a discovered operation to keep it callable while directing users to a replacement. The deprecation message appears in the dashboard, and the catalog lists the operation as deprecated.

Requires gateway.manage.

CLI
MCP
Agent

dome tool catalog deprecate notion create_page \
  --message "use create_page_v2"

Reference: dome tool catalog deprecate

Tool: dome_tool_deprecate

{
  "connection": "notion",
  "tool": "create_page",
  "message": "use create_page_v2"
}

Reference: dome_tool_deprecate

Deprecate a discovered tool

Deprecate "create_page" on the "notion" tool and recommend "create_page_v2".

Restore

Restore a discovered operation to make it available again when rules permit. Restoring clears its block or deprecation. When no blocked operations remain, Dome removes the managed denies.

Requires gateway.manage.

CLI
MCP
Agent

dome tool catalog restore notion delete_page

Reference: dome tool catalog restore

Tool: dome_tool_restore

{
  "connection": "notion",
  "tool": "delete_page"
}

Reference: dome_tool_restore

Restore a discovered tool

Restore "delete_page" on the "notion" tool to active.

Attach to a Gateway

Attach a tool to a Gateway to expose its operations through the gateway’s MCP endpoint. Attaching the entire tool also exposes operations discovered later. Membership makes the tool reachable but does not authorize an agent to call it. The agent must allow the Gateway, and rules must permit the call. You can attach a tool when you add it or later from either the tool or Gateway. Refer to Gateways for membership and grants.

Requires gateway.manage.

CLI
MCP
Agent

dome tool gateways add notion prod-tools

The Gateway side of the same membership is dome gateway tool-sources add.

Reference: dome tool gateways

Tool: dome_gateway_tool_source_add

{
  "gateway": "prod-tools",
  "connection": "notion"
}

Reference: dome_gateway_tool_source_add

Publish a tool

Add the entire "notion" tool to the "prod-tools" Gateway.

Verify discovery

Call tools/list on the Gateway endpoint with an agent’s API key. The response applies Gateway membership and rules, so it shows what that one agent can use. The stored catalog in List catalog applies neither check.

curl -X POST "https://{{GATEWAY_HOST}}/gateways/{{GATEWAY_ID}}/mcp" \
  -H "Authorization: Bearer {{DOME_AGENT_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

If an operation is missing, check the tool’s health, catalog status, Gateway membership, the agent’s allowed resources, and rules.

Manage OAuth

With shared OAuth, an administrator completes consent once after configuring the OAuth client. With per-user OAuth, each end user completes consent on their first call.

Connect OAuth

Connect OAuth to begin the admin consent flow. The response includes a one-shot URL valid for about ten minutes. Open it and complete consent at the upstream authorization server. Dome stores the resulting OAuth tokens. On a shared tool, those tokens serve every call. On a per-user tool, the flow attaches the calling administrator’s own credential, which Sync catalog then reads to discover operations before agent traffic starts. End users still complete their own consent on their first call.

Requires gateway.manage. The tool must use auth_method=oauth.

CLI
MCP
API
Agent

dome tool oauth-connect notion

The CLI and the MCP tool accept shared tools only. To attach an administrator’s per-user credential, call the API with that administrator’s act-as subject.

Reference: dome tool oauth-connect

Tool: dome_tool_oauth_connect

{
  "name": "notion"
}

Reference: dome_tool_oauth_connect

POST /dome.mgmt.v1.Management/BeginMCPServerOAuthConnect
Content-Type: application/json

{
  "workspace_id": "{{WORKSPACE_ID}}",
  "connection_id": "{{CONNECTION_ID}}"
}

On a per-user tool, add act_as_sub to name the administrator whose credential this flow attaches. It defaults to the calling administrator’s email, and it is required when the workspace’s act-as verifier issues opaque subjects.

Reference: BeginMCPServerOAuthConnect

Connect shared OAuth

Start shared OAuth consent for the "notion" tool.

Disconnect OAuth

Disconnect shared OAuth to revoke its stored tokens. The OAuth client configuration remains, so you can reconnect without configuring the client again. Disconnecting an already disconnected tool has no effect.

Requires gateway.manage.

CLI
MCP
API
Agent

dome tool oauth-disconnect notion

Reference: dome tool oauth-disconnect

Tool: dome_tool_oauth_disconnect

{
  "name": "notion"
}

Reference: dome_tool_oauth_disconnect

POST /dome.mgmt.v1.Management/DisconnectMCPServerOAuth
Content-Type: application/json

{
  "workspace_id": "{{WORKSPACE_ID}}",
  "connection_id": "{{CONNECTION_ID}}"
}

Reference: DisconnectMCPServerOAuth

Disconnect shared OAuth

Disconnect shared OAuth credentials for the "notion" tool.

Manage egress headers

You can add or remove individual headers without replacing the full list. These operations are available only through the CLI. MCP and API callers change headers through Update tool, which replaces the whole list.

List headers

Retrieve the outbound headers configured on a tool.

Requires gateway.view.

dome tool header list notion

Reference: dome tool header list

Add headers

Add one or more outbound headers without replacing the headers already configured on a tool.

Requires gateway.manage.

dome tool header add crm --header-actas X-Verified-User

You can combine literal, secret, and act-as header flags in one call.

Reference: dome tool header add

Remove headers

Remove outbound headers by name from a tool.

Requires gateway.manage.

dome tool header remove crm --name X-Verified-User

Reference: dome tool header remove

Next steps

Tools concept for how connections and catalogs work and Tools reference for auth methods and catalog statuses
Register agents and allow the resources they need
Manage Gateway membership and grants in Gateways
Authenticate and route runtime traffic in Develop

​Overview

​Upstream authentication

​Egress headers

​Discovered tools

​Requirements

​Permissions

​Add tool

​Update tool

​Change upstream authentication

​Shared API key

​Shared OAuth

​Per-user credentials

​Change egress headers

​Get tool

​List tools

​Remove tool

​Manage discovered tools

​List catalog

​Sync catalog

​Block

​Deprecate

​Restore

​Attach to a Gateway

​Verify discovery

​Manage OAuth

​Connect OAuth

​Disconnect OAuth

​Manage egress headers

​List headers

​Add headers

​Remove headers

​Next steps

Overview

Upstream authentication

Egress headers

Discovered tools

Requirements

Permissions

Add tool

Update tool

Change upstream authentication

Shared API key

Shared OAuth

Per-user credentials

Change egress headers

Get tool

List tools

Remove tool

Manage discovered tools

List catalog

Sync catalog

Block

Deprecate

Restore

Attach to a Gateway

Verify discovery

Manage OAuth

Connect OAuth

Disconnect OAuth

Manage egress headers

List headers

Add headers

Remove headers

Next steps