AI and MCP

Project Succession has three separate places where AI shows up. They are independent - you can use any one of them without the others.

The AI Assistant - a chat panel inside the editor that can read and edit your graphs. Studio plan and above.
The MCP server - Succession exposes itself as a Model Context Protocol server so external AI clients (Claude Desktop, Claude Code, Cursor, ChatGPT desktop) can drive it.
The AI Prompt node - a regular action node that calls a large language model as a step inside a running workflow.

The first two share the same machinery: both talk to the same set of 37 MCP tools. The third is unrelated - it is just an action in your graph.

The AI Assistant

Opening it

The assistant lives in the right sidebar, next to the Inspector. Click the AI Assistant tab.

You need a graph open in the work area. The assistant keeps one conversation per graph, so with no graph open the input reads “Open a graph to chat” and is disabled.

The feature requires a Studio plan or above. On lower plans the tab shows an upgrade panel instead of the chat.

Bring your own model

Succession ships no model and no API key. You point the assistant at an endpoint you control, in Settings - AI Assistant.

Two wire protocols are supported:

Protocol	Works with
`anthropic`	Anthropic Messages API
`openai-compatible`	OpenAI, Ollama, LM Studio, OpenRouter, vLLM, and anything else speaking the OpenAI chat-completions shape

Presets are provided for Anthropic, OpenAI, Ollama (local), LM Studio (local), OpenRouter, and a blank Custom entry. Each provider entry has:

Name - your label for it, and the id used to mark one provider active.
Protocol - one of the two above.
Base URL - for example https://api.anthropic.com or http://localhost:11434/v1.
API key - chosen from your vault keys, or “No API key (local endpoint)” for a local server that needs none. The key itself is never typed into this screen; you store it in the vault first (see the Settings guide) and pick it by name here.
Model - typed in, or picked from a list fetched from the endpoint with the download button.

Two buttons help you check a provider before you rely on it: Fetch model list queries the endpoint for the models it serves, and Test connection performs a minimal round trip and reports success or the exact error.

Pick one provider as active with the radio button. That is the one the assistant uses.

The model must support tool calling. A model without tool support will chat, but it will not be able to look at or change anything.

Keys are read from the vault at the moment a turn starts and sent only to the base URL you configured. Nothing is proxied through Succession’s servers.

What it can do

The assistant is connected to the same MCP tool surface documented below - all 37 tools. In practice that means it can:

Answer questions about the node palette without guessing, because it can read the real node definitions.
Read your deployed graphs and the last execution data per node, which makes it useful for debugging a pipeline that is misbehaving.
Build and edit graphs: create files, add nodes, wire ports, set parameters, validate, deploy.
Author custom Python nodes when nothing in the palette fits.
See what you have open in the editor - active graph, open tabs, current selection - and refresh the canvas after it edits a file on disk.

The system prompt tells it which graph you currently have open, and instructs it to work in small reviewable steps and to validate after substantial edits.

Tool approval

Every tool carries an approval tier derived from its MCP annotations. The assistant treats them differently:

Tier	Behaviour
Read-only	Runs automatically. Shown in the transcript as an auto-run card.
Write	Asks for approval. The approval card offers an Always allow `<tool>` checkbox, which persists that tool to your always-allowed list in Settings.
Destructive	Asks for approval every single time. No always-allow option. Marked with a warning in the card.
Unknown	Treated like destructive - asks every time.

Tools annotated destructive are the ones that remove or change running state: delete_node, delete_graph, delete_custom_node, deploy_graph, stop_graph, fire_trigger.

Each tool call is shown as an expandable card with the exact arguments it wants to use and, afterwards, the result it got back. Denying a call tells the model the user refused and not to retry.

Your always-allowed list is visible in Settings - AI Assistant, and you can revoke an entry there at any time.

During a turn

Model reasoning is streamed live when the provider emits it, shown above the input while the assistant is thinking.
Cancel stops the turn immediately, including while a tool approval is pending.
A turn is capped at 25 tool iterations. If the model is still calling tools after 25 rounds, the turn stops and says so.

History

Conversations are saved per graph and reloaded when you reopen that graph. They live outside your project, in your local application data directory under project_succession/chat_history, one file per graph. The trash button in the panel header clears the conversation for the current graph.

The MCP server

Succession’s running backend is itself a Model Context Protocol server. Any MCP-capable AI client can connect to it and use the same tools the built-in assistant uses.

How it is exposed

The MCP endpoint is mounted at /mcp on the backend’s own address - by default http://127.0.0.1:3000/mcp, configurable in Settings - Backend. It uses MCP’s Streamable HTTP transport.

It is protected by the same bearer token as the rest of Succession’s API, generated on first launch and stored in your system credential store. Requests without a valid token get a 401.

The server only exists while the Succession app is running. It goes down with the app.

For clients that speak stdio MCP rather than HTTP, Succession ships a bridge binary, succession_mcp_bridge, which is launched as a subprocess by the client and forwards every call to /mcp. It exposes exactly the same 37 tools.

Connecting a client

Claude Desktop (stdio) - edit the config file:

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

{
  "mcpServers": {
    "succession": {
      "command": "<path-to>/succession_mcp_bridge"
    }
  }
}

Restart Claude Desktop afterwards.

Claude Code (stdio):

claude mcp add succession <path-to>/succession_mcp_bridge

Cursor and other HTTP clients - no bridge needed:

{
  "succession": {
    "url": "http://127.0.0.1:3000/mcp",
    "headers": {
      "Authorization": "Bearer <YOUR_API_TOKEN>"
    }
  }
}

Finding the bridge binary

succession_mcp_bridge ships inside the Succession installation, alongside the main backend binary.

macOS: right-click Project Succession.app, Show Package Contents, then Contents/MacOS/succession_mcp_bridge
Windows: in the installation directory, under bin\ or next to the main executable
Linux (deb): typically /usr/lib/project-succession/succession_mcp_bridge
Linux (AppImage): inside the mounted AppImage

Finding your API token

HTTP clients need the bearer token. It lives in your operating system’s credential store under ProjectSuccession, in an entry named succession_api_token whose value is JSON containing a token field.

macOS: Keychain Access
Windows: Credential Manager
Linux: the system secret service (GNOME Keyring, KWallet, and so on)

In container and CI environments with no keyring, the token can instead be supplied through the SUCCESSION_API_TOKEN environment variable. The keyring always wins when both are present.

Tool reference

All 37 tools, with the approval tier the built-in assistant applies to them. External clients apply their own policy, but the annotations are the same over MCP.

Discovering the palette

Tool	Tier	What it does
`list_node_palette`	read-only	Every trigger and action with full schemas
`get_node_documentation`	read-only	One node type in detail - parameters, inputs, outputs
`suggest_node`	read-only	Rank node types against a free-form intent string

The palette is compiled into the backend, so these work regardless of where the app was launched from.

Inspecting graphs

Tool	Tier	What it does
`list_graphs`	read-only	Every deployed graph, including triggers whose start failed
`get_graph`	read-only	Full JSON of one deployed graph
`get_last_execution_data`	read-only	Most recent per-node execution data, optionally for one node
`list_secret_keys`	read-only	Names of configured secret keys - values are never returned
`validate_graph`	read-only	Lint report: unknown node types, missing required parameters, unconnected required inputs, orphan nodes

Editing graphs

Tool	Tier	What it does
`create_graph`	write	New empty graph file; fails if one already exists
`add_node`	write	Validates the node type against the palette, generates an id, auto-lays out when no position is given, writes atomically
`update_node`	write	Whitelisted fields only: `customProperties`, `parameterExpressions`, `position`, `label`, `nodeAlias`
`delete_node`	destructive	Deletes the node and cascades its edges
`connect`	write	New edge; rejects fan-in into an already-occupied target handle
`disconnect`	write	Remove an edge by id
`delete_graph`	destructive	Stops the graph if running, then deletes the file

Deploying and running

Tool	Tier	What it does
`deploy_graph`	destructive	Deploy a graph file into the running engine
`stop_graph`	destructive	Stop a deployed graph
`fire_trigger`	destructive	Inject a synthetic trigger event for testing

fire_trigger is wired through the MCP surface but not yet implemented in the live engine - calling it returns an error explaining this. It is tracked as a follow-up.

Subgraphs and loops

Tool	Tier	What it does
`create_subgraph`	write	New child file pre-wired with boundary nodes - SubgraphInput to SubgraphOutput, or GetIterator to LoopReturn
`set_subgraph_path`	write	Point a parent ExecSubgraph or ForLoop node at a child file, validating the boundary nodes and storing a relative path where possible
`expose_parameter`	write	Add an entry to a subgraph’s `exposedParameters` so the outer node renders a widget
`list_exposed_parameters`	read-only	Read a subgraph’s exposed parameters
`remove_exposed_parameter`	write	Remove one
`get_subgraph_chain`	read-only	Walk the composition tree from a parent graph, with cycle detection

Custom Python nodes

Tool	Tier	What it does
`validate_python_node_code`	read-only	Check candidate source without writing anything
`create_custom_python_node`	write	Validates the harness contract, then writes the `.py` file into your custom-nodes directory
`get_custom_node`	read-only	On-disk path and source of an existing custom node
`update_custom_node`	write	Replace the source; rejects `NODE_ID` renames
`delete_custom_node`	destructive	Refuses while any deployed graph still references the node

The file watcher picks up creates, updates, and deletes asynchronously, so a newly created node appears in the palette a moment after the tool returns.

Solutions and search

Tool	Tier	What it does
`list_solutions`	read-only	Recursively scan a directory for `.succsln` files
`get_solution`	read-only	One solution’s graphs, with deployed and executable flags
`search_graphs`	read-only	Search every deployed graph by text, node type, alias, or secret reference
`find_alias_usages`	read-only	Every `parameterExpression` referencing `@alias.param`, across all deployed graphs

search_graphs currently treats a solution scope as all_known and says so in its response.

Editor awareness

Tool	Tier	What it does
`get_active_graph`	read-only	Path of the graph shown in the work area
`get_open_tabs`	read-only	Open graph tabs, which is active, and which have unsaved changes
`get_selected_nodes`	read-only	Nodes currently selected on the canvas, as id, type, label, alias
`refresh_graph`	write	Reload a graph from disk in the editor so file edits become visible

These four require the Succession user interface to be running, not just the backend - they read a live channel fed by the editor. Without it they report that the UI is not connected.

refresh_graph will refuse rather than discard your work: if the editor has unsaved changes in that tab it returns unsaved_changes and leaves the canvas alone. Other outcomes are refreshed, not_open, failed, timeout, and not_connected.

Safety

A few properties are worth knowing about before you hand an AI client write access to your pipelines.

Secret values never leave the vault over MCP. list_secret_keys returns names only. No tool returns a secret value.
Filesystem access is gated by your path policy. Every MCP tool that takes a caller-supplied path is checked against the same allowed-paths policy that governs node execution. A tool asked to read or write outside it fails with a message telling you to add the path in Settings. The custom Python node tools are additionally confined to the app-managed custom-nodes directory by name validation.
The endpoint is local and token-protected. It binds to the backend address, which is loopback by default, and every request must carry the API token.
Approval is client-side. The built-in assistant enforces the read-only / write / destructive tiers described above. An external MCP client applies its own policy - most will prompt you before a write, but that is the client’s behaviour, not Succession’s. Treat an external client with full tool access the same way you would treat a shell.

The AI Prompt node

Separately from all of the above, the palette contains an AI Prompt action under the AI category. It calls a language model as a step inside a running workflow - useful for classifying a file, summarising a log, or generating text that a later node consumes.

Parameters:

Provider - OpenAI, Anthropic, or Google.
Model - the model identifier, for example gpt-4o, claude-sonnet-4-5, gemini-2.5-flash.
API Key (Vault) - the name of the vault key holding the key, for example OPENAI_API_KEY. Store the key in the vault first; see the Settings guide.
Prompt Template - the prompt. Placeholders in {key} form are filled from the value object of the incoming data.

Inputs and outputs:

input0 - execution signal, and the data used to fill the template. Optional.
output0 - the model’s text response, identified as ai_response.
output1 - fires instead on failure, carrying an error message identified as ai_error.

Because it fans out to a separate error output, you can wire a fallback path for a missing key, a rate limit, or a provider outage without failing the whole graph.

Requests go directly to the provider’s public endpoint. Unlike the AI Assistant, this node does not support custom base URLs, so it cannot be pointed at a local or self-hosted model.

Troubleshooting

The backend is not running. The MCP server lives inside the Succession app. Open the app.

MCP cannot authenticate. Restart Succession to regenerate the API token, then restart your AI client so it reconnects.

Tools do not appear in my client. Check the config file for malformed JSON - both Claude Desktop and Cursor fail silently on a bad config. Make sure the path to succession_mcp_bridge is absolute and points at the real binary.

The bridge will not launch. On macOS the first run of a downloaded binary may need a right-click Open to get past Gatekeeper. On Windows, Defender may quarantine it once. On Linux, check it is executable.

Tools return empty results. list_graphs and get_last_execution_data are empty until you have deployed and run a graph.

The editor-awareness tools say the UI is not connected. They need the Succession window open, not just the backend process.

The assistant says it cannot reach a tool. The assistant connects to the MCP endpoint through the same API token. If the backend was restarted mid-session, send another message to reconnect.

“Connection ok” but the assistant never calls a tool. The model probably does not support tool calling. Try a different model on the same endpoint.

A path was refused. Add the directory, or a parent of it, to the allowed paths in Settings.

Settings Guide - vault keys, backend address, allowed paths
Custom Python Nodes Guide - the harness contract the AI writes against
Subgraph Parameters Guide - what expose_parameter is manipulating
Graph Deployment Guide - what deploy_graph and stop_graph do