Workato MCP Service

This project provides a Model Context Protocol (MCP) server that integrates with the Workato API, allowing AI assistants to interact with Workato workflows, recipes, and data.

What is MCP?

Model Context Protocol (MCP) is a standard that allows AI assistants to connect to external data sources and tools. This service provides a bridge between AI assistants and the Workato automation platform.

Prerequisites

Before running this service, you'll need:

Python 3.10+ installed on your system
Git for cloning the repository
Workato API access (API token and base URL)
AI assistant that supports MCP (like Claude Desktop, Cursor, or others)

Installation

1. Clone the Repository

git clone <your-repository-url>
cd worka42

2. Install Dependencies

The project uses uv for dependency management. Install it first if you don't have it:

# On Windows (PowerShell)
winget install --id=astral-sh.uv

# On macOS
brew install uv

# On Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

Then install the project dependencies:

uv sync

3. Configure MCP

The project includes a smart wrapper script (run_mcp.py) that automatically detects your environment and uses the correct Python setup.

Step 1: Copy the MCP template to your Cursor settings:

# Windows
copy mcp.json.template %USERPROFILE%\.cursor\mcp.json

# macOS/Linux
cp mcp.json.template ~/.cursor/mcp.json

Step 2: Edit the copied file with your details:

{
  "mcpServers": {
    "workato": {
      "command": "python",
      "args": ["/absolute/path/to/worka42/run_mcp.py"],
      "env": {
        "WORKATO_API_BASE_URL": "https://www.workato.com/api/",
        "WORKATO_API_TOKEN": "your_workato_api_token_here"
      }
    }
  }
}

Important:

Replace /absolute/path/to/worka42 with your actual project path
Replace your_workato_api_token_here with your Workato API token

Step 3: Restart Cursor to load the new MCP configuration.

How the Wrapper Script Works

The run_mcp.py script automatically detects your environment:

If .venv exists (after running uv sync): Uses uv run python app/services/mcp_service.py
If no .venv: Falls back to direct python app/services/mcp_service.py

This ensures compatibility across different Python setups while maintaining the benefits of uv's dependency management.

⚠️ Important: Never commit your mcp.json file to version control as it contains sensitive API tokens. The file is already added to .gitignore.

Running the MCP Service

Option 1: Run as MCP Server (Recommended)

The service is designed to run as an MCP server that AI assistants can connect to:

uv run python app/services/mcp_service.py

Option 2: Run as FastAPI Server

You can also run it as a standalone FastAPI server for testing:

cd app
uv run uvicorn services.mcp_service:app --reload --host 0.0.0.0 --port 8000

Connecting AI Assistants

Cursor

Open Cursor
Press Cmd/Ctrl + Shift + P to open command palette
Type "MCP: Connect to Server"
Select your mcp.json file
The Workato MCP server will be available in your AI conversations

Other MCP-Compatible Assistants

Most MCP-compatible assistants will look for the mcp.json file in your project directory or allow you to specify its location in their settings.

Available MCP Tools

Once connected, your AI assistant will have access to these Workato operations:

Recipe Management

List recipes with filtering and pagination
Get recipe details, versions, and health reports
View recipe jobs and execution history

Connection Management

List and manage Workato connections
View connector metadata and custom connectors

Data Operations

Access lookup tables and data tables
Query and manipulate Workato data

Project Management

Manage Workato projects and deployments
View project properties and builds

User Management

List workspace members and their privileges
Manage user roles and permissions

Environment Variables

You can configure the service using environment variables:

export WORKATO_API_BASE_URL="https://www.workato.com/api/"
export WORKATO_API_TOKEN="your_token_here"
export LOG_LEVEL="INFO"

Troubleshooting

Common Issues

"MCP package not available" error
- Make sure you've installed all dependencies: uv sync
- Verify FastMCP is installed: uv run python -c "import mcp.server.fastmcp"
"Permission denied" when running
- Ensure you have execute permissions on the Python files
- Try running with uv run python -m app.services.mcp_service
AI assistant can't connect or doesn't recognize tools
- Check MCP configuration location: Ensure mcp.json is in your Cursor settings directory (~/.cursor/ or %USERPROFILE%\.cursor\)
- Verify project path: Make sure the absolute path in mcp.json points to your actual project directory
- Test the wrapper script: Run python run_mcp.py from the project directory to see if it starts without errors
- Check environment variables: Verify WORKATO_API_TOKEN is set correctly in mcp.json
- Validate JSON: Ensure mcp.json is valid JSON (no trailing commas, proper quotes)
- Restart Cursor: Always restart Cursor after making MCP configuration changes
"No tools available" or empty tool list
- Test the wrapper script: Run python run_mcp.py to verify the MCP server starts correctly
- Check dependencies: Ensure all dependencies are installed with uv sync
- Verify API token: Test your Workato API token: uv run python -c "from app.services.workato_service import WorkatoService; WorkatoService().get_user_info()"
- Check wrapper script: Ensure run_mcp.py is in your project root directory
Workato API errors
- Verify your API token is valid and has the necessary permissions
- Check that the API base URL is correct
- Ensure your Workato account has API access enabled

Debug Steps

Test the wrapper script:
```
cd /path/to/worka42
python run_mcp.py
```

Check if tools are registered:

uv run python -c "from app.services.mcp_service import app; import asyncio; tools = asyncio.run(app.list_tools()); print('Tools count:', len(tools))"

Verify environment and dependencies:

# Check if dependencies are installed
uv run python -c "import mcp.server.fastmcp; print('FastMCP available')"

# Check environment variables
uv run python -c "import os; print('API Token set:', bool(os.getenv('WORKATO_API_TOKEN')))"

Test Workato API connection:

uv run python -c "from app.services.workato_service import WorkatoService; print('API test:', WorkatoService().get_user_info())"

Debug Mode

Enable debug logging by setting the environment variable:

export LOG_LEVEL="DEBUG"

Development

Project Structure

worka42/
├── app/
│   ├── __init__.py             # Package initialization
│   ├── services/
│   │   ├── __init__.py         # Services package initialization
│   │   ├── mcp_service.py      # Main MCP server
│   │   └── workato_service.py  # Workato API client
│   ├── utils/
│   │   ├── __init__.py         # Utils package initialization
│   │   ├── logging.py          # Logging configuration
│   │   ├── params.py           # Parameter parsing utilities
│   │   └── response_helpers.py # Response formatting utilities
│   ├── pyproject.toml          # Python project configuration
│   └── uv.lock                 # uv dependency lock file
├── mcp.json.template           # MCP configuration template
├── .gitignore                  # Git ignore rules
├── run_mcp.py                  # MCP server wrapper script
└── README.md                   # This file

Utility Modules

The project includes several utility modules in app/utils/:

logging.py: Centralized logging configuration using loguru
params.py: Parameter parsing and validation utilities for MCP tools
response_helpers.py: Standardized response formatting functions

Adding New MCP Tools

To add new MCP tools, modify app/services/mcp_service.py and add new functions with the @app.tool decorator:

@app.tool("new_tool_name", "Description of what this tool does")
def new_tool_function(param1: str, param2: int) -> dict:
    # Your tool implementation here
    return {"result": "success"}

Security Notes

Never commit API tokens to version control
Use environment variables for sensitive configuration
Validate all inputs before processing
Implement proper authentication if exposing the service publicly

Support

For issues related to:

MCP Protocol: Check the MCP documentation
Workato API: Refer to Workato API docs
This Service: Open an issue in the project repository

License

[Add your license information here]

Workato