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 mcpt deploy for these servers.
Stdio Transport: Servers run interactively using stdin/stdout communication. Use mcpt 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:

$ mcpt 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:
  mcpt> tools github                         # List available tools
  mcpt 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
mcpt> tools github

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

# Force refresh tool cache
mcpt> tools github --refresh

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

2. Running Tools¶

Execute individual tools using the run-tool command:

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

# Simple example
mcpt 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
mcpt run-tool github search_repositories \
  --args '{"query": "mcp server", "per_page": 10}'

# Complex nested arguments
mcpt 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
mcpt run-tool github create_issue \
  --args '{"owner": "user", "repo": "test", "title": "Bug report"}' \
  --env GITHUB_PERSONAL_ACCESS_TOKEN=your_token

# Multiple environment variables
mcpt 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
mcpt run-tool filesystem read_file \
  --args '{"path": "/data/file.txt"}' \
  --config allowed_directories='["/data", "/workspace"]' \
  --config read_only=true

# Timeout and performance settings
mcpt 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
mcpt 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
mcpt run-tool github get_file_contents \
  --args '{"owner": "microsoft", "repo": "vscode", "path": "README.md"}' \
  --env GITHUB_PERSONAL_ACCESS_TOKEN=your_token

# Create an issue
mcpt 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
mcpt run-tool github search_users \
  --args '{"q": "location:San Francisco followers:>100"}' \
  --env GITHUB_PERSONAL_ACCESS_TOKEN=your_token

Filesystem Operations¶

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

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

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

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

Database Operations¶

# Execute a query
mcpt 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
mcpt 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
mcpt> tools --image company/custom-mcp:latest

# Run tools from custom servers
mcpt 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

$ mcpt run-tool nonexistent search
❌ Template 'nonexistent' not found

Solution: Check available templates with mcpt list

2. Tool Not Found

$ mcpt run-tool github invalid_tool
❌ Unknown tool: invalid_tool

Solution: List available tools with mcpt> tools github

3. Invalid JSON Arguments

$ mcpt 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)
mcpt 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..."
mcpt 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..."
mcpt 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
mcpt 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
mcpt 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 mcpt> 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": "mcpt 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: |
          mcpt 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.