MCP Server

Dyngle can run as an MCP (Model Context Protocol) server, exposing operations as tools that AI assistants like Claude can execute.

What is MCP?

The Model Context Protocol (MCP) is a standardized protocol that allows AI assistants to discover and use external tools. When Dyngle runs as an MCP server, your configured operations become tools that AI assistants can call to perform tasks.

Starting the Server

Use the mcp command to start the server:

dyngle mcp

By default, this starts a server using the stdio transport, suitable for Claude Desktop integration.

Transport Options

stdio (default)

Standard input/output transport, ideal for Claude Desktop:

dyngle mcp

http

HTTP transport for remote connections:

dyngle mcp --transport http --host 127.0.0.1 --port 8000

sse

Server-Sent Events transport:

dyngle mcp --transport sse --host 127.0.0.1 --port 8000

How Operations Become Tools

When the MCP server starts:

Each public operation becomes an MCP tool
Private operations are not exposed
Tools accept two parameters:
- data - Dictionary/JSON object (equivalent to stdin data)
- args - List of arguments (equivalent to CLI arguments)

Tool Response Format

Tools return JSON responses:

Success:

{"result": <value>}

Where <value> is the operation's return value (if specified), or null if no return value.

Failure:

{"error": "<message>"}

Example Operation as Tool

dyngle:
  operations:
    get-weather:
      description: Get current weather for a city
      return: weather-info
      expressions:
        city: "args[0] if args else 'Unknown'"
      steps:
        - curl -s "https://api.example.com/weather?city={{city}}" => weather-info

An AI assistant can call this tool:

{
  "tool": "get-weather",
  "args": ["San Francisco"]
}

And receive:

{
  "result": {
    "temperature": 72,
    "conditions": "Sunny",
    "humidity": 65
  }
}

Configuring Claude Desktop

To use Dyngle operations with Claude Desktop, configure the MCP server in Claude's configuration file.

macOS Configuration

Edit or create ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "dyngle": {
      "command": "dyngle",
      "args": ["mcp"]
    }
  }
}

Windows Configuration

Edit or create %APPDATA%/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "dyngle": {
      "command": "dyngle",
      "args": ["mcp"]
    }
  }
}

Specifying a Configuration File

Use a specific Dyngle configuration:

{
  "mcpServers": {
    "my-workflows": {
      "command": "dyngle",
      "args": ["--config", "/absolute/path/to/.dyngle.yml", "mcp"]
    }
  }
}

Important:

Use absolute paths
Restart Claude Desktop completely after editing (not just close the window)
Tools appear in Claude's "Search and tools" interface

Design Considerations

Use Descriptions

Operations exposed via MCP should have clear descriptions:

dyngle:
  operations:
    deploy-staging:
      description: Deploy the application to staging environment
      steps:
        - sub: build
        - aws s3 sync ./dist s3://staging-bucket/

The description helps AI assistants understand when to use the tool.

Return Values for Tools

Operations used as tools should return meaningful values:

dyngle:
  operations:
    check-status:
      description: Check deployment status
      return: status
      steps:
        - curl -s "https://api.example.com/status" => status

This allows AI assistants to incorporate the result into their responses.

Private Operations for Secrets

Use private operations to protect sensitive operations:

dyngle:
  operations:
    get-credentials:
      access: private
      return: creds
      steps:
        - aws secretsmanager get-secret-value --secret-id api-creds => creds
    
    make-api-call:
      description: Call the API with authentication
      steps:
        - sub: get-credentials
          => creds
        - curl -H "Authorization: {{creds}}" https://api.example.com/data

The get-credentials operation won't be exposed to AI assistants.

Example Use Cases

Development Workflow Tools

dyngle:
  operations:
    run-tests:
      description: Run the test suite and report results
      return: test-results
      steps:
        - pytest --json-report => results
        - results -> jq '.summary' => test-results
    
    check-coverage:
      description: Check code coverage percentage
      return: coverage
      steps:
        - pytest --cov=src --cov-report=json => cov-report
        - cov-report -> jq '.totals.percent_covered' => coverage

Information Queries

dyngle:
  operations:
    get-latest-version:
      description: Get the latest version from package.json
      return: version
      steps:
        - cat package.json => pkg
        - pkg -> jq -r '.version' => version
    
    list-deployments:
      description: List recent deployments
      return: deployments
      steps:
        - aws s3api list-objects-v2 --bucket deployments --max-items 10 => deployments

System Operations

dyngle:
  operations:
    restart-service:
      description: Restart the application service
      return: status
      steps:
        - systemctl restart myapp => output
        - echo "Service restarted successfully" => status

Troubleshooting

Server Not Showing Up

Check JSON syntax - Validate claude_desktop_config.json
Verify Dyngle in PATH - Run which dyngle (macOS/Linux) or where dyngle (Windows)
Use full path - Try the full path to the dyngle executable in the command field
Restart Claude Desktop - Use Cmd+Q (macOS) or quit from system tray (Windows)

Checking Logs (macOS)

Claude Desktop writes logs to ~/Library/Logs/Claude/:

tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

Tool Execution Failures

Test manually - Run the operation with dyngle run first
Check arguments - Verify the AI assistant is passing correct data/args
Review error field - Check the {"error": "..."} response
Check MCP logs - Look for stdout/stderr in the MCP server logs

Operations Not Appearing

Verify access - Only public operations are exposed
Check description - Operations without descriptions still work but are harder for AI to discover
Restart Claude - Changes require a full restart of Claude Desktop

Security Considerations

Only expose safe operations - Be mindful of what operations you make available
Use private operations - Mark sensitive operations as access: private
Validate inputs - Operations should handle unexpected inputs gracefully
Limit access - Consider which operations should be accessible to AI assistants

See Security for more details.