Shell Commands

Wrap any CLI tool as an MCP tool. Arguments are declared with types and passed into a command template. Shell-escape is applied automatically to prevent injection.

Configuration

upstreams:
  - name: cluster
    type: command
    tool_prefix: k8s
    tools:
      - name: get_pods
        description: List pods in a namespace
        command: kubectl get pods -n {{namespace}} -o json
        args:
          namespace:
            type: string
            description: Kubernetes namespace
            required: true
        timeout: 30s

      - name: describe_pod
        description: Describe a specific pod
        command: kubectl describe pod {{pod}} -n {{namespace}}
        args:
          pod:
            type: string
            description: Pod name
            required: true
          namespace:
            type: string
            description: Kubernetes namespace
            default: default
        timeout: 20s

Argument interpolation

Arguments are referenced in the command string using double-brace syntax: {{arg_name}}. Before execution, each argument value is shell-escaped to prevent injection attacks.

Supported argument types:

Type	Description
`string`	Text value, shell-escaped
`integer`	Integer, validated before interpolation
`number`	Float, validated before interpolation
`boolean`	true/false
`array`	Comma-separated values

Argument options

Field	Type	Description
`type`	string	Argument type (see above)
`description`	string	Shown to the MCP client
`required`	bool	Whether the argument must be provided
`default`	any	Value used when argument is absent
`enum`	array	Allowed values

Timeout

The timeout field (e.g. 30s, 2m) sets the maximum execution time. Commands that exceed the timeout are killed and an error is returned to the MCP client.

Working directory and environment

Commands inherit the proxy process's working directory and environment. Use ${ENV_VAR} syntax in the command string to inject environment variables — these are expanded from the proxy environment before execution, not passed as shell variables.

tools:
  - name: aws_s3_ls
    description: List S3 bucket contents
    command: aws s3 ls s3://{{bucket}} --region ${AWS_DEFAULT_REGION}
    args:
      bucket:
        type: string
        required: true

Common examples

kubectl

tools:
  - name: get_pods
    command: kubectl get pods -n {{namespace}} -o json
    args:
      namespace:
        type: string
        required: true

  - name: get_logs
    command: kubectl logs {{pod}} -n {{namespace}} --tail {{lines}}
    args:
      pod:
        type: string
        required: true
      namespace:
        type: string
        default: default
      lines:
        type: integer
        default: 50

AWS CLI

tools:
  - name: describe_instances
    command: aws ec2 describe-instances --region {{region}} --output json
    args:
      region:
        type: string
        required: true
        enum: [us-east-1, us-west-2, eu-west-1]

Git

tools:
  - name: git_log
    command: git -C {{repo}} log --oneline -{{count}}
    args:
      repo:
        type: string
        required: true
      count:
        type: integer
        default: 20