Local MCP Server - Prometheux

Connect any MCP-compatible AI agent to Prometheux using the Model Context Protocol (MCP) — an open standard that enables AI assistants to interact with external tools and data sources. The local MCP server (prometheux-mcp) runs on your machine and provides a simple, reliable way to integrate AI agents with your Prometheux ontologies. It works with Claude Desktop, Claude Code, Cursor, and any other client that supports MCP stdio servers.

Recommended for Coding AgentsWe recommend the local server for coding agents like Claude Code and Cursor. It uses stdio transport with direct credential configuration — no OAuth browser flow required — which makes it more reliable and easier to set up in development environments.

Why Use Local MCP?

Best for: Coding agents (Claude Code, Cursor), Claude Desktop, development environments, on-premise deployments Pros:

Simple pip install
Runs locally (no external dependencies)
Full control over credentials
Works with any Prometheux instance (cloud or on-premise)
No OAuth flow required — credentials are passed directly as environment variables
Compatible with any MCP client that supports stdio transport

Cons:

Needs to be installed on each machine

Use this when:

You’re using a coding agent (Claude Code, Cursor)
You’re using Claude Desktop
You want a simple, local installation
You’re developing or testing locally

Looking for a Browser-Based Client?If you want to connect from Claude Web, ChatGPT, Genie Code, or other browser-based clients, check out the Remote MCP Server and the Client Guides.

Quick Start

Prerequisites

Prometheux account with access to a deployed instance
Claude Desktop installed on your machine (download here)
Your credentials: token, username, and organization from your Prometheux admin

Installation

Automated (Recommended)
Manual Install

Easiest method - download and run our installation script:macOS/Linux:

curl -sSL https://raw.githubusercontent.com/prometheuxresearch/px-mcp-server/main/install.sh -o install.sh
chmod +x install.sh
./install.sh

Windows (PowerShell):

Invoke-WebRequest -Uri "https://raw.githubusercontent.com/prometheuxresearch/px-mcp-server/main/install.ps1" -OutFile "install.ps1"
.\install.ps1

The script will:

✅ Install pipx (if not already installed)
✅ Install prometheux-mcp package from PyPI
✅ Prompt for your credentials (URL, token, username, organization)
✅ Automatically configure Claude Desktop
✅ Create backups of existing configuration

Then just restart Claude Desktop and you’re ready!

Manual installation using pipx:pipx installs the package in an isolated environment and works reliably with Claude Desktop on all platforms.macOS:

brew install pipx
pipx ensurepath
pipx install prometheux-mcp

Windows:

pip install pipx
pipx ensurepath
pipx install prometheux-mcp

Linux:

pip install pipx
pipx ensurepath
pipx install prometheux-mcp

After installation, you’ll need to manually configure Claude Desktop (see Configuration section below).

Configuration

Automated InstallationIf you used the automated installation script, configuration was done automatically. Skip to the Usage section below.

For manual installations only:

1. Get Your Credentials

You’ll need:

Server URL (e.g., https://api.prometheux.ai or your on-premise URL)
Authentication token
Username
Organization

Contact your Prometheux admin or check your account settings for these credentials.

2. Configure Claude Desktop

Edit the Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

Configuration
With Debug Mode

{
  "mcpServers": {
    "prometheux": {
      "command": "/Users/YOUR_USERNAME/.local/bin/prometheux-mcp",
      "args": ["--url", "https://api.prometheux.ai"],
      "env": {
        "PROMETHEUX_TOKEN": "your_token_here",
        "PROMETHEUX_USERNAME": "your_username",
        "PROMETHEUX_ORGANIZATION": "your_organization"
      }
    }
  }
}

Finding Your PathRun this in your terminal to find the full path:

macOS/Linux: which prometheux-mcp
Windows: where prometheux-mcp (in PowerShell or Command Prompt)

Common paths after pipx install:

macOS: /Users/YOUR_USERNAME/.local/bin/prometheux-mcp
Windows: C:\\Users\\YOUR_USERNAME\\.local\\bin\\prometheux-mcp.exe
Linux: /home/YOUR_USERNAME/.local/bin/prometheux-mcp

Use double backslashes (\\) for Windows paths in JSON.

URL RoutingThe server automatically constructs the full API path using your username and organization: {url}/jarvispy/{organization}/{username}/mcp/messages

Custom or On-Premise URLsFor on-premise deployments or custom URLs, replace https://api.prometheux.ai with your own server URL:

"args": ["--url", "https://your-custom-domain.com"]

Add --debug flag to see detailed logs in Claude Desktop’s console:

{
  "mcpServers": {
    "prometheux": {
      "command": "/Users/YOUR_USERNAME/.local/bin/prometheux-mcp",
      "args": ["--url", "https://api.prometheux.ai", "--debug"],
      "env": {
        "PROMETHEUX_TOKEN": "your_token_here",
        "PROMETHEUX_USERNAME": "your_username",
        "PROMETHEUX_ORGANIZATION": "your_organization"
      }
    }
  }
}

Replace the command path with your actual path (see previous tab for how to find it).

3. Restart Claude Desktop

Completely quit Claude Desktop (Cmd+Q on macOS, or close from system tray) and reopen it. The MCP server will start automatically when Claude launches.

Configure Cursor

Cursor supports MCP servers via a mcp.json configuration file. You can configure it at the project level or globally.

Scope	Path
Project	`.cursor/mcp.json` (inside your project root)
Global	`~/.cursor/mcp.json` (your home directory)

Add the following configuration:

{
  "mcpServers": {
    "prometheux": {
      "command": "/Users/YOUR_USERNAME/.local/bin/prometheux-mcp",
      "args": ["--url", "https://api.prometheux.ai"],
      "env": {
        "PROMETHEUX_TOKEN": "your_token_here",
        "PROMETHEUX_USERNAME": "your_username",
        "PROMETHEUX_ORGANIZATION": "your_organization"
      }
    }
  }
}

After saving, go to Settings (Cmd+Shift+J) → Tools & MCP and toggle the server on. The tools will be available in new chat sessions.

Finding Your PathRun which prometheux-mcp (macOS/Linux) or where prometheux-mcp (Windows) to find the correct path for the command field.

Configure Claude Code

Claude Code (terminal CLI) supports adding MCP servers via the claude mcp add command. Add the server:

claude mcp add --scope user \
  -e PROMETHEUX_TOKEN='your_token_here' \
  -e PROMETHEUX_USERNAME='your_username' \
  -e PROMETHEUX_ORGANIZATION='your_organization' \
  -- prometheux /Users/YOUR_USERNAME/.local/bin/prometheux-mcp --url https://api.prometheux.ai

This registers the server globally (user scope). Restart Claude Code for the changes to take effect. Verify the connection:

claude mcp list

You should see prometheux listed as connected.

Managing the serverTo remove: claude mcp remove prometheuxTo list all servers: claude mcp list

Usage

Once configured, just chat naturally with your AI agent. The agent will automatically use the Prometheux MCP tools when relevant.

Example Conversations & Available ToolsSee the MCP overview page for example conversations and a complete list of available tools.

Troubleshooting

”command not found” or “Server disconnected” error

Claude Desktop can’t find the prometheux-mcp command. Solution:

Quick FixIf you used manual installation, try the automated installation script instead - it handles all path configuration automatically:

# macOS/Linux
curl -sSL https://raw.githubusercontent.com/prometheuxresearch/px-mcp-server/main/install.sh -o install.sh && chmod +x install.sh && ./install.sh

# Windows
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/prometheuxresearch/px-mcp-server/main/install.ps1" -OutFile "install.ps1"; .\install.ps1

Manual fix: macOS:

Find the full path: which prometheux-mcp
Use that full path in your config (usually /Users/YOUR_USERNAME/.local/bin/prometheux-mcp)
Restart Claude Desktop completely (Cmd+Q, then reopen)

Windows:

Find the full path: where prometheux-mcp (in PowerShell or Command Prompt)
Use that full path in your config with double backslashes (e.g., C:\\Users\\YOUR_USERNAME\\.local\\bin\\prometheux-mcp.exe)
Restart Claude Desktop

Linux:

Find the full path: which prometheux-mcp
Use that full path in your config (usually /home/YOUR_USERNAME/.local/bin/prometheux-mcp)
Restart Claude Desktop

GUI applications like Claude Desktop may not inherit your terminal’s PATH. Using the full path is more reliable than the short command.

”Connection refused” error

The MCP server can’t reach your Prometheux instance. Solution:

Verify your server URL is correct and accessible
Test the connection: curl https://your-server-url/mcp/info
Check if you’re behind a VPN or firewall that might block access
For on-premise installations, ensure the server is running

”Authentication failed” error

Your credentials are incorrect or expired. Solution:

Double-check your token, username, and organization in the config
Verify the credentials with your Prometheux admin
Ensure there are no extra spaces or quotes in the JSON config
Check if your token has expired and needs renewal

Claude doesn’t use the tools

Claude might not realize the tools are relevant to your query. Solution:

Be more explicit: “Use the prometheux tools to list concepts in project X”
Check Claude Desktop’s console for MCP errors (View → Developer → Toggle Developer Tools)
Enable debug mode in your config (--debug flag) and check logs
Verify the server is connected: look for the hammer icon in Claude Desktop

Advanced Usage

Using MCP Programmatically

You can also use the Prometheux MCP package as a Python library:

import asyncio
from prometheux_mcp.config import Settings
from prometheux_mcp.client import PrometheuxClient

async def main():
    # Configure connection
    settings = Settings(
        url="https://api.prometheux.ai",
        token="your_token",
        username="your_username",
        organization="your_org"
    )
    
    # Create client
    async with PrometheuxClient(settings) as client:
        # List concepts
        concepts = await client.list_concepts("project-123")
        print(f"Found {concepts['count']} concepts")
        
        # Run a concept
        result = await client.run_concept(
            project_id="project-123",
            concept_name="my_concept",
            force_rerun=True
        )
        print(f"Derived {result['total_records']} records")

asyncio.run(main())

Local Development

To test MCP locally with your development instance:

{
  "mcpServers": {
    "prometheux-local": {
      "command": "prometheux-mcp",
      "args": ["--url", "http://localhost:8000", "--debug"],
      "env": {
        "PROMETHEUX_TOKEN": "dev_token",
        "PROMETHEUX_USERNAME": "dev_user",
        "PROMETHEUX_ORGANIZATION": "dev_org"
      }
    }
  }
}

Learn More

MCP Protocol Specification: modelcontextprotocol.io
Local MCP Server (GitHub): prometheuxresearch/px-mcp-server
Local MCP Server (PyPI): prometheux-mcp
Remote MCP Server: See Remote MCP Server for Claude Web integration
Python SDK: See Python SDK Reference for alternative integration methods
REST API: See REST API Reference for direct HTTP access

Concepts API - Learn about the concept API
Python SDK - Alternative programmatic access
Chat API - Interactive AI chat interface

​Why Use Local MCP?

​Quick Start

​Prerequisites

​Installation

​Configuration

​1. Get Your Credentials

​2. Configure Claude Desktop

​3. Restart Claude Desktop

​Configure Cursor

​Configure Claude Code

​Usage

​Troubleshooting

​”command not found” or “Server disconnected” error

​”Connection refused” error

​”Authentication failed” error

​Claude doesn’t use the tools

​Advanced Usage

​Using MCP Programmatically

​Local Development

​Learn More

​Related Resources

Why Use Local MCP?

Quick Start

Prerequisites

Installation

Configuration

1. Get Your Credentials

2. Configure Claude Desktop

3. Restart Claude Desktop

Configure Cursor

Configure Claude Code

Usage

Troubleshooting

”command not found” or “Server disconnected” error

”Connection refused” error

”Authentication failed” error

Claude doesn’t use the tools

Advanced Usage

Using MCP Programmatically

Local Development

Learn More

Related Resources