Content
# Anzo MCP Extended
An extended MCP (Model Context Protocol) server for **Altair Graph Studio (AGS) / Anzo**, built on top of [`ags-mcp-server`](https://pypi.org/project/ags-mcp-server/) by RapidMiner/Siemens.
This extension adds full REST API coverage for graphmart/layer/step CRUD, dataset management, ACL management, ontology model management, pipeline execution, and in-flight query control — while retaining all original tools from the upstream package.
---
## What's New vs. Upstream (`ags-mcp-server`)
### Dual-Client Architecture
This server uses two complementary clients:
- **`pyanzo`** — for SPARQL journal queries, semantic services, and graphmart lifecycle operations
- **`ags_mcp.AnzoAPIClient`** — for REST API operations (`/api/...`) with built-in retry logic and structured error handling
### Additional Tools
#### Graphmart CRUD
| Tool | Description |
|------|-------------|
| `create_graphmart` | Create a new graphmart with title, description, and optional URI |
| `modify_graphmart` | Update title, description, or other properties of an existing graphmart |
| `delete_graphmart` | Permanently delete a graphmart and all its data |
#### Layer REST Operations
| Tool | Description |
|------|-------------|
| `retrieve_layer` | Get full details of a layer including steps and configuration |
| `modify_layer` | Update layer title, description, or enabled state |
| `delete_layer` | Delete a layer and all its steps and graph data |
| `retrieve_layer_status` | Get current status of a layer (loading, loaded, error) |
| `retrieve_layer_views` | List all views (virtual tables) defined in a layer |
| `create_layer_view` | Add a new view to a layer |
#### Step REST Operations
| Tool | Description |
|------|-------------|
| `create_or_replace_layer_step` | Create or fully replace a transformation step in a layer |
| `delete_layer_step` | Delete a specific step from a layer by both layer URI and step URI |
| `delete_step` | Delete a step directly by its URI |
| `retrieve_step_status` | Get step status including validation errors |
#### Dataset Management
| Tool | Description |
|------|-------------|
| `list_datasets` | List all datasets the current user can view |
| `get_dataset_info` | Get detailed information about a dataset including editions |
| `create_empty_dataset` | Create a new empty dataset at a specified location |
| `modify_dataset` | Update dataset properties |
| `delete_dataset` | Delete a dataset and its associated editions and components |
#### ACL Management
| Tool | Description |
|------|-------------|
| `retrieve_acls` | Get ACLs for any Anzo object (inherited and explicit) |
| `set_acls` | Set/replace ACLs for an object |
| `modify_acls` | Add or remove specific ACL statements |
#### Ontology Model Management
| Tool | Description |
|------|-------------|
| `retrieve_models` | List all ontology models available in AGS |
| `upload_model` | Upload an ontology file (TTL, RDF, TriG, etc.) to AGS |
| `delete_model` | Delete an ontology model from AGS |
#### Pipeline Execution
| Tool | Description |
|------|-------------|
| `run_pipeline` | Run an unstructured data pipeline |
| `cancel_pipeline` | Cancel a currently running pipeline |
| `retrieve_pipeline_status` | Get the status of a pipeline execution |
#### In-Flight Query Management
| Tool | Description |
|------|-------------|
| `get_inflight_queries` | List all currently executing queries (operation ID + datasource) |
| `cancel_all_inflight_queries` | Cancel every currently executing query |
#### AnzoGraph Cluster Management
| Tool | Description |
|------|-------------|
| `restart_anzograph` | Safely restart an AnzoGraph cluster: deactivates graphmarts, sends reload request, reactivates and waits for each graphmart to come back online |
---
## Installation
### From GitHub
```bash
pip install git+https://github.com/sbeisner/anzo_mcp_extended.git
```
### From source
```bash
git clone https://github.com/sbeisner/anzo_mcp_extended.git
cd anzo_mcp_extended
pip install -e .
```
---
## Configuration
The server reads credentials from environment variables. Create a `.env` file in the directory where you run the server (it is loaded automatically):
```env
# Used by pyanzo (SPARQL + semantic services)
PYANZO_DOMAIN=your-anzo-host.example.com
PYANZO_PORT=443
PYANZO_USER=sysadmin
PYANZO_PASSWORD=your-password
# Used by AnzoAPIClient (REST API)
ANZO_HTTP_BASE=https://your-anzo-host.example.com
ANZO_USERNAME=sysadmin
ANZO_PASSWORD=your-password
```
> **Note:** `PYANZO_DOMAIN` and `ANZO_HTTP_BASE` point to the same Anzo instance. Both sets of variables are required because each client has a different configuration format.
### SSL
SSL verification is disabled by default to support self-signed certificates, which is typical for on-premise Anzo deployments.
---
## Claude Desktop Setup
Add the following to your `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`):
```json
{
"mcpServers": {
"anzo": {
"command": "/path/to/your/venv/bin/python",
"args": ["-m", "anzo_mcp.server"],
"env": {
"PYANZO_DOMAIN": "your-anzo-host.example.com",
"PYANZO_PORT": "443",
"PYANZO_USER": "sysadmin",
"PYANZO_PASSWORD": "your-password",
"ANZO_HTTP_BASE": "https://your-anzo-host.example.com",
"ANZO_USERNAME": "sysadmin",
"ANZO_PASSWORD": "your-password"
}
}
}
}
```
Alternatively, if using a `.env` file, omit the `env` block and ensure the `.env` file is present in the server's working directory.
---
## Claude Code (CLI) Setup
Add to `~/.claude.json` under `mcpServers`:
```json
{
"mcpServers": {
"anzo": {
"command": "/path/to/your/venv/bin/python",
"args": ["-m", "anzo_mcp.server"]
}
}
}
```
With a `.env` file containing the credentials in the same directory.
---
## Anzo Version Compatibility
| Anzo Version | API Base Path | Notes |
|---|---|---|
| 5.4.15+ | `/api/` | Full feature support including in-flight query cancellation |
| 5.4.2+ | `/api/` | Default — no extra config needed; `get_inflight_queries` / `cancel_all_inflight_queries` not supported |
| 5.4.1 | `/api/v1/` | Use `api_version='v1'` in `GraphmartManagerApi` if using `pyanzo_interface` directly |
> **Note:** `get_inflight_queries` and `cancel_all_inflight_queries` require Anzo **5.4.15 or later**. The `/sparql/lds/` endpoint used to query system tables is not available in earlier versions.
---
## Dependencies
| Package | Purpose |
|---------|---------|
| [`pyanzo`](https://pypi.org/project/pyanzo/) | SPARQL queries, semantic services, graphmart lifecycle |
| [`ags-mcp-server`](https://pypi.org/project/ags-mcp-server/) | `AnzoAPIClient` for REST API with retry logic; base MCP tooling |
| [`mcp[cli]`](https://pypi.org/project/mcp/) | MCP server framework |
| `python-dotenv` | `.env` file loading |
| `pydantic` | Input validation |
---
## License
This project is an independent extension and is not affiliated with RapidMiner, Siemens, or Cambridge Semantics.
