Temporal Nexus MCP Example Server

A comprehensive sample application demonstrating how to bridge Model Context Protocol (MCP) tools with Temporal's Nexus RPC framework.

python

1

GitHub Stars

python

Language

6 months ago

First Indexed

2 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "steveandroulakis-temporal-nexus-mcp-demo": {
      "command": "uv",
      "args": [
        "run",
        "python",
        "-m",
        "nexus_mcp_calculator.mcp_server"
      ]
    }
  }
}

You can expose a calculator as MCP tools and connect them to Temporal Nexus so you get reliable, observable, and scalable tool executions. This guide walks you through using an MCP server that bridges calculator operations to Temporal Nexus workflows, giving you safe expressions, basic arithmetic, and aggregate functions as MCP tools guarded by Temporal’s fault tolerance.

How to use

Connect to the MCP server from your MCP client to discover calculator tools and invoke operations inside Temporal workflows. You can perform: expression evaluation, basic arithmetic, and list operations, all with full workflow visibility in Temporal UI. Each tool runs as a workflow-backed activity, so long-running calculations survive restarts and scale across workers.

How to install

Prerequisites: Python 3.13 or newer, a running Temporal server (local dev or Temporal Cloud), Temporal CLI, and familiarity with the MCP Python SDK to bridge MCP calls to Temporal workflows.

Step 1 — Install prerequisites and clone the project. Then install dependencies and prepare the environment.

Step 2 — Start infrastructure and endpoints. You will set up Temporal infrastructure and the Nexus bridge endpoints that connect MCP clients to the Temporal worker.

Step 3 — Run the calculator worker and the MCP server so MCP clients can call the calculator tools.

Configuration and usage notes

There are two main runtime components you start in parallel: the Calculator Worker and the MCP Server. The worker registers the Temporal workflows and activities that implement calculator operations. The MCP server exposes those operations as MCP tools and routes calls from MCP clients to the Temporal workflows.

Key commands used during setup and run are shown below. Use the exact commands to ensure the server and worker connect to the correct Temporal namespaces and Nexus endpoint.

Security considerations

The calculator uses AST parsing to safely evaluate expressions, preventing arbitrary code execution. Only allowed arithmetic operators, functions (abs, round, max, min, sum), and numeric constants are permitted. This minimizes risk when accepting user input.

Troubleshooting and notes

If you see issues connecting MCP to Temporal, verify both worker and MCP server are running and that the namespaces and Nexus endpoint names match across components. Use the Temporal UI to inspect workflow and activity executions for debugging and performance insights.

Tools exposed by MCP server

The MCP server automatically exposes the following calculator tools, backed by Temporal workflows and activities:

Available calculator tools

calculate — Evaluate mathematical expressions
add — Add two numbers
subtract — Subtract two numbers
multiply — Multiply two numbers
divide — Divide two numbers
power — Raise a number to a power
sum_list — Sum a list of numbers

Available tools

calculate

Evaluate mathematical expressions with safe AST parsing and return the result.

add

Add two numbers and return the sum.

subtract

Subtract the second number from the first and return the difference.

multiply

Multiply two numbers and return the product.

divide

Divide the first number by the second and return the quotient.

power

Raise the first number to the power of the second.

sum_list

Sum a list of numbers and return the total.