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 DigitalEmployeeConfiguration objects with specific key patterns:

DigitalEmployeeConfiguration(
    key="<MCP_NAME>_ALLOWED_TOOLS",
    value="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 os
from dotenv import load_dotenv
from digital_employee_core import (
    DigitalEmployee,
    DigitalEmployeeConfiguration,
    DigitalEmployeeIdentity,
    DigitalEmployeeJob,
)
from digital_employee_core.connectors.mcps import google_calendar_mcp, google_mail_mcp

load_dotenv()

Step 2: Create Identity

job = DigitalEmployeeJob(
    title="Email Assistant",
    description="Helps manage emails and calendars",
    instruction="You are an email assistant that helps users manage their emails efficiently.",
)

identity = DigitalEmployeeIdentity(
    name="Email Bot",
    email="[e-mail]",
    job=job,
)

Step 3: Configure MCP URLs and Allowed Tools

configurations = [
    # MCP URLs
    DigitalEmployeeConfiguration(
        key="GOOGLE_MAIL_MCP_URL",
        value=os.getenv("GOOGLE_MAIL_MCP_URL", ""),
    ),
    DigitalEmployeeConfiguration(
        key="GOOGLE_MCP_X_API_KEY",
        value=os.getenv("GOOGLE_MCP_X_API_KEY", ""),
    ),
    # Allowed tools - comma-separated strings
    DigitalEmployeeConfiguration(
        key="GOOGLE_MAIL_MCP_ALLOWED_TOOLS",
        value="google_mail_send_email,google_mail_get_email_details,google_mail_list_emails",
    ),
]

Note: Replace the example values above with your actual configuration:

• GOOGLE_MAIL_MCP_URL: Your MCP server endpoints

• GOOGLE_MCP_X_API_KEY: Your actual API key (consider using environment variables)

Step 4: Create and Deploy the Digital Employee

# Create digital employee with MCPs
mcps = [google_mail_mcp]

digital_employee = DigitalEmployee(
    identity=identity,
    mcps=mcps,
    configurations=configurations,
)

# Deploy applies the configurations
digital_employee.deploy()

Step 5 (Optional): Verify Configuration

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

mail_mcp_config = digital_employee.agent.mcp_configs.get(google_mail_mcp.name).get("config")
print(f"Mail MCP allowed_tools in config: {mail_mcp_config.get('allowed_tools')}")
# Output: ['google_mail_send_email', 'google_mail_read_email', 'google_mail_search']

Step 6: Run the Digital Employee

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

# The Digital Employee will only be able to use the allowed tools
response = digital_employee.run(
    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://api.bosa.id/docs.

Common Use Cases

Restricting Email Operations

Only allow reading and searching emails, but not sending:

DigitalEmployeeConfiguration(
    key="GOOGLE_MAIL_MCP_ALLOWED_TOOLS",
    value="google_mail_get_email_details,google_mail_list_emails",
)

Read-Only Calendar Access

Only allow listing events, but not creating or modifying:

DigitalEmployeeConfiguration(
    key="GOOGLE_CALENDAR_MCP_ALLOWED_TOOLS",
    value="google_calendar_events_list",
)

Multiple Tool Permissions

Grant access to multiple related tools:

DigitalEmployeeConfiguration(
    key="GOOGLE_MAIL_MCP_ALLOWED_TOOLS",
    value="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
DigitalEmployeeConfiguration(
    key="GOOGLE_MAIL_MCP_ALLOWED_TOOLS",
    value="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
DigitalEmployeeConfiguration(
    key="GOOGLE_MAIL_MCP_ALLOWED_TOOLS",
    value="google_mail_get_email_details,google_mail_list_emails",
)

3. Use Environment Variables for Sensitive Data

Store API keys and URLs in environment variables:

import os

DigitalEmployeeConfiguration(
    key="GOOGLE_MCP_X_API_KEY",
    value=os.getenv("GOOGLE_MCP_API_KEY"),
)

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.