# Temporal MCP

> Temporal MCP Server monitors and manages distributed workflows in Temporal Cloud. Your AI client can list active runs, search for failed executions using visibility syntax, or retrieve the entire event history to debug complex processes instantly.

## Overview
- **Category:** ship-it
- **Price:** Free
- **Tags:** workflow-orchestration, distributed-systems, durable-execution, event-history, debugging, cloud-automation

## Description

This MCP Server connects your AI client directly to Temporal Cloud's execution engine. It lets you treat complex workflow management data—the kind SREs use every day—like simple API calls right from your chat window. You don't gotta open the clunky UI or run command line tools; your agent handles it all.

### Understanding Your Workflow Environment

You can check the operational state of your system first. The `get_namespace_details` tool pulls core metadata for your current namespace, letting you verify things like the configured retention period and overall settings. Before running any searches, use `list_search_attributes` to see exactly what custom attributes are available in the namespace; this helps structure your queries correctly.

### Monitoring Runs and Status

Need a quick status check? The `list_workflows` tool gives you an immediate roster of all workflow executions in the configured namespace, listing their IDs and current status—whether they're running, completed, or failed. If you're tracking scheduled jobs, `list_schedules` returns a list of every defined recurring workflow, showing when each one is slated to run next. To get specific details on any single run, use `get_workflow_details`; this fetches the high-level status and configuration data for just that one workflow execution ID.

### Advanced Search and Querying

When you gotta dig deep, the system provides advanced querying options. The `search_workflows` tool lets you run complex queries across your entire history using Temporal Visibility syntax. You can filter results by specific types or statuses to narrow down huge datasets fast. If you're not sure what parameters work for a search, check out `list_search_attributes` first.

### Debugging Failures and Tracking History

Debugging is where this thing shines. When a workflow fails, the single most valuable thing is the full sequence of events. The `get_workflow_history` tool retrieves the complete event history log for any specific run ID; you'll see every activity, signal, and change in state that happened during its entire lifecycle, letting you pinpoint exactly where things went wrong.

For even broader visibility than a single failure, you can use `search_workflows` to find groups of failed runs or successful batches. The combination of tools means your agent handles the full audit trail: check namespace settings with `get_namespace_details`, list all running jobs using `list_workflows`, and pull the entire chronological event record for deep debugging with `get_workflow_history`. It's built for platform engineers who need answers, period.

## Tools

### get_workflow_history
Retrieves the full, detailed event history log for any specific workflow run to track its entire lifecycle.

### get_namespace_details
Retrieves core metadata, including the configured retention period, for your current namespace.

### get_workflow_details
Fetches high-level status and configuration details for a single workflow execution ID.

### list_schedules
Returns a list of all defined recurring workflows and when they are scheduled to run next.

### list_search_attributes
Shows you what custom attributes are available for searching within the namespace, helping structure your queries.

### list_workflows
Lists all workflow executions in the configured namespace, providing their IDs and current status (running, failed, etc.).

### search_workflows
Allows running complex queries across runs using Temporal Visibility syntax to filter results by type or status.

## Prompt Examples

**Prompt:** 
```
Show me the last 5 workflows that failed or panicked in the default namespace.
```

**Response:** 
```
I executed a visibility query for `ExecutionStatus="Failed"`. I found 3 failure records:
- 1. `WithdrawalWorkflow` (Run ID: fca1-4040). Failed at activity `ChargeCreditCard`.
- 2. `SendEmailWorkflow` (Run ID: acb2-2020). Panicked on line 78.
- 3. `OnboardUser` (Run ID: 19ba-3333). Timed out out. Would you like me to pull the full history sequence for any of these to debug?
```

**Prompt:** 
```
Explain the exact execution history for workflow 'GenerateInvoice-102'.
```

**Response:** 
```
Here is the summary of events for `GenerateInvoice-102` (Run ID: axd...).
[00:00:01] Workflow execution started.
[00:00:03] Activity `FetchTaxData` scheduled and completed successfully.
[00:00:08] Timer activated for 3 hours.
[03:00:08] Timer fired.
[03:00:10] Activity `SendPDF` failed with a 500 downstream error. Do you want to review the source code behind `SendPDF`?
```

**Prompt:** 
```
List all active schedules and tell me when the database backup is due.
```

**Response:** 
```
You have 2 schedules running:
1. `WeeklyReportQueue` (Runs every Monday at 9AM).
2. `DatabaseColdBackup` (Runs daily at Midnight UTC).
According to Temporal, the next execution for `DatabaseColdBackup` is scheduled to start in 5 hours and 14 minutes.
```

## Capabilities

### View Workflow Status
List all workflow runs, filtering by status (running, completed, failed) using `list_workflows`.

### Inspect Specific Runs
Pull detailed information for a single workflow execution with `get_workflow_details`.

### Debug Execution Failures
Get the full chronological sequence of events, activities, and signals using `get_workflow_history`.

### Search Complex Runs
Run advanced queries (like SQL) across your runs using Temporal Visibility syntax via `search_workflows`.

### Audit Namespace Settings
Check the configuration, retention periods, and metadata of your operational namespace with `get_namespace_details`.

### Monitor Scheduled Jobs
List all recurring workflows using `list_schedules` and predict their next run times.

## Use Cases

### The Failed Payment Run
A customer reports their payment failed. The agent uses `search_workflows` to filter for 'Payment' workflows with a 'Failed' status. Then, it runs `get_workflow_history` on the resulting ID, pinpointing that the failure occurred specifically at the 'ChargeCreditCard' activity. Problem solved.

### Auditing Namespace Drift
Platform Ops needs to ensure all development namespaces follow the same data retention rules. They call `get_namespace_details` for multiple namespaces, quickly confirming that every one has a 30-day limit set correctly. No manual checks needed.

### Checking Next Maintenance Window
The team needs to know when the nightly database backup runs. They ask the agent to run `list_schedules`. The server immediately returns the scheduled ID and calculates that the next execution starts in 4 hours, allowing them to prepare.

### Diagnosing a Stalled Pipeline
The data pipeline workflow hasn't updated. An engineer uses `list_workflows` to check status, finds an old run is 'Running', and then calls `get_workflow_details`. The details show the process timed out, allowing them to restart it immediately.

## Benefits

- Instant debugging: Instead of jumping into the Temporal UI, you can ask the agent to run `get_workflow_history` and immediately see every event that happened during a failure. That saves time.
- Targeted searching: Need to find all runs that failed last week? Use `search_workflows` with specific criteria (e.g., `Status="Failed"`) instead of manually filtering huge lists.
- Know your limits: Run `get_namespace_details` anytime to check the retention period or configuration metadata, making sure you stay compliant without logging into a separate console.
- Manage recurring jobs: Use `list_schedules` to get a clean overview of every scheduled workflow and see exactly when the next critical job (like a nightly backup) is due.
- Simple status checks: The `list_workflows` tool gives you a quick rundown of all active runs, letting you know if anything unusual—like an unexpected spike in failures—is happening right now.

## How It Works

The bottom line is: you talk to your AI agent like it's a dashboard, but the server does the heavy lifting by connecting directly to Temporal's core API.

1. Subscribe to the server, then enter your Temporal Address, Namespace, and API Key (or cert path).
2. Your AI client executes a command—for instance, 'Show me all failed payment workflows.'
3. The agent uses the appropriate tool (`search_workflows`) to query the cluster state and returns the actionable data set.

## Frequently Asked Questions

**How do I find a specific failed workflow using get_workflow_details?**
You first need the Run ID. Use `list_workflows` or `search_workflows` to find the correct Run ID, and then pass that ID to `get_workflow_details`. This gives you the high-level status before digging into history.

**Can I use search_workflows for anything other than failures?**
Yes. You can filter by any attribute Temporal tracks, like workflow type or start time. You must use the full Visibility Query syntax, which is what makes `search_workflows` powerful.

**Does get_namespace_details tell me about individual workflows?**
No. It only provides metadata *about* the namespace itself—stuff like its retention policy and configuration settings. Use `list_workflows` for actual workflow data.

**What's the difference between list_workflows and search_workflows?**
Simple: `list_workflows` gives you a raw, basic list of IDs and statuses in the namespace. `search_workflows` lets you apply complex filters (like finding all 'Payment' workflows that failed last week).

**How do I check if my scheduled job is running?**
First, run `list_schedules` to see the schedule name. Then, use `get_workflow_details` on a recent execution ID associated with that schedule to confirm its current operational status.

**Before running a complex query with `search_workflows`, how can I find out which attributes are available?**
Run `list_search_attributes` first. This tool returns every custom attribute defined in your namespace. Knowing these fields ensures your search syntax is correct and prevents failed queries.

**What specific configuration details does `get_namespace_details` reveal about the cluster?**
It provides essential metadata, including the configured retention periods for logs and the current operational status of the namespace. This helps you audit consistency across your distributed systems.

**When I use `get_workflow_history`, what does the returned data structure look like?**
The history returns a chronological sequence of events, including timestamps, activity names, and signal payloads. It doesn't just show status; it shows every step taken during execution.

**Can my AI agent debug a failed Temporal workflow run directly?**
Yes. Instead of browsing the Temporal UI to manually dissect the execution, feed the workflow ID directly to your AI agent. It can seamlessly fetch the entire event history, identify the exact panic line or activity timeout, and immediately suggest code fixes within your IDE.

**How complex can the visibility searches be via natural language?**
Very complex. Because your agent understands your codebase, you can ask 'Find all workflows of type ProcessPayment that failed in the last 2 hours'. The agent formulates the perfect SQL-like syntax for the backend, parses the matching pages, and surfaces exactly which transactions failed.

**Can it read scheduled jobs and Cron jobs configurations inside Temporal?**
Absolutely. You can request a list of all active schedules mapped to your namespace. Your agent unpacks JSON configurations, showing definitions of workflow recurrence, enabling you to detect missing crons without interrupting your workflow.