Tools

A tool is an MCP server (or related backend) you attach so agents can call it without holding upstream secrets. Dome authorizes each call, injects the credential, and audits the result.

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:

1. Add a tool for the upstream MCP server.
2. If the server requires credentials, configure upstream authentication.
3. Attach the tool to a Gateway to make it available through a Dome endpoint.
4. Allow the Gateway on the agent.
5. 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.

1. The authentication method defines how the server verifies a request.

2. 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.

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 forwards the end-user assertion that the workspace admitted. The Gateway does not apply a second strength ranking at egress: configure the accepted methods or required provider in the workspace Act-As policy. The call fails closed when no raw assertion is available, including bound and interactive session identity. 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.

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.

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.

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

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

POST /v1/tools
Content-Type: application/json

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

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.

Install a catalog adapter

Install a Dome-managed REST adapter — Slack, GitHub, Notion, and other bundled integrations — as a workspace tool. The catalog hides the REST→MCP mapping: pick a slug, name the connection, and supply the upstream credential.

Use catalog install when an adapter exists for your upstream. Direct creation with protocol=rest is rejected; the install RPC is the only path that produces a catalog-backed connection. For upstreams that already speak MCP, use Add tool with streamable-http or stdio.

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

{
  "workspace_id": "{{WORKSPACE_ID}}",
  "slug": "github",
  "name": "github-prod",
  "secret_values": { "Authorization": "Bearer {{GITHUB_TOKEN}}" },
  "credential_type": "shared",
  "tool_filter": ["create_issue", "list_pull_requests"]
}

Catalog adapter lifecycle

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.

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

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

PATCH /v1/tools/{{CONNECTION_ID}}
Content-Type: application/json

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

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.

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

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

PATCH /v1/tools/{{CONNECTION_ID}}
Content-Type: application/json

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

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.

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

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

PATCH /v1/tools/{{CONNECTION_ID}}
Content-Type: application/json

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

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.

dome tools get notion

{
  "name": "notion"
}

GET /v1/tools/{{CONNECTION_ID}}?workspace_id={{WORKSPACE_ID}}

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.

dome tools list

{}

GET /v1/tools?workspace_id={{WORKSPACE_ID}}

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.

dome tools remove notion

{
  "name": "notion"
}

DELETE /v1/tools/{{CONNECTION_ID}}?workspace_id={{WORKSPACE_ID}}

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.

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

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

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.

dome tools catalog sync notion

POST /v1/tools/{{CONNECTION_ID}}/catalog/sync
Content-Type: application/json

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

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.

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

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

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.

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

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

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.

dome tools catalog restore notion delete_page

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

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.

dome tools gateways add notion prod-tools

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

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.

dome tools oauth-connect notion

{
  "name": "notion"
}

POST /v1/tools/{{CONNECTION_ID}}/oauth/connect
Content-Type: application/json

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

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.

dome tools oauth-disconnect notion

{
  "name": "notion"
}

POST /v1/tools/{{CONNECTION_ID}}/oauth/disconnect
Content-Type: application/json

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

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.

dome tools header list notion

Add headers

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

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

Remove headers

Remove outbound headers by name from a tool.

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

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