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

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

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

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

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

2. Running Tools¶

Execute individual tools using the run-tool command:

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

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

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

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

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

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

Filesystem Operations¶

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

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

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

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

Database Operations¶

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

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

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

Solution: Check available templates with mcpp list

2. Tool Not Found

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

Solution: List available tools with mcpp> tools github

3. Invalid JSON Arguments

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