MCP Allowed Tools Configuration

Overview

The allowed_tools configuration enables you to restrict which tools a Digital Employee can access from Model Context Protocol (MCP) servers. This is useful for security, cost control, and ensuring your Digital Employee only uses approved functionality.

Key Concepts

What are Allowed Tools?

Allowed tools are a whitelist of specific tool names that an MCP connector is permitted to use. When configured, the Digital Employee will only have access to the specified tools from that MCP, even if the MCP server provides additional capabilities.

Benefits

• Security: Limit access to sensitive operations

• Cost Control: Prevent usage of expensive API calls

• Compliance: Ensure only approved tools are used

• Clarity: Make it explicit which capabilities are available

Configuration

Basic Setup

Allowed tools are configured using add_configs_from_env() with tuples to provide default values:

DigitalEmployeeAgentBuilder()
    .add_mcps([google_mail_mcp])
    .add_configs_from_env([
        ("GOOGLE_MAIL_MCP_ALLOWED_TOOLS", "tool1,tool2,tool3")
    ])

Key Pattern

The configuration key follows this pattern:

• <MCP_NAME>_ALLOWED_TOOLS

Where <MCP_NAME> matches the MCP connector's configuration prefix (e.g., GOOGLE_MAIL_MCP, GOOGLE_CALENDAR_MCP).

Value Format

The value is a comma-separated string of tool names that will be automatically converted to a list:

# This string...
value="google_mail_send_email,google_mail_get_email_details,google_mail_list_emails"

# ...is automatically converted to this list:
['google_mail_send_email', 'google_mail_get_email_details', 'google_mail_list_emails']

Complete Example

Step 1: Import Required Components

import asyncio
from dotenv import load_dotenv
from digital_employee_core import (
    DigitalEmployeeAgentBuilder,
    DigitalEmployeeBuilder,
    DigitalEmployeePipelineBuilder,
)
from digital_employee_core.connectors.mcps import google_mail_mcp

load_dotenv()

Step 2: Build Digital Employee with Allowed Tools Configuration

# Build digital employee using builder pattern
digital_employee = (
    DigitalEmployeeBuilder()
    .set_name("Email Bot")
    .set_email("[e-mail]")
    .set_job(
        title="Email Assistant",
        description="Helps manage emails and calendars",
        instruction="You are an email assistant that helps users manage their emails efficiently.",
    )
    .set_pipeline(
        DigitalEmployeePipelineBuilder().add_step(
            DigitalEmployeeAgentBuilder()
            .add_mcps([google_mail_mcp])
            .add_configs_from_env(
                [
                    "GOOGLE_MAIL_MCP_URL",
                    "GOOGLE_MCP_X_API_KEY",
                    # Use tuples to provide default values for environment variables
                    (
                        "GOOGLE_MAIL_MCP_ALLOWED_TOOLS",
                        "google_mail_send_email,google_mail_get_email_details,google_mail_list_emails",
                    ),
                ]
            )
        )
    )
    .build()
)

Using Tuples for Default Values:

When using add_configs_from_env(), you can provide tuples (key, default_value) to specify default values for environment variables:

add_configs_from_env([
    "REQUIRED_ENV_VAR",  # Must be set in environment
    ("OPTIONAL_ENV_VAR", "default_value"),  # Uses default if not set
])

This is particularly useful for ALLOWED_TOOLS configurations where you want to provide sensible defaults.

Step 3 (Optional): Verify Configuration

If you want to verify the configuration was applied correctly, you can check the MCP config through the pipeline steps:

# Access the agent from pipeline steps
steps = digital_employee.get_pipeline_steps()
agent = steps[0].component.agent

# Check the Google Mail MCP configuration
print(f"Mail MCP allowed_tools: {agent.mcp_configs.get('digital_employee_google_mail_mcp').get('config').get('allowed_tools')}")
# Output: ['google_mail_send_email', 'google_mail_get_email_details', 'google_mail_list_emails']

Step 4: Run the Digital Employee

Now you can run the Digital Employee and it will only have access to the allowed tools:

response = asyncio.run(
    digital_employee.invoke(message="Read and summarize my latest email")
)
print(response)

In this example:

• The Digital Employee can use google_mail_get_email_details, google_mail_list_emails to find the latest email.

• It cannot use tools like google_mail_delete_email because they weren't in the allowed list.

For the list of tools that are available via GLConnector, please refer to https://connectors.gdplabs.id/docs.

Common Use Cases

Restricting Email Operations

Only allow reading and searching emails, but not sending:

DigitalEmployeeAgentBuilder()
    .add_mcps([google_mail_mcp])
    .add_configs_from_env([
        ("GOOGLE_MAIL_MCP_ALLOWED_TOOLS", "google_mail_get_email_details,google_mail_list_emails"),
    ])

Read-Only Calendar Access

Only allow listing events, but not creating or modifying:

DigitalEmployeeAgentBuilder()
    .add_mcps([google_calendar_mcp])
    .add_configs_from_env([
        ("GOOGLE_CALENDAR_MCP_ALLOWED_TOOLS", "google_calendar_events_list"),
    ])

Multiple Tool Permissions

Grant access to multiple related tools:

DigitalEmployeeAgentBuilder()
    .add_mcps([google_mail_mcp])
    .add_configs_from_env([
        ("GOOGLE_MAIL_MCP_ALLOWED_TOOLS", "google_mail_send_email,google_mail_get_email_details,google_mail_delete_email"),
    ])

Best Practices

1. Principle of Least Privilege

Only grant access to tools that are absolutely necessary for the Digital Employee's job:

# Good: Specific tools for specific job
DigitalEmployeeAgentBuilder()
    .add_mcps([google_mail_mcp])
    .add_configs_from_env([
        ("GOOGLE_MAIL_MCP_ALLOWED_TOOLS", "google_mail_get_email_details,google_mail_list_emails"),
    ])

# Avoid: Granting all available tools without restriction

2. Document Your Tool Choices

Add comments explaining why specific tools are allowed:

# Allow email reading and searching for customer support queries
DigitalEmployeeAgentBuilder()
    .add_mcps([google_mail_mcp])
    .add_configs_from_env([
        ("GOOGLE_MAIL_MCP_ALLOWED_TOOLS", "google_mail_get_email_details,google_mail_list_emails"),
    ])

3. Use Environment Variables for Sensitive Data

Store API keys and URLs in environment variables using add_configs_from_env():

DigitalEmployeeAgentBuilder()
    .add_mcps([google_mail_mcp])
    .add_configs_from_env([
        "GOOGLE_MAIL_MCP_URL",  # Required from environment
        "GOOGLE_MCP_X_API_KEY",  # Required from environment
        ("GOOGLE_MAIL_MCP_ALLOWED_TOOLS", "tool1,tool2"),  # Optional with default
    ])

Troubleshooting

Tools Not Being Restricted

Problem: All tools are still accessible despite configuration.

Solution: Ensure the configuration key matches the MCP's expected pattern:

• Check the MCP connector's documentation for the correct prefix

• Verify the key format: <MCP_PREFIX>_ALLOWED_TOOLS

Tool Names Incorrect

Problem: Tools are not recognized.

Solution: Verify the exact tool names from the MCP server documentation. Tool names are case-sensitive and must match exactly.