Discover Tools

Overview

The enkrypt_discover_all_tools tool discovers available tools from a specific MCP server or all servers, validates them through security guardrails, and caches the results for future use.

Tool discovery happens automatically when you use enkrypt_list_all_servers with discover_tools=true. Use this tool to force re-discovery or troubleshoot specific servers.

Tool Signature

async def enkrypt_discover_all_tools(
    ctx: Context,
    server_name: str = None
) -> dict

Parameters

Context

required

MCP context (automatically provided by the client)

str

default:"None"

Name of the server to discover tools for.

None or "null": Discovers tools for all servers
Specific name (e.g., "github"): Discovers tools for that server only

Return Value

string

required

Operation status: "success" or "error"

string

Human-readable description of the result

object

Dictionary or list of discovered tools (single server mode)

object

Dictionary of servers with their tools (all servers mode)

string

Where tools came from: "config", "cache", or "discovery"

array

List of tools blocked by security guardrails

integer

Number of tools blocked

Usage Examples

Discover Tools for a Specific Server

User: Discover all tools for the github server

Claude: I'll discover what tools are available from the GitHub server.
[Uses enkrypt_discover_all_tools with server_name="github"]

Found 8 tools:
- create_issue
- list_issues
- create_pull_request
- search_repositories
...

result = await session.call_tool(
    "enkrypt_discover_all_tools",
    arguments={"server_name": "github"}
)

tools = result["tools"]
print(f"Discovered {len(tools)} tools from cache={result['source']=='cache'}")

Discover Tools for All Servers

Discover tools for all servers

This discovers and caches tools from every configured server.

Force Re-discovery

To bypass cache and force fresh discovery:

Clear cache for github server, then discover its tools

This uses enkrypt_clear_cache followed by enkrypt_discover_all_tools.

Response Structure

Single Server Discovery

{
  "status": "success",
  "server_name": "github",
  "message": "Tools retrieved from cache for github",
  "source": "cache",
  "tools": {
    "tools": [
      {
        "name": "create_issue",
        "description": "Create a new issue in a repository",
        "inputSchema": {
          "type": "object",
          "properties": {
            "repo": {"type": "string", "description": "Repository name"},
            "title": {"type": "string"},
            "body": {"type": "string"}
          },
          "required": ["repo", "title"]
        }
      }
    ]
  },
  "blocked_tools": [],
  "blocked_count": 0,
  "blocked_reasons": []
}

{
  "status": "success",
  "server_name": "weather",
  "message": "Tools already defined in config for weather",
  "source": "config",
  "tools": {
    "get_weather": {
      "name": "get_weather",
      "description": "Get current weather for a location",
      "inputSchema": {
        "type": "object",
        "properties": {
          "location": {"type": "string"}
        }
      }
    }
  },
  "blocked_tools": [],
  "blocked_count": 0
}

{
  "status": "success",
  "server_name": "echo_server",
  "message": "Tools discovered for echo_server",
  "source": "discovery",
  "tools": [
    {
      "name": "echo",
      "description": "Echo back the input",
      "inputSchema": {
        "type": "object",
        "properties": {
          "message": {"type": "string"}
        }
      }
    }
  ],
  "blocked_tools": [],
  "blocked_count": 0
}

All Servers Discovery

{
  "status": "success",
  "message": "Tools discovery tried for all servers",
  "discovery_failed_servers": [],
  "discovery_success_servers": ["github", "weather", "echo_server"],
  "available_servers": {
    "github": {
      "status": "success",
      "tools": {...},
      "source": "discovery"
    },
    "weather": {
      "status": "success",
      "tools": {...},
      "source": "config"
    }
  }
}

Tool Sources

Tools can come from three sources:

config - Pre-configured Tools

Tools are explicitly defined in the gateway configuration file under the tools property for the server.Advantages:

Instant availability
No discovery overhead
Can restrict which tools are accessible

Example:

{
  "server_name": "weather",
  "tools": {
    "get_weather": {...}
  }
}

cache - Cached Discovery

Tools were previously discovered and cached. Default cache duration is 4 hours.Advantages:

Fast retrieval
No server connection needed
Automatic refresh after expiration

Note: Use enkrypt_get_cache_status to check cache expiration.

discovery - Fresh Discovery

Tools are dynamically discovered by connecting to the server and requesting its tool list.Advantages:

Always up-to-date
Discovers new tools automatically
Validates tool availability

Note: Results are automatically cached for future use.

Security Validation

Tool Guardrails

If tool guardrails are enabled for a server, discovered tools are validated before being made available:

Example: Blocked Tools

{
  "status": "success",
  "server_name": "filesystem",
  "tools": {...},
  "blocked_tools": [
    {
      "name": "delete_system_file",
      "reasons": [
        "Tool allows destructive file operations",
        "Potential security risk detected"
      ]
    }
  ],
  "blocked_count": 1,
  "blocked_reasons": [
    "Tool allows destructive file operations",
    "Potential security risk detected"
  ]
}

Blocked tools will not be available for execution via enkrypt_secure_call_tools.

Server Validation

Before tool discovery, the server itself is validated:

Example: Blocked Server

{
  "status": "error",
  "server_name": "malicious_server",
  "message": "Server 'malicious_server' blocked by security guardrails: Suspicious command execution pattern detected",
  "blocked": true,
  "violations": [
    "Suspicious command execution pattern detected"
  ]
}

Implementation Details

Service Location

Implemented in: src/secure_mcp_gateway/services/discovery/discovery_service.py:52

Three-Phase Parallel Discovery

When discovering tools for all servers, the gateway uses an optimized three-phase approach:

Phase 1: Server Validation

All servers are validated in parallel against security guardrails:

# Validates:
- Server configuration
- Command and arguments
- Security policies
- Server registration (if enabled)

Phase 2: Separation

Servers are separated into two groups:

Servers with config tools: Have pre-defined tools in configuration
Servers needing discovery: Require dynamic tool discovery

Phase 3: Parallel Execution

Both groups are processed in parallel:

Config tools: Validated against guardrails
Discovery tools: Discovered and validated

This parallel approach can reduce discovery time from 30+ seconds to under 5 seconds for multiple servers.

Caching Strategy

Discovered tools are cached using a composite key:

cache_key = f"{gateway_key}_{project_id}_{user_id}_{mcp_config_id}_{server_name}"

Cache duration: 4 hours (configurable)
Cache invalidation: Automatic expiration or manual via enkrypt_clear_cache
Cache types: Local (in-memory) or External (Redis/KeyDB)

Tool Annotations

annotations={
    "title": "Discover Server Tools",
    "readOnlyHint": True,      # Does not modify state
    "destructiveHint": False,  # Not destructive
    "idempotentHint": True,    # Can be called multiple times
    "openWorldHint": False     # No external API calls
}

Common Use Cases

Initial Server Setup

After adding a new server to your configuration:

Discover tools for the new weather server

Verify Tool Updates

When a server is updated with new tools:

Clear cache and discover tools for github server

Troubleshoot Missing Tools

When expected tools aren’t showing up:

Force discovery of tools for the database server

Check Security Blocks

To see if any tools are being blocked:

Discover tools for the filesystem server and show any blocked tools

Error Handling

DISCOVERY_SERVER_UNAVAILABLE

Error: Server not availableCause: Server name doesn’t exist in configurationSolution: Use enkrypt_list_all_servers to see available servers

DISCOVERY_FAILED

Error: Tool discovery failedCauses:

Server command/arguments incorrect
Required dependencies not installed
Server not responding
Network connectivity issues

Solution: Check server configuration and logs

GUARDRAIL_VALIDATION_FAILED

Error: Server blocked by security guardrailsCause: Server configuration violates security policiesSolution: Review server configuration and guardrail policies

Timeout Errors

Error: Discovery operation timed outCause: Server taking too long to respondSolution:

Check server performance
Adjust timeout settings in gateway config
Use enkrypt_get_timeout_metrics to diagnose

Performance Optimization

Use Cache

Don’t force re-discovery unless necessary. Cached tools are returned instantly.

Discover in Background

Use enkrypt_list_all_servers with discover_tools=true to discover all tools at once.

Pre-configure Tools

Define tools in your config file to skip discovery entirely.

External Cache

Use Redis/KeyDB for shared cache across multiple gateway instances.

List Servers

See all configured servers before discovery

Execute Tools

Use discovered tools securely

Cache Status

Check cache status and expiration

Clear Cache

Force re-discovery by clearing cache

REST API

CLI Reference

Gateway Tools

Plugin API

Overview

Tool Signature

Parameters

Return Value

Usage Examples

Discover Tools for a Specific Server

Discover Tools for All Servers

Force Re-discovery

Response Structure

Single Server Discovery

All Servers Discovery

Tool Sources

Security Validation

Tool Guardrails

Server Validation

Implementation Details

Service Location

Three-Phase Parallel Discovery

Phase 1: Server Validation

Phase 2: Separation

Phase 3: Parallel Execution

Caching Strategy

Tool Annotations

Common Use Cases

Error Handling

Performance Optimization

Use Cache

Discover in Background

Pre-configure Tools

External Cache

List Servers

Execute Tools

Cache Status

Clear Cache

​Overview

​Tool Signature

​Parameters

​Return Value

​Usage Examples

​Discover Tools for a Specific Server

​Discover Tools for All Servers

​Force Re-discovery

​Response Structure

​Single Server Discovery

​All Servers Discovery

​Tool Sources

​Security Validation

​Tool Guardrails

​Server Validation

​Implementation Details

​Service Location

​Three-Phase Parallel Discovery

​Phase 1: Server Validation

​Phase 2: Separation

​Phase 3: Parallel Execution

​Caching Strategy

​Tool Annotations

​Common Use Cases

​Error Handling

​Performance Optimization

Use Cache

Discover in Background

Pre-configure Tools

External Cache

​Related Tools

List Servers

Execute Tools

Cache Status

Clear Cache

Overview

Tool Signature

Parameters

Return Value

Usage Examples

Discover Tools for a Specific Server

Discover Tools for All Servers

Force Re-discovery

Response Structure

Single Server Discovery

All Servers Discovery

Tool Sources

Security Validation

Tool Guardrails

Server Validation

Implementation Details

Service Location

Three-Phase Parallel Discovery

Phase 1: Server Validation

Phase 2: Separation

Phase 3: Parallel Execution

Caching Strategy

Tool Annotations

Common Use Cases

Error Handling

Performance Optimization

Related Tools