Execute Tools Securely

Overview

The enkrypt_secure_call_tools tool provides secure batch execution of MCP server tools with comprehensive guardrail checks, PII handling, and detailed response tracking.

This is the only recommended way to execute tools from MCP servers through the gateway. Direct server access bypasses security protections.

Tool Signature

async def enkrypt_secure_call_tools(
    ctx: Context,
    server_name: str,
    tool_calls: list = []
) -> dict

Parameters

Context

required

MCP context (automatically provided by the client)

str

required

Name of the server containing the tools to execute

list

default:"[]"

List of tool calls to execute. Each item should be an object with:

Show tool_call object structure

string

required

Name of the tool to call

object

required

Arguments to pass to the tool

Special behavior:

Empty list []: Triggers tool discovery only (no execution)
Single item: Executes one tool
Multiple items: Executes all tools in sequence within the same session

Important: If you need to execute multiple tools, pass them all in a single list. Multiple separate calls will create new sessions each time, which may fail or be inefficient.

Return Value

string

required

Overall status: "success", "error", "blocked_input", or "blocked_output"

string

Human-readable description of the execution result

array

Array of individual tool execution results

object

Summary statistics about the batch execution

Show execution_summary properties

integer

Total number of tool calls requested

integer

Number of successful executions

integer

Number of failed executions

integer

Number of calls blocked by input guardrails

integer

Number of calls blocked by output guardrails

Usage Examples

Execute a Single Tool

User: Create an issue in my repository titled "Bug in login page"

Claude: I'll create an issue in your GitHub repository.
[Uses enkrypt_secure_call_tools]

Success! Created issue #42 in your repository.

result = await session.call_tool(
    "enkrypt_secure_call_tools",
    arguments={
        "server_name": "github",
        "tool_calls": [
            {
                "name": "create_issue",
                "args": {
                    "repo": "myuser/myrepo",
                    "title": "Bug in login page",
                    "body": "Login fails with email addresses"
                }
            }
        ]
    }
)

if result["status"] == "success":
    print(f"Issue created: {result['results'][0]['response']}")

Execute Multiple Tools in Sequence

User: Create a new repository called "test-repo" and add a README file to it

Claude: I'll create the repository and add a README.
[Uses enkrypt_secure_call_tools with 2 tool calls]

1. Created repository "test-repo"
2. Added README.md file

Both operations completed successfully!

result = await session.call_tool(
    "enkrypt_secure_call_tools",
    arguments={
        "server_name": "github",
        "tool_calls": [
            {
                "name": "create_repository",
                "args": {
                    "name": "test-repo",
                    "description": "Test repository"
                }
            },
            {
                "name": "create_file",
                "args": {
                    "repo": "myuser/test-repo",
                    "path": "README.md",
                    "content": "# Test Repository"
                }
            }
        ]
    }
)

for i, result in enumerate(result["results"]):
    print(f"Call {i+1}: {result['status']}")

Discovery Mode (No Execution)

To discover tools without executing them:

result = await session.call_tool(
    "enkrypt_secure_call_tools",
    arguments={
        "server_name": "github",
        "tool_calls": []  # Empty list triggers discovery
    }
)

# Returns: {"status": "success", "tools": {...}}

Response Structure

Successful Execution

{
  "status": "success",
  "message": "Batch execution completed: 2 successful, 0 failed, 0 blocked (input), 0 blocked (output)",
  "results": [
    {
      "status": "success",
      "response": "Issue #42 created successfully",
      "enkrypt_mcp_data": {
        "call_index": 0,
        "server_name": "github",
        "tool_name": "create_issue",
        "args": {...}
      },
      "input_guardrail_response": {
        "is_safe": true,
        "processing_time_ms": 45
      },
      "output_guardrail_response": {
        "is_safe": true,
        "processing_time_ms": 38
      }
    }
  ],
  "execution_summary": {
    "total_calls": 2,
    "successful_calls": 2,
    "failed_calls": 0,
    "blocked_input_calls": 0,
    "blocked_output_calls": 0,
    "input_guardrails_enabled": true,
    "output_guardrails_enabled": true
  }
}

Blocked by Input Guardrails

{
  "status": "error",
  "message": "Batch execution failed: 0 successful, 0 failed, 1 blocked (input)",
  "results": [
    {
      "status": "blocked_input",
      "message": "Request blocked due to input guardrail violations: policy_violation, nsfw_content",
      "response": "",
      "enkrypt_mcp_data": {
        "call_index": 0,
        "server_name": "github",
        "tool_name": "create_issue",
        "args": {...}
      },
      "input_guardrail_response": {
        "is_safe": false,
        "violations": [
          {
            "type": "policy_violation",
            "severity": "high",
            "message": "Content violates acceptable use policy",
            "action": "block"
          },
          {
            "type": "nsfw_content",
            "severity": "high",
            "message": "NSFW content detected",
            "action": "block"
          }
        ],
        "processing_time_ms": 52
      }
    }
  ]
}

Blocked by Output Guardrails

{
  "status": "error",
  "message": "Batch execution failed: 0 successful, 0 failed, 0 blocked (input), 1 blocked (output)",
  "results": [
    {
      "status": "blocked_output",
      "message": "Response blocked due to output guardrail violations: policy_violation",
      "response": "[Response blocked by guardrails]",
      "enkrypt_mcp_data": {...},
      "output_guardrail_response": {
        "is_safe": false,
        "violations": [
          {
            "type": "policy_violation",
            "severity": "high",
            "message": "Response contains policy-violating content"
          }
        ],
        "processing_time_ms": 67
      }
    }
  ]
}

Security Features

Input Guardrails

Before executing tools, the gateway validates input arguments:

PII Detection & Redaction

Automatically detects and redacts personally identifiable information:

Input: {"email": "john.doe@example.com", "ssn": "123-45-6789"}
Redacted: {"email": "[EMAIL_REDACTED]", "ssn": "[SSN_REDACTED]"}

The original PII is stored securely and restored in the response.

Content Safety

Checks for:

NSFW content
Toxic language
Hate speech
Profanity

Injection Prevention

Detects and blocks:

SQL injection attempts
Command injection
Prompt injection
XSS attacks

Policy Enforcement

Validates against custom organizational policies:

Topic restrictions
Keyword blocking
Business rules

Output Guardrails

After execution, responses are validated:

All Input Checks

All input guardrail checks are also applied to outputs.

Relevancy Validation

Ensures the response is relevant to the input:

{
  "relevancy_score": 0.85,
  "threshold": 0.75,
  "is_relevant": true
}

Adherence Checking

Verifies the response follows instructions:

{
  "adherence_score": 0.92,
  "threshold": 0.80,
  "adheres": true
}

Hallucination Detection

Identifies potentially fabricated information in responses.

PII De-anonymization

Automatically restores redacted PII in the response if the output is safe.

Async Guardrails

For improved performance, guardrails can run asynchronously:

Configuration

{
  "common_mcp_gateway_config": {
    "enkrypt_async_input_guardrails_enabled": true,
    "enkrypt_async_output_guardrails_enabled": true
  }
}

When enabled:

Input guardrails and tool execution run in parallel
Response is blocked if guardrails detect violations
Reduces total execution time by ~50%

Implementation Details

Service Location

Implemented in: src/secure_mcp_gateway/services/execution/secure_tool_execution_service.py:64

Execution Flow

Authentication - Validate gateway credentials
Server Lookup - Find server configuration
Tool Discovery - Ensure tools are available (cached or discovered)
Session Creation - Open persistent session to server
For each tool call:
- Input Guardrails - Validate input (if enabled)
- PII Redaction - Redact sensitive data (if enabled)
- Tool Execution - Call the actual tool
- Output Guardrails - Validate output (if enabled)
- PII Restoration - Restore redacted data (if safe)
Session Cleanup - Close server connection
Summary - Return execution results

Session Management

All tool calls in a single request share the same server session. This is critical for stateful operations.

# Single session for all calls
async with session:
    result1 = await call_tool("create_repo", ...)
    result2 = await call_tool("add_file", ...)  # Same session

Error Handling

Execution stops on first error or block:

tool_calls = [
    {"name": "tool1", "args": {...}},  # ✓ Executes
    {"name": "tool2", "args": {...}},  # ✗ Blocked by guardrails
    {"name": "tool3", "args": {...}}   # ⊘ Never executed
]

Tool Annotations

annotations={
    "title": "Securely Call Tools",
    "readOnlyHint": False,     # May modify state
    "destructiveHint": True,   # Can be destructive
    "idempotentHint": False,   # Results may vary
    "openWorldHint": True      # Makes external API calls
}

Performance Optimization

Batch Calls

Execute multiple tools in one request to reuse the session.

Async Guardrails

Enable async guardrails to run checks in parallel with execution.

Cache Tools

Ensure tools are discovered and cached before execution.

Timeout Tuning

Adjust timeout settings for slow tools via gateway config.

Common Use Cases

Safe API Calls

Execute external API calls with automatic PII protection:

Send an email to john.doe@example.com with the meeting notes

The gateway redacts the email before sending to the server.

Multi-step Workflows

Execute complex workflows in a single session:

Create a new database
Create tables
Insert sample data

Content Moderation

Automatically filter inappropriate content:

Post this message to the forum: [user input]

Toxic or NSFW content is blocked before posting.

Policy Enforcement

Enforce organizational policies on tool usage:

Delete all files in the /important directory

Policy violations are blocked automatically.

Error Codes

TOOL_NOT_FOUND

Error: Tool not found for this serverSolution: Use enkrypt_discover_all_tools to see available tools

TOOL_EXECUTION_FAILED

Error: Tool execution failedCauses: Server error, invalid arguments, connectivity issuesSolution: Check tool arguments and server logs

GUARDRAIL_VALIDATION_FAILED

Error: Input/output blocked by guardrailsSolution: Review violation details in the response

AUTH_INVALID_CREDENTIALS

Error: Authentication failedSolution: Verify gateway key configuration

Configuration Reference

Configure guardrails per-server in enkrypt_mcp_config.json:

{
  "server_name": "github",
  "input_guardrails_policy": {
    "enabled": true,
    "policy_name": "Sample Airline Guardrail",
    "additional_config": {
      "pii_redaction": true
    },
    "block": [
      "policy_violation",
      "injection_attack",
      "nsfw_content",
      "toxic_content"
    ]
  },
  "output_guardrails_policy": {
    "enabled": true,
    "policy_name": "Sample Airline Guardrail",
    "additional_config": {
      "relevancy": true,
      "adherence": true,
      "hallucination": true
    },
    "block": [
      "policy_violation",
      "nsfw_content"
    ]
  }
}

List Servers

See available servers to execute tools from

Discover Tools

Find available tools before execution

Timeout Metrics

Monitor execution performance

Guardrails Config

Configure security policies

REST API

CLI Reference

Gateway Tools

Plugin API

Overview

Tool Signature

Parameters

Return Value

Usage Examples

Execute a Single Tool

Execute Multiple Tools in Sequence

Discovery Mode (No Execution)

Response Structure

Successful Execution

Blocked by Input Guardrails

Blocked by Output Guardrails

Security Features

Input Guardrails

Output Guardrails

Async Guardrails

Implementation Details

Service Location

Execution Flow

Session Management

Error Handling

Tool Annotations

Performance Optimization

Batch Calls

Async Guardrails

Cache Tools

Timeout Tuning

Common Use Cases

Error Codes

Configuration Reference

List Servers

Discover Tools

Timeout Metrics

Guardrails Config

​Overview

​Tool Signature

​Parameters

​Return Value

​Usage Examples

​Execute a Single Tool

​Execute Multiple Tools in Sequence

​Discovery Mode (No Execution)

​Response Structure

​Successful Execution

​Blocked by Input Guardrails

​Blocked by Output Guardrails

​Security Features

​Input Guardrails

​Output Guardrails

​Async Guardrails

​Implementation Details

​Service Location

​Execution Flow

​Session Management

​Error Handling

​Tool Annotations

​Performance Optimization

Batch Calls

Async Guardrails

Cache Tools

Timeout Tuning

​Common Use Cases

​Error Codes

​Configuration Reference

​Related Tools

List Servers

Discover Tools

Timeout Metrics

Guardrails Config

Overview

Tool Signature

Parameters

Return Value

Usage Examples

Execute a Single Tool

Execute Multiple Tools in Sequence

Discovery Mode (No Execution)

Response Structure

Successful Execution

Blocked by Input Guardrails

Blocked by Output Guardrails

Security Features

Input Guardrails

Output Guardrails

Async Guardrails

Implementation Details

Service Location

Execution Flow

Session Management

Error Handling

Tool Annotations

Performance Optimization

Common Use Cases

Error Codes

Configuration Reference

Related Tools