Using the Plexus MCP Server

Connect AI assistants like Claude to your Plexus data and functionality using the Model Context Protocol (MCP) server.

What is MCP?

The Model Context Protocol (MCP) is an open standard designed by Anthropic that allows AI models, such as Claude, to securely interact with external tools and data sources. For an AI assistant, an MCP server acts as a gateway, enabling it to access and use capabilities from other systems. In the context of Plexus, this means you can empower an AI to work with your scorecards, evaluations, and reports directly. This allows for more dynamic and powerful ways to interact with your Plexus instance. For a deeper dive into the protocol itself, see the official Anthropic Model Context Protocol announcement.

Plexus MCP Server Overview

The Plexus MCP server is a pre-built tool that you can run on your system. Once running, it allows AI assistants that support MCP (like the Claude desktop app) to connect to your Plexus environment. This connection lets the AI perform various actions within Plexus on your behalf, such as listing scorecards, retrieving report details, or even initiating new evaluations. The server is typically run via a wrapper script (plexus_fastmcp_wrapper.py) which handles environment setup and ensures smooth communication with the AI client.

Getting the Server Code

To run the Plexus MCP server, you'll first need to obtain the server code. This is available in the main Plexus GitHub repository. You can clone or download it from: https://github.com/AnthusAI/Plexus. The necessary scripts (plexus_fastmcp_wrapper.py and plexus_fastmcp_server.py) are typically located at MCP/ within the repository. You will primarily need these files and to ensure their dependencies can be met in your Python environment.

Setting Up an MCP Client (e.g., Claude Desktop App)

To use the Plexus MCP server, you need an MCP client. For example, if you are using the Claude desktop application, you would configure it by creating or editing an mcp.json file. This file tells Claude (or another client) how to find and communicate with your running Plexus MCP server.

Here is an example configuration for your mcp.json file. You will need to replace the placeholder paths (/path/to/...) with the actual paths relevant to your system and where you have cloned the Plexus repository.

{
  "mcpServers": {
    "plexus-mcp-service": {
      "command": "/path/to/your/conda/envs/py311/bin/python",
      "args": [
        "/path/to/your/Plexus/MCP/plexus_fastmcp_wrapper.py",
        "--host", "127.0.0.1",
        "--port", "8002",
        "--transport", "stdio",
        "--env-file", "/path/to/your/Plexus/.env",
        "--target-cwd", "/path/to/your/Plexus/"
      ],
      "env": {
        "PYTHONUNBUFFERED": "1",
        "PYTHONPATH": "/path/to/your/Plexus"
      }
    }
  }
}

Key parts of this configuration:

  • command: The full path to the Python interpreter within your Plexus conda environment (e.g., py311).
  • args: Specifies the wrapper script to run (plexus_fastmcp_wrapper.py) and its parameters. The --host and --port arguments configure the local server settings. The --transport stdio argument is standard for client-server communication. The --env-file argument must point directly to your .env file (which contains API keys). The --target-cwd should point to your Plexus project root directory.
  • env.PYTHONPATH: Should point to the root of your Plexus project directory to ensure the server can find all necessary Python modules.

The location of the mcp.json file can vary depending on the client. For the Claude desktop app, consult its documentation for the correct location (often in a configuration directory within your user profile).

Available Tools & Capabilities

Once the Plexus MCP server is running (via the wrapper script) and your AI assistant is connected, you can instruct the assistant to use the following tools:

Scorecard Management

  • list_plexus_scorecards: Ask the AI to list available scorecards in your Plexus Dashboard. You can optionally tell it to filter by an account name/key, a partial scorecard name, or a scorecard key. For example: "List Plexus scorecards for the 'Sales' account that include 'Q3' in the name."
  • get_plexus_scorecard_info: Request detailed information about a specific scorecard. Provide the AI with an identifier for the scorecard (like its name, key, or ID). It will return the scorecard's description, sections, and the scores within each section. For example: "Get info for the 'Customer Satisfaction Q3' scorecard."
  • get_plexus_score_details: Get specific details for a particular score within a scorecard, including its configuration and version history. You'll need to specify both the scorecard and the score. You can also ask for a specific version of the score. For example: "Show me the details for the 'Responsiveness' score in the 'Support Tickets' scorecard, especially its champion version."

Evaluation Tools

  • run_plexus_evaluation: Instruct the AI to start a new scorecard evaluation. You need to provide the scorecard name and optionally a specific score name and the number of samples. The server will dispatch this task to your Plexus backend. Note that the MCP server itself doesn't track the progress; you would monitor the evaluation in the Plexus Dashboard as usual. For example: "Run a Plexus evaluation for the 'Lead Quality' scorecard using 100 samples."

Reporting Tools

  • list_plexus_reports: Ask for a list of generated reports. You can filter by account or by a specific report configuration ID if you know it. The AI will return a list showing report names, IDs, and when they were created. For example: "List the latest Plexus reports for the main account."
  • get_plexus_report_details: Retrieve detailed information about a specific report by providing its ID. This includes the report's parameters, output, and any generated blocks. For example: "Get the details for Plexus report ID '123-abc-456'."
  • get_latest_plexus_report: A convenient way to get the details of the most recently generated report. You can optionally filter by account or report configuration ID. For example: "Show me the latest report generated from the 'Weekly Performance' configuration."
  • list_plexus_report_configurations: Get a list of all available report configurations for an account. This is useful for knowing what reports you *can* generate. For example: "What report configurations are available for the 'Marketing' account?"

Utility Tools

  • think: A planning tool used internally by the AI to structure reasoning before using other tools. This helps the AI organize its approach to complex tasks that may require multiple steps or tool calls.

Environment Requirements for Running the Server

Software

  • Python 3.11 or newer (required by the fastmcp library the server uses).
  • An existing Plexus installation and access to its dashboard credentials.
  • The python-dotenv Python package (used by the server to load your API keys from the .env file).

.env File with Plexus Credentials

The server needs to access your Plexus API. Create a file named .env. The --env-file parameter in your mcp.json should point directly to this file. It's typically located in your main Plexus project root directory (e.g., Plexus/.env).

Required Variables in .env:

  • PLEXUS_API_URL: The API endpoint URL for your Plexus instance.
  • PLEXUS_API_KEY: Your API key for authenticating with Plexus.
  • PLEXUS_DASHBOARD_URL: The main URL of your Plexus dashboard (used for generating links).

Optional Variables in .env:

  • PLEXUS_ACCOUNT_KEY: If you work with multiple accounts, you can set a default account key here.
  • LOG_LEVEL: You can set this to DEBUG, INFO, WARNING, or ERROR to control the server's logging verbosity.

Running the Server

Once you have the code and your .env file is set up, you should run the server using the plexus_fastmcp_wrapper.py script as configured in your mcp.json file. The MCP client (e.g., Claude Desktop App) will execute the command specified in mcp.json when it attempts to connect to the "plexus-mcp-service".

You typically don't run the plexus_fastmcp_wrapper.py script manually from the terminal for client use. Instead, ensure your mcp.json is correctly configured, and the client application will start the server process as needed.

Make sure your Plexus Python environment (e.g., conda activate py311) is correctly referenced by the full path to python in the command field of your mcp.json. The wrapper script handles passing the necessary environment variables and paths to the underlying plexus_fastmcp_server.py.

Troubleshooting Common Issues

  • Connection Errors: Double-check all paths in your mcp.json file (command, args, env.PYTHONPATH). Ensure they accurately point to your Python executable, the plexus_fastmcp_wrapper.py script, your .env file, and your project directory.
  • Authentication Errors: Verify that the --env-file path in mcp.json correctly points to your .env file and that this file contains the correct PLEXUS_API_URL and PLEXUS_API_KEY.

Server Logs

The Plexus MCP server setup (via plexus_fastmcp_wrapper.py) directs operational logs and error messages to stderr. MCP clients like the Claude desktop app typically capture and display these stderr logs, or store them in a dedicated log file.

For instance, Cursor often stores MCP interaction logs in ~/Library/Logs/Claude/mcp.log on macOS. Monitoring this file is key for diagnosing issues if the client doesn't display them directly.