Adding Tools

Tools extend your agents’ capabilities beyond conversation. With tools, agents can search the web, read files, call APIs, execute code, and integrate with external services. This guide covers configuring tools in your workspace.

Tools Configuration Structure

Tools are configured in the tools section of your workspace.yml:

tools:
  mcp:
    # Global MCP client configuration
    client_config:
      timeout: "30s"
      retry_policy:
        max_attempts: 3
    
    # MCP servers
    servers:
      server-name:
        transport:
          type: "stdio"  # or "http", "sse"
          # Transport-specific config
        
        # Optional configurations
        auth:           # Authentication
        tools:          # Tool filtering
        config:         # Server-specific config
        env:           # Environment variables

Quick Start

Add basic tools to your workspace:

tools:
  mcp:
    servers:
      # File system access
      filesystem:
        transport:
          type: "stdio"
          command: "npx"
          args: ["-y", "@modelcontextprotocol/server-filesystem"]
        config:
          root_path: "./data"
          allow_write: false
      
      # Web search
      web-search:
        transport:
          type: "stdio"
          command: "mcp-websearch"
        env:
          SEARCH_API_KEY: "${SEARCH_API_KEY}"

Transport Types

STDIO Transport

For command-line MCP servers:

servers:
  my-tool:
    transport:
      type: "stdio"
      command: "python"           # Command to run
      args: ["mcp_server.py"]    # Command arguments
      cwd: "./tools"             # Working directory
      env:                       # Environment variables
        PYTHONPATH: "./lib"

HTTP Transport

For HTTP-based MCP servers:

servers:
  api-tool:
    transport:
      type: "http"
      url: "http://localhost:8080/mcp"
      method: "POST"              # HTTP method
      headers:                    # Custom headers
        "User-Agent": "Atlas/1.0"
      timeout: "60s"

SSE Transport

For Server-Sent Events streaming:

servers:
  streaming-tool:
    transport:
      type: "sse"
      url: "https://api.example.com/v1/mcp/stream"
      reconnect: true
      reconnect_delay: "5s"

Authentication

Bearer Token

servers:
  secure-api:
    transport:
      type: "http"
      url: "https://api.service.com/mcp"
    auth:
      type: "bearer"
      token: "your-token-here"         # Direct token
      token_env: "SERVICE_API_TOKEN"   # From environment

API Key

servers:
  api-service:
    auth:
      type: "api_key"
      header: "X-API-Key"              # Header name
      key: "${API_KEY}"                # Key value

Basic Auth

servers:
  protected-service:
    auth:
      type: "basic"
      username: "user"
      password_env: "SERVICE_PASSWORD"

OAuth

servers:
  oauth-service:
    auth:
      type: "oauth"
      client_id: "${OAUTH_CLIENT_ID}"
      client_secret_env: "OAUTH_CLIENT_SECRET"
      token_endpoint: "https://auth.example.com/token"
      scopes: ["read", "write"]

Tool Filtering

Control which tools agents can access:

Allow Lists

Only permit specific tools:

servers:
  github:
    transport:
      type: "stdio"
      command: "mcp-github"
    tools:
      allow:
        - "search_repositories"
        - "get_file_contents"
        - "list_issues"
      # All other tools are denied

Deny Lists

Block specific tools:

servers:
  filesystem:
    transport:
      type: "stdio"
      command: "mcp-filesystem"
    tools:
      deny:
        - "delete_file"
        - "write_file"
      # All other tools are allowed

Pattern Matching

Use patterns for filtering:

servers:
  database:
    tools:
      allow:
        - "read_*"      # All read operations
        - "list_*"      # All list operations
      deny:
        - "*_delete"    # No delete operations
        - "*_drop"      # No drop operations

Common MCP Servers

File System

Read and write files:

servers:
  filesystem:
    transport:
      type: "stdio"
      command: "npx"
      args: ["-y", "@modelcontextprotocol/server-filesystem"]
    config:
      root_path: "./workspace"
      allow_hidden: false
      max_file_size: "10MB"
    tools:
      allow:
        - "read_file"
        - "list_files"
        - "search_files"

GitHub Integration

Work with GitHub repositories:

servers:
  github:
    transport:
      type: "stdio"
      command: "npx"
      args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_TOKEN: "${GITHUB_TOKEN}"
    config:
      default_org: "your-org"
      include_private: true

Database Access

Query databases:

servers:
  postgres:
    transport:
      type: "stdio"
      command: "mcp-postgres"
    config:
      connection_string: "${DATABASE_URL}"
      ssl: true
      read_only: false
      max_query_time: "30s"
    tools:
      allow:
        - "query"
        - "list_tables"
        - "describe_table"

Web Browser

Scrape and interact with web pages:

servers:
  browser:
    transport:
      type: "stdio"
      command: "mcp-browser"
    config:
      headless: true
      timeout: "30s"
      user_agent: "Atlas Bot 1.0"
      viewport:
        width: 1920
        height: 1080

Slack Integration

Send messages and read channels:

servers:
  slack:
    transport:
      type: "stdio"
      command: "mcp-slack"
    env:
      SLACK_BOT_TOKEN: "${SLACK_BOT_TOKEN}"
    config:
      default_channel: "#general"
    tools:
      allow:
        - "send_message"
        - "read_channel"
        - "list_channels"

Advanced Configuration

Global Client Configuration

Set defaults for all MCP connections:

tools:
  mcp:
    client_config:
      # Timeouts
      timeout: "30s"
      connect_timeout: "10s"
      
      # Retry policy
      retry_policy:
        max_attempts: 3
        initial_delay: "1s"
        max_delay: "10s"
        backoff_multiplier: 2
      
      # Connection pooling
      connection_pool:
        max_connections: 10
        max_idle_connections: 5
        idle_timeout: "300s"
      
      # Rate limiting
      rate_limit:
        requests_per_second: 10
        burst_size: 20

Server-Specific Configuration

Override global settings per server:

servers:
  slow-api:
    transport:
      type: "http"
      url: "https://slow-api.example.com/mcp"
    
    # Override global timeout
    client_config:
      timeout: "120s"  # 2 minutes for slow API
      retry_policy:
        max_attempts: 5  # More retries

Environment Variables

Pass environment to MCP servers:

servers:
  custom-tool:
    transport:
      type: "stdio"
      command: "./custom-mcp-server"
    env:
      # Direct values
      LOG_LEVEL: "debug"
      PORT: "8080"
      
      # From environment
      API_KEY: "${CUSTOM_API_KEY}"
      DATABASE_URL: "${DATABASE_URL}"
      
      # With defaults
      CACHE_TTL: "${CACHE_TTL:-3600}"

Health Checks

Monitor MCP server health:

servers:
  critical-service:
    transport:
      type: "http"
      url: "https://critical.example.com/mcp"
    
    health_check:
      enabled: true
      endpoint: "/health"
      interval: "30s"
      timeout: "5s"
      failure_threshold: 3
      success_threshold: 1

Security Considerations

Permission Scoping

Limit tool permissions:

servers:
  filesystem:
    transport:
      type: "stdio"
      command: "mcp-filesystem"
    
    # Restrict file access
    permissions:
      read_paths:
        - "./data"
        - "./configs"
      write_paths:
        - "./output"
      forbidden_paths:
        - "/etc"
        - "~/.ssh"
        - ".env"

Secret Management

Never hardcode secrets:

# ❌ Bad - Exposed secret
auth:
  token: "sk-abc123xyz789"

# ✅ Good - Environment variable
auth:
  token_env: "API_TOKEN"

# ✅ Good - Secret file
auth:
  token_file: "/run/secrets/api_token"

Network Security

Control network access:

servers:
  external-api:
    transport:
      type: "http"
      url: "https://api.example.com/mcp"
    
    network:
      allowed_hosts:
        - "api.example.com"
        - "auth.example.com"
      proxy: "${HTTPS_PROXY}"
      verify_ssl: true
      ca_cert: "./certs/ca.pem"

Tool Development

Creating Custom MCP Servers

Basic Python MCP server:

# my_mcp_server.py
from mcp import Server, Tool

server = Server("my-tools")

@server.tool(
    name="process_data",
    description="Process data with custom logic",
    parameters={
        "type": "object",
        "properties": {
            "input": {"type": "string"},
            "operation": {
                "type": "string",
                "enum": ["transform", "analyze", "summarize"]
            }
        },
        "required": ["input", "operation"]
    }
)
async def process_data(input: str, operation: str):
    # Your tool implementation
    if operation == "transform":
        result = transform_data(input)
    elif operation == "analyze":
        result = analyze_data(input)
    else:
        result = summarize_data(input)
    
    return {"result": result}

if __name__ == "__main__":
    server.run()

Configure in workspace.yml:

servers:
  custom-processor:
    transport:
      type: "stdio"
      command: "python"
      args: ["./tools/my_mcp_server.py"]
    config:
      log_level: "info"

Testing Tools

Test MCP server connectivity:

# List available tools
atlas tools list

# Test specific tool
atlas tools test filesystem read_file --params '{"path": "test.txt"}'

# Debug tool calls
atlas tools debug --server github

Tool Usage Patterns

1. Data Pipeline Tools

servers:
  # Data extraction
  data-extractor:
    transport:
      type: "stdio"
      command: "mcp-extractor"
    config:
      supported_formats: ["csv", "json", "xlsx"]
  
  # Data transformation
  data-transformer:
    transport:
      type: "stdio"
      command: "mcp-transformer"
    config:
      transformations: ["normalize", "aggregate", "pivot"]
  
  # Data storage
  data-store:
    transport:
      type: "http"
      url: "http://datastore:8080/mcp"
    config:
      database: "analytics"

2. Communication Tools

servers:
  # Email
  email:
    transport:
      type: "stdio"
      command: "mcp-email"
    config:
      smtp_host: "${SMTP_HOST}"
      smtp_port: 587
  
  # Slack
  slack:
    transport:
      type: "stdio"
      command: "mcp-slack"
    env:
      SLACK_TOKEN: "${SLACK_TOKEN}"
  
  # SMS
  sms:
    transport:
      type: "http"
      url: "https://sms-gateway.com/mcp"
    auth:
      type: "api_key"
      key_env: "SMS_API_KEY"

3. Development Tools

servers:
  # Code execution
  code-runner:
    transport:
      type: "stdio"
      command: "mcp-coderunner"
    config:
      languages: ["python", "javascript", "bash"]
      timeout: "30s"
      memory_limit: "512MB"
  
  # Git operations
  git:
    transport:
      type: "stdio"
      command: "mcp-git"
    config:
      default_branch: "main"
      allow_push: false
  
  # Container management
  docker:
    transport:
      type: "stdio"
      command: "mcp-docker"
    config:
      socket: "/var/run/docker.sock"

Best Practices

1. Minimal Tool Sets

Only add tools agents actually need:

# Good - Focused tools
agents:
  analyst:
    tools: ["data-reader", "calculator"]

# Avoid - Too many tools
agents:
  everything:
    tools: ["tool1", "tool2", "tool3", "tool4", ...]

2. Tool Documentation

Document tool usage:

servers:
  custom-api:
    description: |
      Custom API integration for order processing.
      Available operations:
      - create_order: Create new order
      - check_status: Check order status
      - cancel_order: Cancel existing order

3. Error Handling

Configure robust error handling:

servers:
  external-service:
    transport:
      type: "http"
      url: "https://api.example.com/mcp"
    
    error_handling:
      retry_on: ["timeout", "500", "503"]
      fallback_response: {
        "status": "unavailable",
        "message": "Service temporarily unavailable"
      }

4. Performance

Optimize tool performance:

client_config:
  # Cache tool responses
  cache:
    enabled: true
    ttl: "300s"
    max_size: "100MB"
  
  # Connection reuse
  connection_pool:
    max_connections: 20
    keepalive: true

5. Monitoring

Track tool usage:

servers:
  monitored-tool:
    metrics:
      enabled: true
      track:
        - "call_count"
        - "response_time"
        - "error_rate"
        - "data_processed"

Working with Agents

Workspace Configuration

Tutorials

​Adding Tools

​Tools Configuration Structure

​Quick Start

​Transport Types

​STDIO Transport

​HTTP Transport

​SSE Transport

​Authentication

​Bearer Token

​API Key

​Basic Auth

​OAuth

​Tool Filtering

​Allow Lists

​Deny Lists

​Pattern Matching

​Common MCP Servers

​File System

​GitHub Integration

​Database Access

​Web Browser

​Slack Integration

​Advanced Configuration

​Global Client Configuration

​Server-Specific Configuration

​Environment Variables

​Health Checks

​Security Considerations

​Permission Scoping

​Secret Management

​Network Security

​Tool Development

​Creating Custom MCP Servers

​Testing Tools

​Tool Usage Patterns

​1. Data Pipeline Tools

​2. Communication Tools

​3. Development Tools

​Best Practices

​1. Minimal Tool Sets

​2. Tool Documentation

​3. Error Handling

​4. Performance

​5. Monitoring

​Troubleshooting

​Tool Not Available

​Permission Denied

​Timeout Errors

​Connection Failures

​Next Steps