List Servers Tool

Overview

The enkrypt_list_all_servers tool retrieves comprehensive information about all MCP servers configured in your gateway, including their tools, configuration status, and discovery requirements.

This is typically the first tool you’ll use when working with the gateway.

Tool Signature

async def enkrypt_list_all_servers(
    ctx: Context,
    discover_tools: bool = True
) -> dict

Parameters

Context

required

MCP context (automatically provided by the client)

bool

default:"true"

Whether to automatically discover tools for servers that need it.

true: Discovers and caches tools for all servers
false: Returns server list without tool discovery

Return Value

Returns a dictionary containing:

string

required

Operation status: "success" or "error"

object

required

Dictionary of server configurations keyed by server name

array

List of server names that require tool discovery

array

List of server names where discovery failed (only when discover_tools=true)

array

List of server names where discovery succeeded (only when discover_tools=true)

Usage Examples

Basic Usage

User: List all available servers

Claude: I'll list all available MCP servers for you.
[Uses enkrypt_list_all_servers tool]

I found 3 servers configured:
1. github - GitHub integration
2. weather - Weather data provider  
3. echo_server - Test echo server

from mcp import ClientSession

async with ClientSession(...) as session:
    result = await session.call_tool(
        "enkrypt_list_all_servers",
        arguments={"discover_tools": True}
    )
    
    servers = result["available_servers"]
    print(f"Found {len(servers)} servers")

Without Tool Discovery

If you want to list servers quickly without discovering their tools:

List all servers without discovering tools

This will call enkrypt_list_all_servers with discover_tools=false, returning server information faster.

Response Structure

Success Response

{
  "status": "success",
  "message": "Tools discovery tried for all servers",
  "discovery_failed_servers": [],
  "discovery_success_servers": ["github", "weather", "echo_server"],
  "available_servers": {
    "github": {
      "server_name": "github",
      "description": "GitHub MCP Server",
      "config": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-github"]
      },
      "tools": {
        "create_issue": {
          "name": "create_issue",
          "description": "Create a new issue in a repository",
          "inputSchema": {
            "type": "object",
            "properties": {
              "repo": {"type": "string"},
              "title": {"type": "string"},
              "body": {"type": "string"}
            }
          }
        }
      },
      "input_guardrails_policy": {
        "enabled": true,
        "policy_name": "Sample Airline Guardrail"
      },
      "output_guardrails_policy": {
        "enabled": true,
        "policy_name": "Sample Airline Guardrail"
      }
    }
  }
}

{
  "status": "success",
  "available_servers": {
    "github": {
      "server_name": "github",
      "description": "GitHub MCP Server",
      "config": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-github"]
      },
      "tools": {}
    }
  },
  "servers_needing_discovery": ["github", "weather", "echo_server"]
}

Error Response

{
  "status": "error",
  "error": "No MCP config found. Please check your credentials.",
  "error_code": "CONFIG_MISSING_REQUIRED",
  "correlation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Server Object Structure

Each server in available_servers contains:

string

Unique identifier for the server

string

Human-readable description of the server

object

Server execution configuration

Show config properties

string

Command to execute (e.g., "python", "npx", "docker")

array

Command-line arguments

object

Environment variables (sensitive values are masked)

object

Dictionary of available tools (empty if not discovered yet)

object

Input guardrail configuration for this server

object

Output guardrail configuration for this server

Implementation Details

Service Location

Implemented in: src/secure_mcp_gateway/services/server/server_listing_service.py:38

Authentication

The tool automatically:

Extracts gateway credentials from the request context
Validates credentials against the local or remote configuration
Retrieves the MCP configuration for the authenticated user/project

Caching

Server information is cached to improve performance:

Cache Key: Based on gateway key, project ID, user ID, and config ID
Cache Duration: 24 hours (gateway config) + 4 hours (tools)
Cache Type: Local (in-memory) or External (Redis/KeyDB)

Parallel Processing

When discover_tools=true, the gateway:

Phase 1: Validates all servers in parallel
Phase 2: Separates servers with pre-configured tools from those needing discovery
Phase 3: Runs tool validation and discovery in parallel

This parallel approach significantly reduces response time for multiple servers.

Tool Annotations

annotations={
    "title": "List Available Servers",
    "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

Verify Server Configuration

List all servers and show their configuration

Use this to verify that servers are properly configured and accessible.

Check Available Tools

What tools are available across all servers?

Gets a comprehensive view of all capabilities.

Troubleshoot Discovery Issues

List servers without discovering tools

Quickly check server connectivity without waiting for tool discovery.

Initial Setup Verification

After setting up the gateway, use this tool to confirm all servers are accessible:

Show me all configured servers and whether they're working

Error Handling

Common errors and solutions:

CONFIG_MISSING_REQUIRED

Error: No MCP config foundSolution: Verify that:

Gateway key is correct in your MCP client config
~/.enkrypt/enkrypt_mcp_config.json exists
Project ID and User ID match the configuration

AUTH_INVALID_CREDENTIALS

Error: Authentication failedSolution: Check your gateway credentials in the MCP client configuration

DISCOVERY_FAILED

Error: Tool discovery failed for some serversSolution:

Check server command and arguments
Verify required dependencies are installed
Review server logs for specific errors
Try discover_tools=false to see which servers are accessible

Performance Tips

Use Caching

Tools are cached for 4 hours by default. Subsequent calls return cached results instantly.

Skip Discovery

Set discover_tools=false for faster responses when you only need server names.

Parallel Execution

The gateway automatically discovers tools from multiple servers in parallel.

Monitor Metrics

Use enkrypt_get_timeout_metrics to identify slow servers.

Get Server Info

Get detailed information about a specific server

Discover Tools

Force re-discovery of tools for a server

Cache Status

View cache status for discovered tools

Execute Tools

Run tools from discovered servers

REST API

CLI Reference

Gateway Tools

Plugin API

Overview

Tool Signature

Parameters

Return Value

Usage Examples

Basic Usage

Without Tool Discovery

Response Structure

Success Response

Error Response

Server Object Structure

Implementation Details

Service Location

Authentication

Caching

Parallel Processing

Tool Annotations

Common Use Cases

Error Handling

Performance Tips

Use Caching

Skip Discovery

Parallel Execution

Monitor Metrics

Get Server Info

Discover Tools

Cache Status

Execute Tools

​Overview

​Tool Signature

​Parameters

​Return Value

​Usage Examples

​Basic Usage

​Without Tool Discovery

​Response Structure

​Success Response

​Error Response

​Server Object Structure

​Implementation Details

​Service Location

​Authentication

​Caching

​Parallel Processing

​Tool Annotations

​Common Use Cases

​Error Handling

​Performance Tips

Use Caching

Skip Discovery

Parallel Execution

Monitor Metrics

​Related Tools

Get Server Info

Discover Tools

Cache Status

Execute Tools

Overview

Tool Signature

Parameters

Return Value

Usage Examples

Basic Usage

Without Tool Discovery

Response Structure

Success Response

Error Response

Server Object Structure

Implementation Details

Service Location

Authentication

Caching

Parallel Processing

Tool Annotations

Common Use Cases

Error Handling

Performance Tips

Related Tools