- Local MCP Server (
prometheux-mcp): Runs on your machine — works with Claude Desktop, Claude Code, Cursor, and any stdio-capable client. Recommended for coding agents. - Remote MCP Server (
px-remote-mcp-server): Cloud-hosted option that works with any MCP-compatible client via OAuth authentication - Built-in MCP Server (Snowflake Native App only): Automatically registered when the app starts — Cortex Agents and Snowflake Intelligence can discover Prometheux tools with no external setup. See the Native App guide for details.
What is MCP?
The Model Context Protocol allows AI agents to:- Discover available tools and resources
- Execute operations through a standardized interface
- Access external data sources and APIs
Which Option Should I Use?
- Local MCP Server
- Remote MCP Server
- Built-in (Native App)
Best for: Coding agents (Claude Code, Cursor), Claude Desktop, development environments, on-premise deploymentsPros:
- Simple pip install
- Runs locally (no external dependencies)
- Full control over credentials — no OAuth flow required
- Works with any Prometheux instance (cloud or on-premise)
- Compatible with Claude Desktop, Claude Code, Cursor, and any stdio-capable client
- Needs to be installed on each machine
- 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
Supported MCP Clients
We provide step-by-step connection guides for the following clients:Coding Agents (Local Server Recommended)
Chat & Enterprise Clients (Remote Server)
Don’t see your client? For stdio-capable clients (IDEs, terminal agents), use the Local MCP Server. For browser-based clients, the Remote MCP Server exposes a standard OAuth endpoint.
Available Tools
Both MCP servers dynamically expose the following tools to AI agents. The tool catalog is served by the Prometheux backend, so new capabilities are available automatically as they are added to the platform. Required parameters are shown in bold; the rest are optional.Most clients fetch the tool catalog once, when the connection opens, and cache it
for the rest of the session. If a tool starts rejecting a parameter that this
page documents, your client is probably holding an older copy of the schema —
reconnect to the server to pick up the current one.
Ontologies
Data sources
Workspace files
These tools work on the workspace disk — thedisk/ directory behind Data →
Files — which is where a file lives before connect_file_as_datasource turns it
into a data source.
find_disk_files is the one to reach for when the user names a file without a
path; list_disk_files is for browsing. A non-empty folder is only removed when
delete_disk_files is called with recursive: true. save_file_to_disk exists
because a file attached in chat is temporary and otherwise swept.
Concepts — read and run
Concepts — authoring
Freezing a concept
set_refresh_mode takes checkpoint to freeze or default to unfreeze. A frozen
concept keeps whatever output it last produced: nothing re-derives it while it is
reached as a dependency of something else, so the concepts below it in the chain
are not rebuilt either. Running the frozen concept directly still builds it, and a
run_mode: "all" run overrides the freeze.Use it for a concept whose inputs are gone or unreliable, one expensive enough
that its consumers should reuse the last result, or one holding a result that must
not move while work continues around it.Writing a concept
concept_type is one of logic (Vadalog), sql, cypher, python, context,
or llm, and defaults to logic. The body always goes in definition — a
Vadalog program, a query, a Python body, or an LLM prompt template, depending on
the type.context concepts are the exception: they have no body at all, and are
configured entirely through concept_config. llm concepts use definition
for the prompt and concept_config for the output columns and model settings.
See Context and LLM concepts.create_concept also guards against duplication: if a similar concept already
exists in another of your ontologies, the save is rejected with
similar_existing_concepts, and you re-issue the call with confirm_new: true
to proceed.Snapshots
restore_snapshot takes an automatic safety snapshot before it overwrites anything.
Schema
Apps
Call
get_app_schema before save_app — it returns the authoritative JSON Schema
for the app definition, along with the authoring guide.
Context Layer
Here
scope is the note’s own reach — global or project. kind is
preference or fact.
Skills
Compute machines
Note the two different identifiers:
machine_id is a catalogue id, used only by
start_machine, while user_machine_id identifies a machine already on your
list.
Databricks compute
An alternative to a Prometheux machine: point the workspace at a Databricks cluster and concepts run there instead. See Databricks compute for the concepts behind this.
Call
get_databricks_compute first — it reports what is already configured, so
only the missing fields need asking for. auth_mode picks between a personal
access token (token) and a service principal (client_id + client_secret),
which is what a shared or production workspace usually issues.
Waiting
This exists so an agent can sit out the gap when something it started needs time
— a cluster coming up, a machine booting, a long run finishing — instead of
either polling in a tight loop or handing the turn back to you.
Scheduled runs
trigger_type is either cron, whose config looks like
{"cron_expression": "0 6 * * *"}, or data_change, whose config looks like
{"check_interval_minutes": 30}.
Vadalog and company knowledge
Long-running tools
run_concept, ingest_document_as_context, and extract_concepts_from_document
advertise themselves as long-running through the prometheux/long_running hint
in tools/list, so clients can keep the connection alive and surface progress
instead of timing out.Example Usage
Once configured, just chat naturally with your AI agent. The agent will automatically use the Prometheux MCP tools when relevant. Example queries:“What ontologies do I have?”
“What concepts are available in my customer-analytics ontology?”
“Run the churn_prediction concept in the customer-analytics ontology”
“Write a concept that finds all transitive suppliers for a company”
“Summarise each supplier’s risk notes into a table of company, risk level, and reason”
“Create an app showing the results of churn_prediction”
“What does the Vadalog documentation say about recursive rules?”The AI agent will automatically:
- Call the appropriate Prometheux MCP tools
- Parse the results
- Present them in a readable format
- Answer follow-up questions about the data
Learn More
- MCP Protocol Specification: modelcontextprotocol.io
- Local MCP Server (GitHub): prometheuxresearch/px-mcp-server
- Local MCP Server (PyPI): prometheux-mcp
- Python SDK: See Python SDK Reference for alternative integration methods
- REST API: See REST API Reference for direct HTTP access
Related Resources
- Concepts API - Learn about the concept API
- Python SDK - Alternative programmatic access
- Chat API - Interactive AI chat interface

