Stdio Tool Execution Guide¶

This guide covers executing tools from stdio MCP servers using the run-tool command. Stdio MCP servers use standard input/output for communication and are designed for interactive tool execution rather than persistent deployment.

Overview¶

Transport Types¶

MCP servers support two transport types:

HTTP Transport: Servers run as persistent containers accessible via HTTP endpoints. Use mcp-template deploy for these servers.
Stdio Transport: Servers run interactively using stdin/stdout communication. Use mcp-template run-tool for these servers.

Why Stdio Servers Can't Be Deployed¶

Stdio MCP servers are designed for interactive communication and cannot run as persistent background services. When you attempt to deploy a stdio server, you'll see a helpful error message:

$ mcp-template deploy github
❌ Cannot deploy stdio transport MCP servers

The template github uses stdio transport, which doesn't require deployment.
Stdio MCP servers run interactively and cannot be deployed as persistent containers.

Available tools in this template:
  • search_repositories
  • create_repository  
  • get_file_contents
  • create_issue
  • create_pull_request

To use this template, run tools directly:
  mcp-template tools github                         # List available tools
  mcp-template run-tool github <tool_name>          # Run a specific tool

Basic Usage¶

1. Discovering Available Tools¶

Before running tools, discover what's available:

# List all tools in a template
mcp-template tools github

# List tools with configuration (for dynamic discovery)
mcp-template tools github --config github_token=your_token

# Force refresh tool cache
mcp-template tools github --refresh

# Discover tools from a Docker image directly
mcp-template tools --image mcp/custom-server:latest

2. Running Tools¶

Execute individual tools using the run-tool command:

# Basic syntax
mcp-template run-tool <template> <tool_name> [options]

# Simple example
mcp-template run-tool github search_repositories --args '{"query": "mcp server"}'

Command Options¶

`--args`: JSON Tool Arguments¶

Pass structured data to tools using JSON format:

# Simple arguments
mcp-template run-tool github search_repositories \
  --args '{"query": "mcp server", "per_page": 10}'

# Complex nested arguments
mcp-template run-tool github create_pull_request \
  --args '{
    "owner": "username",
    "repo": "project",
    "title": "Feature: Add new functionality", 
    "head": "feature-branch",
    "base": "main",
    "body": "This PR adds:\n- Feature 1\n- Feature 2"
  }'

`--env`: Environment Variables¶

Provide authentication and configuration via environment variables:

# GitHub authentication
mcp-template run-tool github create_issue \
  --args '{"owner": "user", "repo": "test", "title": "Bug report"}' \
  --env GITHUB_PERSONAL_ACCESS_TOKEN=your_token

# Multiple environment variables
mcp-template run-tool database query \
  --args '{"sql": "SELECT * FROM users"}' \
  --env DB_HOST=localhost \
  --env DB_PORT=5432 \
  --env DB_PASSWORD=secret

`--config`: Server Configuration¶

Configure the MCP server behavior:

# Filesystem security settings
mcp-template run-tool filesystem read_file \
  --args '{"path": "/data/file.txt"}' \
  --config allowed_directories='["/data", "/workspace"]' \
  --config read_only=true

# Timeout and performance settings  
mcp-template run-tool api-client fetch_data \
  --args '{"url": "https://api.example.com/data"}' \
  --config timeout=30 \
  --config max_retries=3

Practical Examples¶

GitHub Operations¶

# Search for repositories
mcp-template run-tool github search_repositories \
  --args '{"query": "python machine learning", "sort": "stars"}' \
  --env GITHUB_PERSONAL_ACCESS_TOKEN=your_token

# Get file contents from a repository
mcp-template run-tool github get_file_contents \
  --args '{"owner": "microsoft", "repo": "vscode", "path": "README.md"}' \
  --env GITHUB_PERSONAL_ACCESS_TOKEN=your_token

# Create an issue
mcp-template run-tool github create_issue \
  --args '{
    "owner": "user",
    "repo": "project", 
    "title": "Bug: Application crashes on startup",
    "body": "## Description\nThe app crashes when...\n\n## Steps to Reproduce\n1. Step 1\n2. Step 2",
    "labels": ["bug", "high-priority"]
  }' \
  --env GITHUB_PERSONAL_ACCESS_TOKEN=your_token

# Search for users
mcp-template run-tool github search_users \  
  --args '{"q": "location:San Francisco followers:>100"}' \
  --env GITHUB_PERSONAL_ACCESS_TOKEN=your_token

Filesystem Operations¶

# List directory contents
mcp-template run-tool filesystem list_directory \
  --args '{"path": "/data"}' \
  --config allowed_directories='["/data", "/workspace"]'

# Read file contents
mcp-template run-tool filesystem read_file \
  --args '{"path": "/data/config.json"}' \
  --config allowed_directories='["/data"]' \
  --config read_only=true

# Create a new file
mcp-template run-tool filesystem create_file \
  --args '{"path": "/workspace/output.txt", "content": "Hello, World!"}' \
  --config allowed_directories='["/workspace"]' \
  --config read_only=false

# Search files
mcp-template run-tool filesystem search_files \
  --args '{"pattern": "*.py", "directory": "/workspace"}' \
  --config allowed_directories='["/workspace"]'

Database Operations¶

# Execute a query
mcp-template run-tool database query \
  --args '{"sql": "SELECT name, email FROM users WHERE active = true LIMIT 10"}' \
  --config connection_string="postgresql://localhost:5432/mydb" \
  --env DB_PASSWORD=secret

# Get table schema
mcp-template run-tool database describe_table \
  --args '{"table_name": "users"}' \
  --config connection_string="postgresql://localhost:5432/mydb" \
  --env DB_PASSWORD=secret

Custom MCP Servers¶

# Work with custom Docker images
mcp-template tools --image company/custom-mcp:latest

# Run tools from custom servers
mcp-template run-tool custom-template analyze_data \
  --args '{"dataset": "sales_2024.csv", "type": "summary"}' \
  --config input_directory="/data" \
  --config output_format="json"

Error Handling¶

Common Errors and Solutions¶

1. Template Not Found

$ mcp-template run-tool nonexistent search
❌ Template 'nonexistent' not found

Solution: Check available templates with mcp-template list

2. Tool Not Found

$ mcp-template run-tool github invalid_tool
❌ Unknown tool: invalid_tool

Solution: List available tools with mcp-template tools github

3. Invalid JSON Arguments

$ mcp-template run-tool github search --args '{invalid json}'
❌ Invalid JSON in tool arguments: {invalid json}

Solution: Validate JSON syntax, use online JSON validators

4. Authentication Errors

❌ Tool execution failed: Authentication required

Solution: Provide required environment variables (e.g., API tokens)

5. Permission Errors

❌ Tool execution failed: Access denied to path /restricted

Solution: Check allowed_directories configuration for filesystem tools

Advanced Usage¶

Configuration Files¶

For complex configurations, use configuration files:

// config.json
{
  "security": {
    "allowed_directories": ["/data", "/workspace"],
    "read_only": false,
    "max_file_size": 100
  },
  "performance": {
    "timeout": 30,
    "max_concurrent_operations": 5
  }
}

# Use configuration file (if supported by the template)
mcp-template run-tool filesystem read_file \
  --args '{"path": "/data/file.txt"}' \
  --config-file config.json

Scripting and Automation¶

Use run-tool in scripts for automation:

#!/bin/bash

# Automated GitHub workflow
GITHUB_TOKEN="your_token"

# Search for issues
echo "Searching for open issues..."
mcp-template run-tool github search_issues \
  --args '{"q": "repo:user/project state:open label:bug"}' \
  --env GITHUB_PERSONAL_ACCESS_TOKEN="$GITHUB_TOKEN"

# Create a new issue
echo "Creating issue..."
mcp-template run-tool github create_issue \
  --args '{"owner": "user", "repo": "project", "title": "Automated Issue", "body": "Created by script"}' \
  --env GITHUB_PERSONAL_ACCESS_TOKEN="$GITHUB_TOKEN"

Integration with Other Tools¶

Combine with standard Unix tools:

# Process JSON output with jq
mcp-template run-tool github search_repositories \
  --args '{"query": "mcp"}' \
  --env GITHUB_PERSONAL_ACCESS_TOKEN=token | \
  jq '.items[0:5] | .[] | {name: .name, stars: .stargazers_count}'

# Save output to file
mcp-template run-tool filesystem list_directory \
  --args '{"path": "/data"}' > directory_listing.json

Best Practices¶

1. Security¶

Never hardcode sensitive tokens in scripts
Use environment variables or secure config files for authentication
Configure appropriate allowed_directories for filesystem access
Enable read_only mode when write access isn't needed

2. Performance¶

Use appropriate timeout values for long-running operations
Cache tool discovery results when possible
Limit result sets with pagination parameters

3. Error Handling¶

Always check tool output for errors before processing
Use --refresh flag if tool discovery seems outdated
Validate JSON arguments before sending complex requests

4. Documentation¶

Use mcp-template tools <template> to discover available tools
Check template documentation for specific configuration options
Review tool descriptions and parameter requirements

Integration Examples¶

VS Code/Cursor Integration¶

{
  "tasks": [
    {
      "label": "Search GitHub Issues",
      "type": "shell", 
      "command": "mcp-template run-tool github search_issues --args '{\"q\": \"${input:searchQuery}\"}' --env GITHUB_PERSONAL_ACCESS_TOKEN=${env:GITHUB_TOKEN}",
      "group": "build"
    }
  ]
}

CI/CD Pipeline Integration¶

# GitHub Actions example
name: MCP Tool Integration
on: [push]
jobs:
  analyze:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Install MCP Template
        run: pip install mcp-template
      - name: Analyze Repository
        run: |
          mcp-template run-tool filesystem search_files \
            --args '{"pattern": "*.py", "directory": "."}' \
            --config allowed_directories='["."]' > analysis.json
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

This comprehensive guide should help you effectively use stdio MCP servers with the run-tool command for interactive tool execution.