# Agent Tools
Source: https://mcp-docs.synta.io/agent-tools
Comprehensive guide to all Synta MCP tools and recommended workflow-building flow
Synta MCP provides 23 active tools for searching nodes, shortlisting recommended nodes, configuring them, finding templates, building workflows, validating them, and testing them against a live n8n instance. The recommended flow is to discover first, shortlist likely nodes second, configure with exact node definitions third, and only then create or update workflows.
## Getting Started with Agent Tools
**Phase 1: Discovery & Assessment**
For AI workflows, get patterns first. For standard workflows, search templates directly.
```
// AI Workflows: Get patterns FIRST
get_ai_workflow_patterns({mode: "list"})
// Standard Workflows: Search templates
search_templates({searchMode: "keyword", query: "slack notification"})
get_best_practices({mode: "list"})
```
Search for specific nodes you need in your workflow.
```
// First pass: lightweight discovery
search_nodes({queries: ["webhook"]})
search_nodes({queries: ["slack"], source: "core"})
// Second pass: only when you need resource/operation/mode details
search_nodes({queries: ["slack"], includeOperations: true})
```
**Phase 2: Planning**
Get detailed examples and best practices for your workflow type.
```
// Get template details
get_template({templateId: 123, mode: "full", includeMermaid: true})
// Get best practices for techniques
get_best_practices({mode: "detail", technique: "universal"})
get_best_practices({mode: "detail", technique: "notification"})
// Get curated node suggestions for the workflow category
get_suggested_nodes({categories: ["notification"]})
// Get node configuration examples
get_node({nodeIds: [{nodeId: "n8n-nodes-base.slack"}], view: "standard", includeConfigExamples: "json"})
```
**Phase 3: Implementation**
Deploy your workflow directly to n8n.
```
n8n_create_workflow({
name: "My Workflow",
nodes: [...],
connections: {...}
})
```
**Phase 4: Validation & Testing**
Check workflow structure and configure credentials.
```
n8n_validate_workflow({id: "wf-id"})
n8n_manage_credentials({mode: "check_workflow", workflowId: "wf-id"})
```
Execute and automatically fix runtime errors.
```
n8n_trigger_execution({id: "wf-id"})
// Analyzes errors, modifies config, re-executes until successful
```
**Phase 1: Discovery & Assessment**
Locate the workflow and understand its current structure.
```
// Find workflow by name
n8n_list_workflows({searchTerm: "slack", searchMode: "fuzzy"})
// Get workflow structure
n8n_get_workflow({id: "wf-id", mode: "structure"})
// Search within workflow
n8n_search_workflow({id: "wf-id", scope: "nodes", match_strategy: "regex", query: "HTTP"})
```
**Phase 2: Planning**
Find examples similar to your intended changes.
```
search_templates({searchMode: "by_nodes", nodeTypes: ["n8n-nodes-base.slack"]})
get_best_practices({mode: "detail", technique: "data_transformation"})
get_suggested_nodes({categories: ["data_transformation"]})
```
**Phase 3: Implementation**
Make incremental updates using diff operations.
```
n8n_update_partial_workflow({id: "wf-id", operations: [
{type: "addNode", node: {...}},
{type: "updateNode", nodeName: "Transform", updates: {"parameters.keepOnlySet": true}},
{type: "addConnection", source: "Webhook", target: "New Node"},
{type: "rewireConnection", source: "IF", from: "OldNode", to: "NewNode", branch: "true"}
]})
```
**Phase 4: Validation & Testing**
Verify your modifications are structurally correct.
```
n8n_validate_workflow({id: "wf-id", options: {validateConnections: true}})
n8n_autofix_workflow({id: "wf-id", applyFixes: true})
```
Execute the updated workflow and fix runtime issues.
```
n8n_trigger_execution({id: "wf-id"})
// If errors occur, analyzes and fixes automatically
```
Self-Healing: Synta MCP automatically tests workflows, detects runtime errors, and modifies configurations until successful execution. Requires N8N login credentials. See
Installation for setup.
## Tool Categories
`search_nodes` - Full-text search across nodes
`get_suggested_nodes` - Curated node shortlists by workflow category
`get_node` - Exact node definitions in `standard`, `summary`, or `raw` view
`search_templates` - Search 10,000+ templates
`get_template` - Get workflow JSON by ID
`n8n_deploy_template` - Deploy from n8n.io
`get_ai_workflow_patterns` - AI architectural patterns
`get_best_practices` - Technique guidance
`n8n_create_workflow` - Create workflows
`n8n_get_workflow` - Retrieve workflows by ID
`n8n_update_full_workflow` - Replace full workflow definitions
`n8n_update_partial_workflow` - Diff-based updates with typeVersion support
`n8n_list_workflows` - List all workflows
`n8n_validate_workflow` - Validate configs, connections, and expressions
`n8n_delete_workflow` - Permanently delete workflows
`n8n_trigger_execution` - Self-healing testing
`n8n_test_workflow` - External testing
`n8n_manage_executions` - Execution management
`n8n_manage_pindata` - Mock data for testing
`n8n_inspect_node_io` - Inspect node inputs and outputs
`n8n_search_workflow` - AST-based search
`n8n_autofix_workflow` - Auto-fix errors
`n8n_manage_credentials` - Manage credentials
## Complete Tool Reference
Search for n8n nodes by name or service. Use it in two passes: first for lightweight discovery, then again with `includeOperations=true` when you need discriminator details.
Array of search terms like `["slack"]`, `["gmail"]`, or `["openai embeddings"]`.
When `true`, includes resource / operation / mode discriminator details and ready-to-copy follow-up guidance for `get_node`.
Filter: all, core, community, verified
* First call `search_nodes({queries: ["slack"]})`
* Then call `search_nodes({queries: ["slack"], includeOperations: true})` only after you have found the node you want
* Then call `get_node(...)` with the exact discriminator values you selected
Get curated node recommendations for workflow technique categories like `chatbot`, `notification`, `document_processing`, or `scraping_and_research`.
Array of workflow categories to get suggestions for, for example `["chatbot"]` or `["notification", "triage"]`.
* Use this after identifying the workflow technique categories from the user request
* Treat the returned `patternHint` as a shortlist, not a complete workflow design
* Then call `search_nodes(...)` and `get_node(...)` for the exact nodes you plan to configure
Get exact node definitions for one or more nodes. Use `view="standard"` for the recommended authoring view, `view="summary"` for a quick JSON overview, and `view="raw"` for the complete raw schema.
Array of node request objects like `{nodeId: "nodes-base.httpRequest"}` or `{nodeId: "nodes-base.gmail", resource: "message", operation: "send"}`.
`standard`, `summary`, or `raw`
Include configuration examples: json, mermaid, or both
Append readable markdown docs for the requested node(s)
* Use `view="summary"` when you want a quick JSON overview of required fields, resources, and operations
* Use `view="standard"` before editing configuration
* For discriminator-based nodes, pass the exact `resource` / `operation` / `mode` from `search_nodes(..., includeOperations: true)`
Search through 10,000+ workflow templates with multiple search modes.
keyword, by\_nodes, by\_task, by\_metadata, patterns
For keyword mode: search text
For keyword mode: fields to include (id, name, description, author, nodes, views, created, url, metadata)
For by\_nodes mode: array of node types
For by\_task mode: ai\_automation, data\_sync, webhook\_processing, email\_automation, slack\_integration, data\_transformation, file\_processing, scheduling, api\_integration, database\_operations
For by\_metadata: simple, medium, complex
For by\_metadata: developers, marketers, analysts
For by\_metadata: filter by required service (e.g., "openai", "slack")
For by\_metadata: filter by category (e.g., "automation", "integration")
For by\_metadata: minimum setup time in minutes (5-480)
For by\_metadata: maximum setup time in minutes (5-480)
Max results (1-100)
Pagination offset
Get complete workflow JSON for a specific template by ID.
Template ID from n8n.io
nodes\_only, structure, full
Include a mermaid flowchart diagram of the workflow
Deploy a workflow template from n8n.io directly to your n8n instance with auto-fix.
Template ID from n8n.io
Custom workflow name (default: template name)
Remove credential references from nodes
Auto-apply fixes after deployment
Upgrade node typeVersions to latest supported
Get architectural patterns for workflows containing AI elements. Mandatory for workflows with AI components (agents, RAG, LLMs, vector stores, AI APIs). These patterns are authoritative blueprints that must be followed strictly.
list (browse all patterns), detail (get full documentation for specific pattern)
Pattern ID for detail mode (get IDs from list mode)
* **Primary source for AI workflows:** Call FIRST to establish topology before templates
* **Mandatory for:** Any workflow with AI Agent nodes, RAG systems, LLM processing, AI API calls
* **Pattern types:** ai\_simple, ai\_tools, rag\_ingest, rag\_query, multi\_agent, hybrid\_memory
* **After patterns:** Use search\_templates + get\_template for proven implementations
* Deviating from these patterns will result in broken AI workflows
Get best practices and implementation guidance for workflow techniques. Use alongside templates for complete workflow planning.
list (browse all techniques), detail (get full documentation for one technique)
For detail mode: one technique per call. Make multiple calls in parallel, always including `universal` plus the workflow-specific techniques you need.
* **Mandatory flow:** Call mode="list" FIRST, then make multiple mode="detail" calls
* **Always include:** `universal`
* **Provides:** Node selection rules, configuration tips, common pitfalls, recommended nodes
* **Use early:** Call during planning before building workflows
Create a new workflow in your N8N instance using adaptive validation and automatic sanitization. Workflows are created inactive by default.
Workflow name
Array of workflow nodes with id, name, type, typeVersion, position, parameters. Use full node type prefixes (`n8n-nodes-base.*` and `@n8n/n8n-nodes-langchain.*`).
Connections object. Keys are source node names
Optional workflow settings (execution order, timezone, error handling)
* Adaptive create mode is always used (validationMode is not exposed).
* Node parameters and metadata are auto-sanitized during create to prevent UI-breaking structures.
* If IDs are missing/duplicated, IDs can be auto-generated/de-duplicated and reported in the response.
* Creation can return partial success guidance (fix with `n8n_update_partial_workflow`, then re-run `n8n_validate_workflow`).
Retrieve a workflow by ID with different detail levels.
Workflow ID
full, details (with execution stats), structure, minimal
Exclude pinned data from response
List workflows with filtering and pagination. Returns minimal metadata (id/name/active/dates/tags). Check hasMore/nextCursor for pagination.
Number of workflows to return (1-100)
Pagination cursor from previous response
Filter by active/published status
Filter by tags (exact match)
Filter by project ID (enterprise feature)
Exclude pinned data from response
Filter workflows by name within current page. Increase limit or use cursor for more results.
Search mode: fuzzy=typo-tolerant (default), fulltext=prefix/token matching
Exclude archived workflows from results
Update workflows incrementally with diff operations. Supports 17 operation types: addNode, removeNode, updateNode, moveNode, enable/disableNode, addConnection, removeConnection, rewireConnection, cleanStaleConnections, replaceConnections, updateSettings, updateName, add/removeTag, publishWorkflow, deactivateWorkflow. TypeVersion changes via updateNode are automatically validated with guidance. Supports smart parameters (branch='true'/'false' for IF nodes, case=N for Switch nodes) and AI connections.
Workflow ID to update
Array of diff operations to apply sequentially
Only validate operations without applying
Optional: create a backup/snapshot before applying operations.
Execution strategy: `best_effort` (recommended/default), `atomic`, or `auto`.
Deprecated legacy flag. Use `executionMode` instead.
Optional intent text used to improve guidance and auto-mode behavior.
* addNode, removeNode, updateNode, moveNode
* enableNode, disableNode
* addConnection, removeConnection, rewireConnection
* cleanStaleConnections, replaceConnections
* updateSettings, updateName
* addTag, removeTag
* publishWorkflow, deactivateWorkflow
For connections, use sourceOutput/targetInput for connection TYPE names (e.g., "main", "ai\_tool"), NOT numeric indices. For multi-output nodes (IF, Switch), use branch/case or sourceIndex.
* **sourceOutput**: Connection type (default: "main"). AI types: ai\_languageModel, ai\_tool, ai\_memory, etc.
* **targetInput**: Target input type (default: "main")
* **branch**: For IF nodes: "true" or "false" instead of sourceIndex
* **case**: For Switch nodes: case number (0-based) instead of sourceIndex
* **sourceIndex/targetIndex**: Explicit indices (override branch/case)
Replace an entire workflow with new configuration. For incremental updates, use `n8n_update_partial_workflow` instead.
Workflow ID to update
New workflow name
Complete array of workflow nodes
Complete connections object
Workflow settings to update
Permanently delete a workflow. This action cannot be undone.
Workflow ID to delete
Validate workflow configuration, connections, and expressions. When execution data exists, also performs runtime expression checks and reports actionable fixes.
Workflow ID to validate
Validate node configurations
Validate workflow connections
Validate n8n expressions
minimal, runtime, ai-friendly, strict
Search within a workflow to find nodes, connections, flow patterns, or text. Use regex matching by default for flexible substring search, exact for strict equality, or fuzzy for typo tolerance. Returns matching nodes with configurable detail levels.
Workflow ID to search within
What to search: nodes, connections, flow, text, comprehensive
regex (default - flexible substring matching), exact (strict equality), fuzzy (typo-tolerant)
Search term. String or object with name/type/path/value. Flow patterns: "A->B->C" (use .\* for any node)
Filter by node type
Target node name (connections scope)
Filter by disabled status
Parameter filter: path, value, exists properties
Limit text search to specific fields (text scope only)
Output verbosity: minimal, standard, full
* **regex** (RECOMMENDED): Grep-like substring matching, case-insensitive. Finds "set" in "offset" or "reset"
* **exact**: Strict equality only. Use when "set" should NOT match "reset"
* **fuzzy**: Typo-tolerant for user errors. "slak" matches "Slack"
* **nodes**: Search by node name or type
* **connections**: Find links between nodes
* **flow**: Search execution paths (e.g., "Webhook->Code->Slack")
* **text**: Ripgrep-like regex search across all node data
* **comprehensive**: Multi-criteria search with filters
Automatically fix common workflow validation errors. Preview fixes before applying. Handles expression format, typeVersion corrections, error output config, node types, webhook paths, version migrations, and parameter locations.
Workflow ID to fix
Apply fixes to workflow (default: false - preview mode)
Types of fixes: expression-format, typeversion-correction, error-output-config, node-type-correction, webhook-missing-path, typeversion-upgrade, version-migration, parameter-location (default: all)
Minimum confidence level: high, medium (default), low
Maximum number of fixes to apply
* **expression-format**: Fix n8n expression syntax issues
* **typeversion-correction**: Correct node typeVersion mismatches
* **error-output-config**: Fix error workflow configurations
* **node-type-correction**: Update deprecated node types
* **webhook-missing-path**: Add missing webhook paths
* **typeversion-upgrade**: Upgrade nodes to latest supported versions
* **version-migration**: Handle parameter migrations between versions
* **parameter-location**: Fix misplaced parameters in node structure
The most powerful tool in Synta MCP. Triggers workflows and enables true AI self-healing by automatically testing, detecting errors, analyzing root causes, and modifying configurations to fix issues. Works with n8n\_manage\_pindata for comprehensive testing.
Workflow ID to execute
Specific trigger node name to use (optional). If not specified, uses the first trigger node in the workflow.
Message for Chat Trigger nodes
Session ID for chat triggers only (optional, auto-generated if not provided)
Form field values for Form Trigger nodes (e.g., field-0: value, field-1: 2003-05-21)
JSON payload for webhook triggers (request body)
Custom HTTP headers for webhook/form requests
Max seconds to wait for completion
Include execution output data
Include full error stack trace in error details
Partial execution target. Use `mode: "exclusive"` to run upstream nodes without running the destination (like n8n's "Execute previous nodes"), or `mode: "inclusive"` (default) to run the destination too.
Target node name in the workflow
exclusive (run previous nodes only) or inclusive (run destination too)
* **Auto-detection**: Identifies Manual, Chat, Webhook, and Form triggers automatically
* **Error analysis**: AI analyzes execution results to identify root causes
* **Self-correction**: Modifies workflow configurations to fix detected issues
* **Full debugging**: Complete execution data including all node outputs
* **Webhook handling**: Automatically polls and calls webhook URLs when needed
* **Mock data integration**: Works with n8n\_manage\_pindata to test workflows using saved mock data instead of live API calls
External workflow testing without login credentials. Test workflows with webhook, form, or chat triggers. Workflow must be active.
Workflow ID to execute
webhook, form, chat (auto-detected if not specified)
GET, POST, PUT, DELETE (default: auto-detected from webhook config)
Override the webhook path
JSON payload for webhook triggers (request body)
Form field values for form triggers. Keys: field-0, field-1, etc.
Message for chat triggers
Session ID for chat triggers only (optional, auto-generated if not provided)
Custom HTTP headers for webhook/form requests
Timeout in milliseconds
Wait for workflow completion
Auto-fetch and return the latest execution after trigger (recommended — avoids a separate n8n\_manage\_executions call)
Detail level when returnExecution=true: summary (token-efficient) or full (complete payload)
Comprehensive execution management with advanced correlation to trace execution chains. Use `action: "get"` with `workflowId` (no id) to fetch the latest execution for a workflow.
get, list, delete, retry, correlate
Execution ID (for get, delete, retry). Omit with action=get + workflowId to get the latest execution.
For get: preview, summary, filtered, full, error
For get: include input data in addition to output
For get with mode=filtered: items per node (0=structure, 2=default, -1=unlimited)
For get with mode=filtered: filter to specific nodes by name
For get with mode=error: include full stack trace
For get with mode=error: include execution path leading to error
For get with mode=error: sample items from upstream node (max: 100)
For get with mode=error: fetch workflow for accurate upstream detection
For list: filter by workflow
For list: success, error, waiting
For list: number of executions (1-100)
For list: pagination cursor from previous response
For list: filter by project ID (enterprise feature)
For list: include execution data
For retry: whether to load the workflow definition
For correlate: starting execution ID
For correlate: time window in milliseconds
* **Webhook path matching**: Find executions triggered by HTTP calls
* **User context matching**: Correlate by user\_id, chat\_id, correlation\_id
* **Timing analysis**: Find executions within configurable time window
* **Sub-workflow detection**: Identify executeWorkflowTrigger patterns
Save and reuse mock data for testing workflows. Instead of calling real APIs or waiting for webhooks, save sample output from any node and reuse it in future test runs. Especially useful for triggers (webhooks, forms) but works with any node for consistent testing without external dependencies.
**Authentication:** `analyzePinDataRequirement` works with API key/OAuth only. CRUD operations (add/update/remove/clear/read) require login credentials.
analyzePinDataRequirement, addPinData, updatePinData, removePinData, clearPinData, readPinData
Workflow ID
Node name to save mock data for (required for add/update/remove modes)
Array of mock data items to save (for add/update modes)
Optional checksum for conflict detection
Mark update as autosaved (optional)
Flag to mark AI-assisted updates (optional)
Bypass checksum mismatch (optional)
* Test webhook/form triggers without sending real HTTP requests
* Avoid hitting API rate limits during development
* Use the same test data every time for consistent results
* Skip slow external API calls while building your workflow
* Test error scenarios with custom mock data
Inspect post-execution node input/output data. Use after any execution to debug expression errors, verify data shapes, or understand branch routing (IF/Switch outputs). Defaults to schema-style output (field/type shape) to keep context small.
Execution ID to inspect. Omit to use workflowId instead.
Workflow ID shortcut — auto-resolves the latest execution for this workflow.
Single node name to inspect (exact workflow node name)
Multiple node names to inspect. Omit to inspect all executed nodes.
Run selection: `latest`, `latestN`, `all`, or `indices`
For `runMode="indices"`: specific 0-based run indices to inspect
For `runMode="latestN"`: how many recent runs to include
Single 0-based output index filter, useful for IF/Switch branches
schema (compact field/type shape) or full (raw item values)
summary (counts/structure) or detail (full item payloads)
Filter IF/Switch branches by 0-based output index
Filter by connection type (main, ai\_tool, ai\_memory, ai\_languageModel, etc.)
Include input analysis (source lineage and/or inputOverride)
Include node outputs
Input analysis mode: `source`, `inputOverride`, or `both`
How items are sampled from each input/output collection: `firstN`, `lastN`, `all`, or `range`
For `firstN` and `lastN`: number of items to include (max 1000)
For `itemsMode="range"`: inclusive start index
For `itemsMode="range"`: exclusive end index
Include binary payload metadata and content references
Include paired item lineage metadata for each item
Include run metadata such as status, execution time, and errors
0-based node pagination page for large executions
Number of nodes per page (1-200)
0-based run pagination page within each selected node
Number of runs per page (1-200)
0-based item pagination page inside each inspected collection
Items per page inside each inspected collection (1-1000)
Include pagination metadata in the response. Defaults to `true` when pagination is used.
Fetch workflow metadata to enrich node type and typeVersion when execution payloads are incomplete
Append lightweight node context such as parents, children, counts, classification, and execution-presence flags
When `includeContext=true`, include workflow node parameters for inspected nodes
When `includeContext=true`, include the latest normalized runData entry for each inspected node
Mirror n8n NDV input preview using static upstream schemas without execution data. Requires `workflowId` and only works for previewable contexts.
* Use `workflowId` as a shortcut when you want the latest execution for a workflow.
* Use `n8n_trigger_execution` with `destinationNode` first if you need missing input data populated for downstream nodes.
* Start with `valueMode="schema"` and switch to `full` only when raw values are necessary.
* `staticPreview` mirrors n8n’s editor preview and is best for Gmail -> Set, Telegram -> Switch, and similar previewable paths.
* `includeContextParameters` and `includeContextRunData` only apply when `includeContext=true`.
Manage n8n credentials with five modes: get\_credential\_docs, create, delete, get\_schema, check\_workflow.
get\_credential\_docs, create, delete, get\_schema, check\_workflow
Credential name (for create)
Credential type e.g., "httpBasicAuth", "gmailOAuth2Api" (for create)
Credential data with type-specific fields (for create)
Credential ID (for delete)
Credential type name (for get\_schema or get\_credential\_docs)
Node type to fetch credential docs for (for get\_credential\_docs when credentialTypeName not provided)
Workflow ID to analyze (for check\_workflow)
## Next Steps
Learn tips and tricks for building better workflows with AI
Set up client-specific rules for optimal workflow building
Production Safety: Always test workflows in a development environment before deploying to production. Never edit production workflows directly without backups.
# Best Practices
Source: https://mcp-docs.synta.io/best-practices
Tips and tricks for building better n8n workflows with AI
Get the most out of Synta MCP with these proven strategies for workflow building, debugging, and optimization.
## Workflow Building Strategies
In Cursor/Claude Code, use plan mode to break down complex workflow tasks into smaller, manageable steps before implementation.
Split large workflow projects into smaller tasks: node discovery → validation → building → testing. This improves accuracy and makes debugging easier.
Specify exact node names, operations, parameters, and expected behavior. Clear, detailed requirements lead to better workflows and fewer iterations.
Use `search_nodes({queries: ["your-node"]})` to find nodes (core & community) quickly.
## Discovery & Research
Start with a broad search to discover available nodes:
```
search_nodes({queries: ["email"]})
```
After you find the node you want, call `search_nodes(..., includeOperations: true)` if you need to see whether it exposes `resource`, `operation`, or `mode`. Use `get_node` with `includeConfigExamples: "json"` when you want real-world configurations.
Once you've identified a node, get its full property documentation:
```
get_node({nodeIds: [{nodeId: "n8n-nodes-base.gmail"}], view: "standard"})
```
Use `view: "standard"` before editing configuration. If `search_nodes(..., includeOperations: true)` returned `resource`, `operation`, or `mode`, include those exact values in `get_node(...)`.
Look for proven patterns in the template library:
```
search_templates({searchMode: "by_nodes", nodeTypes: ["n8n-nodes-base.gmail"]})
```
Templates show real-world implementations you can learn from or deploy directly.
Template-first approach: Before building from scratch, check if a template exists. Templates are production-tested and save significant development time.
## Validation & Testing
Run validation to catch configuration errors:
```
n8n_validate_workflow({id: "your-workflow-id"})
```
This checks node configurations, connections, and expressions.
Use autofix to automatically resolve common problems:
```
n8n_autofix_workflow({id: "your-workflow-id", applyFixes: true})
```
Preview fixes first with `applyFixes: false` (default).
Run the workflow with self-healing enabled:
```
n8n_trigger_execution({id: "your-workflow-id"})
n8n_manage_pindata({mode: "addPinData", id: "your-workflow-id", nodeName: "Webhook", pinData: [...]})
```
AI automatically detects errors and modifies configurations to fix them. Use mock data to test without real webhooks or API calls.
Production Safety: Always test workflows in a development environment before deploying to production. Never edit production workflows directly without backups.
## Debugging Workflows
When things go wrong, use these tools to debug:
List recent executions to find failures:
```
n8n_manage_executions({action: "list", workflowId: "your-id", status: "error"})
```
Retrieve detailed error information:
```
n8n_manage_executions({action: "get", id: "execution-id", mode: "error"})
```
This includes the execution path leading to the error and upstream node data.
For complex systems with multiple workflows:
```
n8n_manage_executions({action: "correlate", executionId: "starting-execution-id"})
```
This traces execution chains across workflows using webhook path and timing analysis.
## Quick Reference
| Task | Tool | Key Parameters |
| ------------------- | ----------------------- | ------------------------------------------ |
| Find nodes | `search_nodes` | `queries`, `includeOperations`, `source` |
| Shortlist nodes | `get_suggested_nodes` | `categories` |
| Get node info | `get_node` | `nodeIds`, `view`, `includeConfigExamples` |
| Find templates | `search_templates` | `searchMode`, `query`, `nodeTypes` |
| Create workflow | `n8n_create_workflow` | `name`, `nodes`, `connections` |
| Validate | `n8n_validate_workflow` | `id` |
| Auto-fix | `n8n_autofix_workflow` | `id`, `applyFixes` |
| Test (self-healing) | `n8n_trigger_execution` | `id` |
| Test (external) | `n8n_test_workflow` | `workflowId` |
| Debug | `n8n_manage_executions` | `action`, `id`, `mode` |
| Mock data | `n8n_manage_pindata` | `mode`, `id`, `nodeName` |
## Next Steps
See the complete reference for all 23 active Synta MCP tools
Set up client-specific rules for optimal workflow building
# Installation
Source: https://mcp-docs.synta.io/installation
Install and configure Synta MCP for your AI client
## Choose Your Setup Method
Synta MCP supports two authentication methods:
**Easy setup** - One-click install with automatic credential sync
**Requirements:**
* A Synta account at [synta.io](https://synta.io)
* Your n8n instance setup in your Synta account
* A **paid Claude plan** (Pro, Team, or Enterprise)
For free plan users, see **API Key** installation.
**Full control** - Manual credential management
Works on **all Claude plans**, but only in the **desktop app**.
**Requirements:**
* [Node.js 16+](https://nodejs.org/en/download) installed
* Synta API Key from [synta.io/mcp](https://synta.io/mcp)
* Your n8n instance URL and API key
### How to Get These Details
1. Go to [synta.io](https://synta.io)
2. Click **Continue with Google** to sign up or log in
3. Complete the onboarding to configure your n8n instance URL and API key (and optionally login email and password for self-healing)
4. Your credentials are now stored securely for OAuth access
Your n8n instance must be publicly accessible (e.g., `https://your-instance.app.n8n.cloud`). Localhost URLs are not supported.
Download and install Node.js 16 or higher from [nodejs.org](https://nodejs.org/en/download).
Verify installation:
```bash theme={null}
node --version
```
1. Go to [synta.io/mcp](https://synta.io/mcp)
2. Sign up or log in
3. Navigate to the API Keys section
4. Create a new API key and copy it
**n8n Instance URL:**
Your publicly accessible n8n URL (e.g., `https://your-instance.app.n8n.cloud`)
**n8n API Key:**
1. Open your n8n instance and log in
2. Go to **Settings** → **n8n API**
3. Click "Create an API Key", give it a label, and click "Create"
4. Copy and save the key (you won't see it again!)
Localhost URLs are not supported. Your n8n instance must be publicly accessible.
For AI-driven workflow testing and self-healing capabilities, you can optionally add your n8n login credentials:
* **Login Email**: Your n8n account email
* **Login Password**: Your n8n account password
This enables advanced tools:
* **`n8n_trigger_execution`**: Execute workflows directly, detect errors, and automatically fix issues
* **`n8n_manage_pindata`** CRUD operations: Add/update/remove/clear pin data for testing workflows
## Configuration by Client
Select your AI client below:
OAuth provides automatic credential sync from your Synta account.
One-Click Install
Recommended
Click the button to add Synta MCP to Cursor automatically:
Go to **Cursor** → **Settings** → **Cursor Settings** → **Tools & MCP**
Click on **"New MCP Server"** and add the configuration below:
```json theme={null}
{
"mcpServers": {
"synta-mcp": {
"url": "https://mcp.synta.io/mcp"
}
}
}
```
When Cursor connects, it will open your browser for OAuth. Log in with the **same account** you used at [synta.io](https://synta.io).
Use API keys for manual credential management. Requires [Node.js](https://nodejs.org/en/download).
One-Click Install
Recommended
Click the button, then edit to add your credentials:
After installing, edit the config to replace `YOUR_SYNTA_API_KEY`, `YOUR_N8N_URL`, and `YOUR_N8N_API_KEY`.
Go to **Cursor** → **Settings** → **Cursor Settings** → **Tools & MCP**
Click on **"New MCP Server"**, add the configuration below and save the file:
```json theme={null}
{
"mcpServers": {
"synta-mcp": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://mcp.synta.io/mcp",
"--header",
"X-Synta-Api-Key: YOUR_SYNTA_API_KEY",
"--header",
"X-N8n-Url: YOUR_N8N_URL",
"--header",
"X-N8n-Key: YOUR_N8N_API_KEY"
]
}
}
}
```
* `YOUR_SYNTA_API_KEY` - Get from [synta.io/mcp](https://synta.io/mcp)
* `YOUR_N8N_URL` - Your n8n instance URL
* `YOUR_N8N_API_KEY` - Your n8n API key
Add n8n login credentials for AI-driven workflow testing:
```json theme={null}
{
"mcpServers": {
"synta-mcp": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://mcp.synta.io/mcp",
"--header",
"X-Synta-Api-Key: YOUR_SYNTA_API_KEY",
"--header",
"X-N8n-Url: YOUR_N8N_URL",
"--header",
"X-N8n-Key: YOUR_N8N_API_KEY",
"--header",
"X-N8n-Login-Email: YOUR_EMAIL",
"--header",
"X-N8n-Login-Password: YOUR_PASSWORD"
]
}
}
}
```
**Self-Healing Benefits:**
* Enables `n8n_trigger_execution` - execute workflows and auto-fix errors
* Enables `n8n_manage_pindata` CRUD operations - add/update/remove/clear pin data for testing
* Full execution data for debugging
OAuth works on both the Desktop app and Claude.ai website, and provides automatic credential sync from your Synta account.
Go to **Settings** → **Connectors** → **Add custom connector**
**Name**:
```text theme={null}
synta-mcp
```
**Remote MCP server URL**:
```text theme={null}
https://mcp.synta.io/mcp
```
Log in with the **same account** you used at [synta.io](https://synta.io). Your n8n credentials are fetched automatically.
API key authentication only works in the **Claude Desktop app**. Requires [Node.js](https://nodejs.org/en/download).
**Via Claude Desktop UI:**
* Go to **Claude** → **Settings** → **Developer** → **Edit Config**
```json theme={null}
{
"mcpServers": {
"synta-mcp": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://mcp.synta.io/mcp",
"--header",
"X-Synta-Api-Key: YOUR_SYNTA_API_KEY",
"--header",
"X-N8n-Url: YOUR_N8N_URL",
"--header",
"X-N8n-Key: YOUR_N8N_API_KEY"
]
}
}
}
```
* `YOUR_SYNTA_API_KEY` - Get from [synta.io/mcp](https://synta.io/mcp)
* `YOUR_N8N_URL` - Your n8n instance URL
* `YOUR_N8N_API_KEY` - Your n8n API key
Add n8n login credentials for AI-driven workflow testing:
```json theme={null}
{
"mcpServers": {
"synta-mcp": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://mcp.synta.io/mcp",
"--header",
"X-Synta-Api-Key: YOUR_SYNTA_API_KEY",
"--header",
"X-N8n-Url: YOUR_N8N_URL",
"--header",
"X-N8n-Key: YOUR_N8N_API_KEY",
"--header",
"X-N8n-Login-Email: YOUR_EMAIL",
"--header",
"X-N8n-Login-Password: YOUR_PASSWORD"
]
}
}
}
```
**Self-Healing Benefits:**
* Enables `n8n_trigger_execution` - execute workflows and auto-fix errors
* Enables `n8n_manage_pindata` CRUD operations - add/update/remove/clear pin data for testing
* Full execution data for debugging
Save the file and restart Claude Desktop.
OAuth provides automatic credential sync from your Synta account.
Run this command in your terminal:
```bash theme={null}
claude mcp add --transport http --scope user synta-mcp https://mcp.synta.io/mcp
```
Start Claude Code in your terminal:
```bash theme={null}
claude
```
Inside Claude Code, type this command and press Enter:
```
/mcp
```
You should see `synta-mcp` with a `⚠️ needs authentication` message next to it. Navigate to it, press Enter, then select `Authenticate` and press Enter again. Claude Code will open a browser window. Log in with the **same account** you used at [synta.io](https://synta.io).
After login, you should see: `✓ Authentication successful. Connected to synta-mcp.`
Verify the server is authenticated by running:
```
/mcp
```
Use API keys for manual credential management. Requires [Node.js](https://nodejs.org/en/download).
```bash macOS/Linux theme={null}
claude mcp add --scope user synta-mcp \
-- npx -y mcp-remote https://mcp.synta.io/mcp \
--header "X-Synta-Api-Key: YOUR_SYNTA_API_KEY" \
--header "X-N8n-Url: YOUR_N8N_URL" \
--header "X-N8n-Key: YOUR_N8N_API_KEY"
```
```powershell Windows (PowerShell) theme={null}
claude mcp add --scope user synta-mcp `
-- npx -y mcp-remote https://mcp.synta.io/mcp `
--header "X-Synta-Api-Key: YOUR_SYNTA_API_KEY" `
--header "X-N8n-Url: YOUR_N8N_URL" `
--header "X-N8n-Key: YOUR_N8N_API_KEY"
```
```cmd Windows (Command Prompt) theme={null}
claude mcp add --scope user synta-mcp ^
-- npx -y mcp-remote https://mcp.synta.io/mcp ^
--header "X-Synta-Api-Key: YOUR_SYNTA_API_KEY" ^
--header "X-N8n-Url: YOUR_N8N_URL" ^
--header "X-N8n-Key: YOUR_N8N_API_KEY"
```
* `YOUR_SYNTA_API_KEY` - Get from [synta.io/mcp](https://synta.io/mcp)
* `YOUR_N8N_URL` - Your n8n instance URL
* `YOUR_N8N_API_KEY` - Your n8n API key
Add n8n login credentials:
```bash macOS/Linux theme={null}
claude mcp add --scope user synta-mcp \
-- npx -y mcp-remote https://mcp.synta.io/mcp \
--header "X-Synta-Api-Key: YOUR_SYNTA_API_KEY" \
--header "X-N8n-Url: YOUR_N8N_URL" \
--header "X-N8n-Key: YOUR_N8N_API_KEY" \
--header "X-N8n-Login-Email: YOUR_EMAIL" \
--header "X-N8n-Login-Password: YOUR_PASSWORD"
```
```powershell Windows (PowerShell) theme={null}
claude mcp add --scope user synta-mcp `
-- npx -y mcp-remote https://mcp.synta.io/mcp `
--header "X-Synta-Api-Key: YOUR_SYNTA_API_KEY" `
--header "X-N8n-Url: YOUR_N8N_URL" `
--header "X-N8n-Key: YOUR_N8N_API_KEY" `
--header "X-N8n-Login-Email: YOUR_EMAIL" `
--header "X-N8n-Login-Password: YOUR_PASSWORD"
```
```cmd Windows (Command Prompt) theme={null}
claude mcp add --scope user synta-mcp ^
-- npx -y mcp-remote https://mcp.synta.io/mcp ^
--header "X-Synta-Api-Key: YOUR_SYNTA_API_KEY" ^
--header "X-N8n-Url: YOUR_N8N_URL" ^
--header "X-N8n-Key: YOUR_N8N_API_KEY" ^
--header "X-N8n-Login-Email: YOUR_EMAIL" ^
--header "X-N8n-Login-Password: YOUR_PASSWORD"
```
**Self-Healing Benefits:**
* Enables `n8n_trigger_execution` - execute workflows and auto-fix errors
* Enables `n8n_manage_pindata` CRUD operations - add/update/remove/clear pin data for testing
* Full execution data for debugging
Run:
```bash theme={null}
claude mcp get synta-mcp
```
ChatGPT **only** supports OAuth authentication. This works with **Pro, Plus, Business, Enterprise and Education** paid plans on the web.
Go to **Settings** → **Apps** → **Advanced settings**
Toggle **Developer Mode** on
Go back and click **"Create app"**
**Name**:
```text theme={null}
synta-mcp
```
**MCP Server URL**:
```text theme={null}
https://mcp.synta.io/mcp
```
**Authentication**: Leave as OAuth (default)
Click **Create** and log in with the **same account** you used at [synta.io](https://synta.io). Your n8n credentials are fetched automatically.
Connection issues? ChatGPT's MCP link is very unstable. If the server doesn't load, repeat the steps 3-5 times. This is a known ChatGPT issue, and we advise using other clients for now.
OAuth provides automatic credential sync from your Synta account.
Click the three dots (**…**) at the top of the editor's agent panel, then go to **MCP Servers** → **Manage MCP Servers** → **View raw config**
Paste the following configuration and click **Save**:
```json theme={null}
{
"mcpServers": {
"synta-mcp": {
"serverUrl": "https://mcp.synta.io/mcp"
}
}
}
```
When Antigravity connects, it will open your browser for OAuth. Log in with the **same account** you used at [synta.io](https://synta.io). Your n8n credentials are fetched automatically.
Go back and click **Refresh** — you'll see a list of available tools.
Use API keys for manual credential management. Requires [Node.js](https://nodejs.org/en/download).
Click the three dots (**…**) at the top of the editor's agent panel, then go to **MCP Servers** → **Manage MCP Servers** → **View raw config**
Paste the following configuration and click **Save**:
```json theme={null}
{
"mcpServers": {
"synta-mcp": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://mcp.synta.io/mcp",
"--header",
"X-Synta-Api-Key: YOUR_SYNTA_API_KEY",
"--header",
"X-N8n-Url: YOUR_N8N_URL",
"--header",
"X-N8n-Key: YOUR_N8N_API_KEY"
]
}
}
}
```
* `YOUR_SYNTA_API_KEY` - Get from [synta.io/mcp](https://synta.io/mcp)
* `YOUR_N8N_URL` - Your n8n instance URL
* `YOUR_N8N_API_KEY` - Your n8n API key
Add n8n login credentials for AI-driven workflow testing:
```json theme={null}
{
"mcpServers": {
"synta-mcp": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://mcp.synta.io/mcp",
"--header",
"X-Synta-Api-Key: YOUR_SYNTA_API_KEY",
"--header",
"X-N8n-Url: YOUR_N8N_URL",
"--header",
"X-N8n-Key: YOUR_N8N_API_KEY",
"--header",
"X-N8n-Login-Email: YOUR_EMAIL",
"--header",
"X-N8n-Login-Password: YOUR_PASSWORD"
]
}
}
}
```
**Self-Healing Benefits:**
* Enables `n8n_trigger_execution` - execute workflows and auto-fix errors
* Enables `n8n_manage_pindata` CRUD operations - add/update/remove/clear pin data for testing
* Full execution data for debugging
Go back and click **Refresh** — you'll see a list of available tools.
OAuth provides automatic credential sync from your Synta account.
Command Setup
Recommended
Enable experimental rMCP client support:
```bash theme={null}
codex --config experimental_use_rmcp_client=true
```
Run this command in your terminal:
```bash theme={null}
codex mcp add synta-mcp --url https://mcp.synta.io/mcp
```
When Codex connects, it will open your browser for OAuth. Log in with the **same account** you used at [synta.io](https://synta.io).
Run:
```bash theme={null}
codex mcp list
```
Codex requires extended timeout settings for Synta to work properly. If you see startup timeout errors, try increasing startup\_timeout\_sec to 40.
Open your global Codex configuration file in your preferred text editor:
**File path:**
* **macOS/Linux**: `~/.codex/config.toml`
* **Windows**: `C:\Users\\.codex\config.toml`
**Command example:**
```bash macOS/Linux theme={null}
nano ~/.codex/config.toml
```
```powershell Windows (PowerShell) theme={null}
notepad $env:USERPROFILE\.codex\config.toml
```
At the top level of the file (not nested under any existing brackets), add:
```toml theme={null}
experimental_use_rmcp_client = true
```
Add a new section for the Synta server at the bottom of the file:
```toml theme={null}
[mcp_servers.synta-mcp]
url = "https://mcp.synta.io/mcp"
type = "http"
startup_timeout_sec = 30
tool_timeout_sec = 360
```
When Codex connects, it will open your browser for OAuth. Log in with the **same account** you used at [synta.io](https://synta.io).
Save the file and exit your editor. Restart your terminal or Codex session to reload the configuration.
Run:
```bash theme={null}
codex mcp list
```
Use API keys for manual credential management. Requires [Node.js](https://nodejs.org/en/download).
Command Setup
Recommended
```bash macOS/Linux theme={null}
codex mcp add synta-mcp \
-- npx -y mcp-remote https://mcp.synta.io/mcp \
--header "X-Synta-Api-Key: YOUR_SYNTA_API_KEY" \
--header "X-N8n-Url: YOUR_N8N_URL" \
--header "X-N8n-Key: YOUR_N8N_API_KEY"
```
```powershell Windows (PowerShell) theme={null}
codex mcp add synta-mcp `
-- npx -y mcp-remote https://mcp.synta.io/mcp `
--header "X-Synta-Api-Key: YOUR_SYNTA_API_KEY" `
--header "X-N8n-Url: YOUR_N8N_URL" `
--header "X-N8n-Key: YOUR_N8N_API_KEY"
```
```cmd Windows (Command Prompt) theme={null}
codex mcp add synta-mcp ^
-- npx -y mcp-remote https://mcp.synta.io/mcp ^
--header "X-Synta-Api-Key: YOUR_SYNTA_API_KEY" ^
--header "X-N8n-Url: YOUR_N8N_URL" ^
--header "X-N8n-Key: YOUR_N8N_API_KEY"
```
Note: This command does not configure timeout settings. For extended timeouts, use the Direct Config File Setup below.
* `YOUR_SYNTA_API_KEY` - Get from [synta.io/mcp](https://synta.io/mcp)
* `YOUR_N8N_URL` - Your n8n instance URL
* `YOUR_N8N_API_KEY` - Your n8n API key
Add n8n login credentials:
```bash macOS/Linux theme={null}
codex mcp add synta-mcp \
-- npx -y mcp-remote https://mcp.synta.io/mcp \
--header "X-Synta-Api-Key: YOUR_SYNTA_API_KEY" \
--header "X-N8n-Url: YOUR_N8N_URL" \
--header "X-N8n-Key: YOUR_N8N_API_KEY" \
--header "X-N8n-Login-Email: YOUR_EMAIL" \
--header "X-N8n-Login-Password: YOUR_PASSWORD"
```
```powershell Windows (PowerShell) theme={null}
codex mcp add synta-mcp `
-- npx -y mcp-remote https://mcp.synta.io/mcp `
--header "X-Synta-Api-Key: YOUR_SYNTA_API_KEY" `
--header "X-N8n-Url: YOUR_N8N_URL" `
--header "X-N8n-Key: YOUR_N8N_API_KEY" `
--header "X-N8n-Login-Email: YOUR_EMAIL" `
--header "X-N8n-Login-Password: YOUR_PASSWORD"
```
```cmd Windows (Command Prompt) theme={null}
codex mcp add synta-mcp ^
-- npx -y mcp-remote https://mcp.synta.io/mcp ^
--header "X-Synta-Api-Key: YOUR_SYNTA_API_KEY" ^
--header "X-N8n-Url: YOUR_N8N_URL" ^
--header "X-N8n-Key: YOUR_N8N_API_KEY" ^
--header "X-N8n-Login-Email: YOUR_EMAIL" ^
--header "X-N8n-Login-Password: YOUR_PASSWORD"
```
**Self-Healing Benefits:**
* Enables `n8n_trigger_execution` - execute workflows and auto-fix errors
* Enables `n8n_manage_pindata` CRUD operations - add/update/remove/clear pin data for testing
* Full execution data for debugging
Run:
```bash theme={null}
codex mcp list
```
Codex requires extended timeout settings for Synta to work properly. If you see startup timeout errors, try increasing startup\_timeout\_sec to 40.
Open your global Codex configuration file in your preferred text editor:
**File path:**
* **macOS/Linux**: `~/.codex/config.toml`
* **Windows**: `C:\Users\\.codex\config.toml`
**Command example:**
```bash macOS/Linux theme={null}
nano ~/.codex/config.toml
```
```powershell Windows (PowerShell) theme={null}
notepad $env:USERPROFILE\.codex\config.toml
```
At the top level of the file (not nested under any existing brackets), add:
```toml theme={null}
experimental_use_rmcp_client = true
```
Add a new section for the Synta server at the bottom of the file:
```toml theme={null}
[mcp_servers.synta-mcp]
command = "npx"
args = [
"-y",
"mcp-remote",
"https://mcp.synta.io/mcp",
"--header",
"X-Synta-Api-Key: YOUR_SYNTA_API_KEY",
"--header",
"X-N8n-Url: YOUR_N8N_URL",
"--header",
"X-N8n-Key: YOUR_N8N_API_KEY"
]
startup_timeout_sec = 30
tool_timeout_sec = 360
```
* `YOUR_SYNTA_API_KEY` - Get from [synta.io/mcp](https://synta.io/mcp)
* `YOUR_N8N_URL` - Your n8n instance URL
* `YOUR_N8N_API_KEY` - Your n8n API key
Add n8n login credentials to the args array:
```toml theme={null}
[mcp_servers.synta-mcp]
command = "npx"
args = [
"-y",
"mcp-remote",
"https://mcp.synta.io/mcp",
"--header",
"X-Synta-Api-Key: YOUR_SYNTA_API_KEY",
"--header",
"X-N8n-Url: YOUR_N8N_URL",
"--header",
"X-N8n-Key: YOUR_N8N_API_KEY",
"--header",
"X-N8n-Login-Email: YOUR_EMAIL",
"--header",
"X-N8n-Login-Password: YOUR_PASSWORD"
]
startup_timeout_sec = 30
tool_timeout_sec = 360
```
**Self-Healing Benefits:**
* Enables `n8n_trigger_execution` - execute workflows and auto-fix errors
* Enables `n8n_manage_pindata` CRUD operations - add/update/remove/clear pin data for testing
* Full execution data for debugging
Note: `n8n_manage_pindata`'s `analyzePinDataRequirement` mode works without login credentials.
Save the file and exit your editor. Restart your terminal or Codex session to reload the configuration.
Run:
```bash theme={null}
codex mcp list
```
OAuth provides automatic credential sync from your Synta account.
Interactive Setup
Recommended
Run this command in your terminal:
```bash theme={null}
opencode mcp add
```
Answer the interactive prompts:
**MCP server name:**
```
synta-mcp
```
**Select MCP server type:** Remote
**MCP server URL:**
```
https://mcp.synta.io/mcp
```
**Does this server require OAuth authentication?:** Yes
**Do you have a pre-registered client ID?:** No
Run the auth command:
```bash theme={null}
opencode mcp auth synta-mcp
```
Your browser will open for OAuth authentication. Log in with the **same account** you used at [synta.io](https://synta.io).
Run:
```bash theme={null}
opencode mcp list
```
Edit your OpenCode configuration file:
**File path:**
* **macOS/Linux**: `~/.config/opencode/opencode.json`
* **Windows**: `%APPDATA%\opencode\opencode.json`
**Command example:**
```bash macOS/Linux theme={null}
nano ~/.config/opencode/opencode.json
```
```powershell Windows (PowerShell) theme={null}
notepad $env:APPDATA\opencode\opencode.json
```
```cmd Windows (Command Prompt) theme={null}
notepad %APPDATA%\opencode\opencode.json
```
Add the following to your config file:
```json theme={null}
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"synta-mcp": {
"type": "remote",
"url": "https://mcp.synta.io/mcp",
"enabled": true
}
}
}
```
Run the auth command in your terminal:
```bash theme={null}
opencode mcp auth synta-mcp
```
Your browser will open for OAuth authentication. Log in with the **same account** you used at [synta.io](https://synta.io).
Run:
```bash theme={null}
opencode mcp list
```
Use API keys for manual credential management. Requires [Node.js](https://nodejs.org/en/download).
Interactive Setup
Recommended
Run this command in your terminal:
```bash theme={null}
opencode mcp add
```
Answer the interactive prompts:
**MCP server name:**
```
synta-mcp
```
**Select MCP server type:** Local
**Enter command to run:**
```
npx -y mcp-remote https://mcp.synta.io/mcp --header "X-Synta-Api-Key: YOUR_SYNTA_API_KEY" --header "X-N8n-Url: YOUR_N8N_URL" --header "X-N8n-Key: YOUR_N8N_API_KEY"
```
Edit the command you just pasted and replace:
* `YOUR_SYNTA_API_KEY` - Get from [synta.io/mcp](https://synta.io/mcp)
* `YOUR_N8N_URL` - Your n8n instance URL
* `YOUR_N8N_API_KEY` - Your n8n API key
To add self-healing capabilities, run the interactive setup again with the full command including login credentials:
```bash theme={null}
opencode mcp add
```
When prompted for **Enter command to run**, paste:
```
npx -y mcp-remote https://mcp.synta.io/mcp --header "X-Synta-Api-Key: YOUR_SYNTA_API_KEY" --header "X-N8n-Url: YOUR_N8N_URL" --header "X-N8n-Key: YOUR_N8N_API_KEY" --header "X-N8n-Login-Email: YOUR_EMAIL" --header "X-N8n-Login-Password: YOUR_PASSWORD"
```
Replace all credentials including:
* `YOUR_EMAIL` - Your n8n account email
* `YOUR_PASSWORD` - Your n8n account password
**Self-Healing Benefits:**
* Enables `n8n_trigger_execution` - execute workflows and auto-fix errors
* Enables `n8n_manage_pindata` CRUD operations - add/update/remove/clear pin data for testing
* Full execution data for debugging
Note: `n8n_manage_pindata`'s `analyzePinDataRequirement` mode works without login credentials.
Run:
```bash theme={null}
opencode mcp list
```
Edit your OpenCode configuration file:
**File path:**
* **macOS/Linux**: `~/.config/opencode/opencode.json`
* **Windows**: `%APPDATA%\opencode\opencode.json`
**Command example:**
```bash macOS/Linux theme={null}
nano ~/.config/opencode/opencode.json
```
```powershell Windows (PowerShell) theme={null}
notepad $env:APPDATA\opencode\opencode.json
```
```cmd Windows (Command Prompt) theme={null}
notepad %APPDATA%\opencode\opencode.json
```
Add the following to your config file:
```json theme={null}
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"synta-mcp": {
"type": "local",
"command": [
"npx",
"-y",
"mcp-remote",
"https://mcp.synta.io/mcp",
"--header",
"X-Synta-Api-Key: YOUR_SYNTA_API_KEY",
"--header",
"X-N8n-Url: YOUR_N8N_URL",
"--header",
"X-N8n-Key: YOUR_N8N_API_KEY"
],
"enabled": true
}
}
}
```
* `YOUR_SYNTA_API_KEY` - Get from [synta.io/mcp](https://synta.io/mcp)
* `YOUR_N8N_URL` - Your n8n instance URL
* `YOUR_N8N_API_KEY` - Your n8n API key
Add n8n login credentials to the command array:
```json theme={null}
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"synta-mcp": {
"type": "local",
"command": [
"npx",
"-y",
"mcp-remote",
"https://mcp.synta.io/mcp",
"--header",
"X-Synta-Api-Key: YOUR_SYNTA_API_KEY",
"--header",
"X-N8n-Url: YOUR_N8N_URL",
"--header",
"X-N8n-Key: YOUR_N8N_API_KEY",
"--header",
"X-N8n-Login-Email: YOUR_EMAIL",
"--header",
"X-N8n-Login-Password: YOUR_PASSWORD"
],
"enabled": true
}
}
}
```
**Self-Healing Benefits:**
* Enables `n8n_trigger_execution` - execute workflows and auto-fix errors
* Enables `n8n_manage_pindata` CRUD operations - add/update/remove/clear pin data for testing
* Full execution data for debugging
Note: `n8n_manage_pindata`'s `analyzePinDataRequirement` mode works without login credentials.
Run:
```bash theme={null}
opencode mcp list
```
OAuth provides automatic credential sync from your Synta account. Requires the **mcporter** skill.
Command Setup
In the OpenClaw gateway UI:
1. On the sidebar, navigate to **Agent** → **Skills** and search for **mcporter**.
2. Expand **Built-in skills**, find the **mcporter** skill, click **Install**, and wait until it shows **Installed**.
Run the command for your OS:
```bash macOS/Linux theme={null}
mcporter config add synta \
--url "https://mcp.synta.io/mcp" \
--auth oauth \
--config ~/.openclaw/workspace/config/mcporter.json
```
```powershell Windows (PowerShell) theme={null}
mcporter config add synta `
--url "https://mcp.synta.io/mcp" `
--auth oauth `
--config "$HOME/.openclaw/workspace/config/mcporter.json"
```
```cmd Windows (Command Prompt) theme={null}
mcporter config add synta ^
--url "https://mcp.synta.io/mcp" ^
--auth oauth ^
--config "%USERPROFILE%\.openclaw\workspace\config\mcporter.json"
```
Run the auth command:
```bash macOS/Linux theme={null}
mcporter auth synta-mcp --config ~/.openclaw/workspace/config/mcporter.json
```
```powershell Windows (PowerShell) theme={null}
mcporter auth synta-mcp --config "$HOME/.openclaw/workspace/config/mcporter.json"
```
```cmd Windows (Command Prompt) theme={null}
mcporter auth synta-mcp --config "%USERPROFILE%\.openclaw\workspace\config\mcporter.json"
```
A browser window will open. Log in with your Synta account and finish when you see **Authorization successful**.
Expected mcporter bug: If you see this message after signing in:
Failed to authorize 'synta-mcp': MCP error -32001: Request timed out
This is a
mcporter bug. Authentication can still succeed and the MCP can still work normally.
Run this command:
```bash theme={null}
openclaw config set tools.profile full && openclaw gateway restart
```
Run:
```bash macOS/Linux theme={null}
mcporter list --config ~/.openclaw/workspace/config/mcporter.json
```
```powershell Windows (PowerShell) theme={null}
mcporter list --config "$HOME/.openclaw/workspace/config/mcporter.json"
```
```cmd Windows (Command Prompt) theme={null}
mcporter list --config "%USERPROFILE%\.openclaw\workspace\config\mcporter.json"
```
You should see `synta-mcp` in the list of configured MCP servers.
Use API keys for manual credential management. Requires the **mcporter** skill and [Node.js](https://nodejs.org/en/download) installed.
Command Setup
In the OpenClaw gateway UI:
1. On the sidebar, navigate to **Agent** → **Skills** and search for **mcporter**.
2. Expand **Built-in skills**, find the **mcporter** skill, click **Install**, and wait until it shows **Installed**.
Run the command for your OS:
```bash macOS/Linux theme={null}
mcporter config add synta \
--url "https://mcp.synta.io/mcp" \
--header "X-Synta-Api-Key=YOUR_SYNTA_API_KEY" \
--header "X-N8n-Url=YOUR_N8N_URL" \
--header "X-N8n-Key=YOUR_N8N_API_KEY" \
--config ~/.openclaw/workspace/config/mcporter.json
```
```powershell Windows (PowerShell) theme={null}
mcporter config add synta `
--url "https://mcp.synta.io/mcp" `
--header "X-Synta-Api-Key=YOUR_SYNTA_API_KEY" `
--header "X-N8n-Url=YOUR_N8N_URL" `
--header "X-N8n-Key=YOUR_N8N_API_KEY" `
--config "$HOME/.openclaw/workspace/config/mcporter.json"
```
```cmd Windows (Command Prompt) theme={null}
mcporter config add synta ^
--url "https://mcp.synta.io/mcp" ^
--header "X-Synta-Api-Key=YOUR_SYNTA_API_KEY" ^
--header "X-N8n-Url=YOUR_N8N_URL" ^
--header "X-N8n-Key=YOUR_N8N_API_KEY" ^
--config "%USERPROFILE%\.openclaw\workspace\config\mcporter.json"
```
* `YOUR_SYNTA_API_KEY` - Get from [synta.io/mcp](https://synta.io/mcp)
* `YOUR_N8N_URL` - Your n8n instance URL
* `YOUR_N8N_API_KEY` - Your n8n API key
Add n8n login credentials for self-healing:
```bash macOS/Linux theme={null}
mcporter config add synta \
--url "https://mcp.synta.io/mcp" \
--header "X-Synta-Api-Key=YOUR_SYNTA_API_KEY" \
--header "X-N8n-Url=YOUR_N8N_URL" \
--header "X-N8n-Key=YOUR_N8N_API_KEY" \
--header "X-N8n-Login-Email=YOUR_EMAIL" \
--header "X-N8n-Login-Password=YOUR_PASSWORD" \
--config ~/.openclaw/workspace/config/mcporter.json
```
```powershell Windows (PowerShell) theme={null}
mcporter config add synta `
--url "https://mcp.synta.io/mcp" `
--header "X-Synta-Api-Key=YOUR_SYNTA_API_KEY" `
--header "X-N8n-Url=YOUR_N8N_URL" `
--header "X-N8n-Key=YOUR_N8N_API_KEY" `
--header "X-N8n-Login-Email=YOUR_EMAIL" `
--header "X-N8n-Login-Password=YOUR_PASSWORD" `
--config "$HOME/.openclaw/workspace/config/mcporter.json"
```
```cmd Windows (Command Prompt) theme={null}
mcporter config add synta ^
--url "https://mcp.synta.io/mcp" ^
--header "X-Synta-Api-Key=YOUR_SYNTA_API_KEY" ^
--header "X-N8n-Url=YOUR_N8N_URL" ^
--header "X-N8n-Key=YOUR_N8N_API_KEY" ^
--header "X-N8n-Login-Email=YOUR_EMAIL" ^
--header "X-N8n-Login-Password=YOUR_PASSWORD" ^
--config "%USERPROFILE%\.openclaw\workspace\config\mcporter.json"
```
**Self-Healing Benefits:**
* Enables `n8n_trigger_execution` - execute workflows and auto-fix errors
* Enables `n8n_manage_pindata` CRUD operations - add/update/remove/clear pin data for testing
* Full execution data for debugging
Note: `n8n_manage_pindata`'s `analyzePinDataRequirement` mode works without login credentials.
Run this command:
```bash theme={null}
openclaw config set tools.profile full && openclaw gateway restart
```
Run:
```bash macOS/Linux theme={null}
mcporter list --config ~/.openclaw/workspace/config/mcporter.json
```
```powershell Windows (PowerShell) theme={null}
mcporter list --config "$HOME/.openclaw/workspace/config/mcporter.json"
```
```cmd Windows (Command Prompt) theme={null}
mcporter list --config "%USERPROFILE%\.openclaw\workspace\config\mcporter.json"
```
You should see `synta` in the list of configured MCP servers.
OAuth provides automatic credential sync from your Synta account.
Go to **Windsurf** → **Settings** → **Windsurf Settings**, click the **Cascade** tab on the left-hand sidebar, find the **MCP Servers** heading and click on **"Open MCP Marketplace"**.
In the text labelled **"Installed MCPs"** on the right-hand side, click the **gear** icon to open the raw configuration editor.
Paste the following configuration and save:
```json theme={null}
{
"mcpServers": {
"synta-mcp": {
"serverUrl": "https://mcp.synta.io/mcp"
}
}
}
```
When you save the configuration, Windsurf will prompt you to authorize. Log in with the **same account** you used at [synta.io](https://synta.io). Your n8n credentials are fetched automatically.
Go back to the **MCP Marketplace** tab and confirm that `synta-mcp` appears in your list of installed servers.
Use API keys for manual credential management. Requires [Node.js](https://nodejs.org/en/download).
Go to **Windsurf** → **Settings** → **Windsurf Settings**, click the **Cascade** tab on the left-hand sidebar, find the **MCP Servers** heading and click on **"Open MCP Marketplace"**.
In the text labelled **"Installed MCPs"** on the right-hand side, click the **gear** icon to open the raw configuration editor.
Paste the following configuration:
```json theme={null}
{
"mcpServers": {
"synta-mcp": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://mcp.synta.io/mcp",
"--header",
"X-Synta-Api-Key: YOUR_SYNTA_API_KEY",
"--header",
"X-N8n-Url: YOUR_N8N_URL",
"--header",
"X-N8n-Key: YOUR_N8N_API_KEY"
]
}
}
}
```
* `YOUR_SYNTA_API_KEY` - Get from [synta.io/mcp](https://synta.io/mcp)
* `YOUR_N8N_URL` - Your n8n instance URL
* `YOUR_N8N_API_KEY` - Your n8n API key
Add n8n login credentials for AI-driven workflow testing:
```json theme={null}
{
"mcpServers": {
"synta-mcp": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://mcp.synta.io/mcp",
"--header",
"X-Synta-Api-Key: YOUR_SYNTA_API_KEY",
"--header",
"X-N8n-Url: YOUR_N8N_URL",
"--header",
"X-N8n-Key: YOUR_N8N_API_KEY",
"--header",
"X-N8n-Login-Email: YOUR_EMAIL",
"--header",
"X-N8n-Login-Password: YOUR_PASSWORD"
]
}
}
}
```
**Self-Healing Benefits:**
* Enables `n8n_trigger_execution` - execute workflows and auto-fix errors
* Enables `n8n_manage_pindata` CRUD operations - add/update/remove/clear pin data for testing
* Full execution data for debugging
Go back to the **MCP Marketplace** tab and confirm that `synta-mcp` appears in your list of installed servers.
## Verify Installation
After setup, verify by asking your AI agent:
```
Can you search for the slack node in n8n?
```
Your AI should respond with Slack node search results if configured correctly.
Having issues? Check the
Troubleshooting page for common problems and solutions.
## Next Steps
Discover all 23 MCP tools with self-healing capabilities
Set up client-specific rules for optimal workflow building
# Introduction
Source: https://mcp-docs.synta.io/introduction
Give your AI assistant expert-level knowledge of N8N workflow automation
Synta MCP transforms AI clients into n8n workflow experts. Your AI assistant gains deep knowledge, intelligent search, and self-healing capabilities—automatically testing, detecting errors, and fixing issues.
## With vs Without Synta MCP
* AI guesses at node names and properties
* Manual trial-and-error to find the right configuration
* Workflows break silently in production
* Hours spent debugging connection issues
* No access to community nodes or templates
* AI searches and validates nodes instantly
* Real examples from 10,000+ production workflows
* Self-healing catches and fixes errors automatically
* Full execution tracing for quick debugging
* Complete core + community node support
## What Your AI Gets
Full N8N node catalog with detailed properties (core & community)
Production-tested workflows curated by N8N experts
AI tests workflows, detects errors, and fixes issues automatically
## Key Capabilities
* **Intelligent search**: Full-text and fuzzy search across nodes, workflows, and templates
* **AI-aware validation**: Specialized checks for AI agents, webhooks, and code nodes
* **Execution tracing**: Correlate chains across workflows with timing analysis
* **22 specialized tools**: Purpose-built for workflow building, testing, and debugging
## Next Steps
Configure Synta MCP for your AI agent in minutes
# Privacy Policy
Source: https://mcp-docs.synta.io/privacy
Learn how Synta MCP protects your data and respects your privacy
## Our Commitment to Privacy
At Synta MCP, we take your privacy seriously. This policy outlines how we handle your data and protect your information.
## Security & Compliance
We follow enterprise-grade security practices and maintain SOC 2 compliance standards
We have opted out from any training by AI model providers. Your data is never used to train AI models
## Data Protection
### What We Collect
* **API Authentication**: Your Synta MCP API key for service authentication
* **Usage Metrics**: Anonymous usage statistics to improve our service
* **Error Logs**: Diagnostic information when errors occur (no workflow data included)
### What We Don't Collect
* **Workflow Contents**: Your n8n workflows and configurations remain private
* **Credentials**: We never store your n8n API keys or instance credentials
* **Personal Data**: We don't collect personal information beyond what's necessary for authentication
### Data Storage
* All data is encrypted in transit using TLS 1.3
* API keys are hashed and securely stored
* Usage logs are retained for 90 days for diagnostic purposes
* No workflow data is stored on our servers
### Third-Party Access
* We do not sell, rent, or share your data with third parties
* We do not allow AI model providers to train on your data
* Your n8n instance credentials are only used for direct API calls and never logged
## Your Rights
You have the right to:
* **Access**: Request information about data we hold about you
* **Deletion**: Request deletion of your account and associated data
* **Portability**: Export your usage data in a machine-readable format
* **Correction**: Update or correct your account information
## Security Measures
We implement industry-standard security practices:
* Encrypted data transmission (TLS 1.3)
* Secure credential storage with hashing
* Regular security audits
* Access controls and authentication
* Monitoring for suspicious activity
Your Responsibility: Keep your API keys secure. Never share them publicly or commit them to version control. Rotate keys immediately if compromised.
## Updates to This Policy
We may update this privacy policy from time to time. We will notify users of any material changes through:
* Email notifications (if you've provided an email)
* Updates on our website
* In-app notifications
**Last Updated**: January 2025
## Contact Us
For privacy-related questions, concerns, or requests, please contact us:
**Email**: [info@synta.io](mailto:info@synta.io)
We aim to respond to all privacy inquiries within 48 hours.
## Additional Information
### GDPR Compliance
For users in the European Union, we comply with GDPR requirements:
* Lawful basis for processing: Legitimate interest and contractual necessity
* Data minimization: We only collect what's necessary
* Right to be forgotten: Contact us to delete your data
* Data portability: Export your data at any time
### California Privacy Rights
For California residents (CCPA):
* We do not sell personal information
* You have the right to opt-out of data collection
* You can request disclosure of collected information
* You can request deletion of your information
## Data Breach Protocol
In the unlikely event of a data breach:
1. We will notify affected users within 72 hours
2. Provide details about what data was affected
3. Offer guidance on protective measures
4. Work with authorities as required by law
Transparency: We believe in being transparent about our data practices. If you have questions not covered here, please reach out.
***
This privacy policy was last updated on **November 19, 2025**.
# Rules & Agent Instructions
Source: https://mcp-docs.synta.io/rules
Configure AI agent rules for optimal n8n workflow automation
Agent rules help your AI client understand n8n workflow patterns, best practices, and common pitfalls. Configure these rules once and get expert-level workflow building:
* **Node discovery patterns**: When to use `search_nodes` vs `get_node`
* **Workflow building guidelines**: Proper connection handling and node configuration
* **Validation requirements**: Always validate before deployment
* **Self-healing instructions**: How to leverage `n8n_trigger_execution` for automatic error fixing
Rules are optional but highly recommended. They significantly improve the quality of AI-generated workflows.
## Client Configuration
Select your AI client to see specific setup instructions:
### Project Rules Setup
Go to **Cursor Settings** → **Rules and Commands** → **Project Rules** → Click **"Add Rule"**
Visit the [Cursor Rules for Synta](https://github.com/Synta-ai/synta-rules-for-agents/blob/main/.cursor/rules/synta.mdc).
Then, copy the rule file's content, paste into the editor and save.
### Project Instructions Setup
In your project root, create a file named `CLAUDE.md`
Visit the [Claude Code instructions for Synta](https://github.com/Synta-ai/synta-rules-for-agents/blob/main/.claude/agents/synta.md)
Then, copy the rule file’s content, paste into your `CLAUDE.md` and save.
### Project Instructions Setup
Open Claude (Desktop app or Claude.ai website) and navigate to **Projects** → **Create New Project**. Give your project a name and description, and then click "Create Project".
In the project, click the **plus icon** on the right-hand side of the **Instructions** text label.
Visit the [Claude instructions for Synta](https://github.com/Synta-ai/synta-rules-for-agents/blob/main/.claude/agents/synta.md)
Then, copy the file's content, paste it into the text field and click **Save instructions**.
### Project Instructions Setup
On the left sidebar, click the **New project** button, add a name and then click **Create project**
Click the three dots (**…**) at the top right of the editor and choose **Project settings**
Visit the [ChatGPT project instructions for Synta](https://github.com/Synta-ai/synta-rules-for-agents/blob/main/.chatgpt/chatgpt-project-instructions.md).
Then, copy the file's content, paste it into the **Instructions** field and click **Save**.
### Project Skill Setup
Quick install
Run the command for your OS to auto-install the Synta Skill:
```bash macOS/Linux theme={null}
mkdir -p ~/.agents/skills/synta-n8n
curl -o ~/.agents/skills/synta-n8n/SKILL.md https://raw.githubusercontent.com/Synta-ai/synta-rules-for-agents/main/.codex/skills/SKILL.MD
```
```powershell Windows (PowerShell) theme={null}
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.agents\skills\synta-n8n"
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/Synta-ai/synta-rules-for-agents/main/.codex/skills/SKILL.MD" -OutFile "$env:USERPROFILE\.agents\skills\synta-n8n\SKILL.md" -UseBasicParsing
```
```cmd Windows (Command Prompt) theme={null}
mkdir "%USERPROFILE%\.agents\skills\synta-n8n" 2>nul
curl -L -o "%USERPROFILE%\.agents\skills\synta-n8n\SKILL.md" https://raw.githubusercontent.com/Synta-ai/synta-rules-for-agents/main/.codex/skills/SKILL.MD
```
Then, restart Codex. Use `$` or `/skills` to invoke, or let Codex call by description.
### Project Rules Setup
Click the three dots (**…**) at the top of the editor's agent panel → **Customizations** and switch to the **Rules** tab.
Choose either:
* **+ Global** (applies across all your workspaces)
* **+ Workspace** (applies only to the current project).
In the editor for the rule:
1. Set the activation mode (recommended: **Model Decision**).
2. **Description** — Copy and paste from this block:
```
Expert guidance for building and editing n8n workflows with Synta MCP tools. Use for creating new workflows, modifying existing workflows, template discovery, node configuration, validation, and connection management in n8n.
```
3. **Content** — Copy the [Antigravity rule content for Synta](https://github.com/Synta-ai/synta-rules-for-agents/blob/main/.antigravity/agents/rules/synta_rule_content.md) and paste.
4. Save the rule.
### Project Rules Setup
In your project root, create a file named `AGENTS.md`
Visit the [OpenCode instructions for Synta](https://github.com/Synta-ai/synta-rules-for-agents/blob/main/.opencode/AGENTS.md)
Then, copy the rule file content, paste it into your `AGENTS.md` file and save.
### Project Skill Setup
Quick install
Run the command for your OS to install the Synta skill into your managed skills directory:
```bash macOS/Linux theme={null}
mkdir -p ~/.openclaw/skills/synta-n8n
curl -o ~/.openclaw/skills/synta-n8n/SKILL.md https://raw.githubusercontent.com/Synta-ai/synta-rules-for-agents/main/.openclaw/skills/SKILL.md
```
```powershell Windows (PowerShell) theme={null}
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.openclaw\skills\synta-n8n"
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/Synta-ai/synta-rules-for-agents/main/.openclaw/skills/SKILL.md" -OutFile "$env:USERPROFILE\.openclaw\skills\synta-n8n\SKILL.md" -UseBasicParsing
```
```cmd Windows (Command Prompt) theme={null}
mkdir "%USERPROFILE%\.openclaw\skills\synta-n8n" 2>nul
curl -L -o "%USERPROFILE%\.openclaw\skills\synta-n8n\SKILL.md" https://raw.githubusercontent.com/Synta-ai/synta-rules-for-agents/main/.openclaw/skills/SKILL.md
```
Start a new session (or restart the gateway) so OpenClaw picks up the skill. You can invoke it via slash command or let the agent match by description.
### Project Rules Setup
Go to **Windsurf** → **Settings** → **Windsurf Settings**, click on the **Cascade** tab on the left-hand sidebar, find the **Cascade Rules** heading and click **"Manage rules"**.
Choose either:
* **+ Global** (applies across all your workspaces)
* **+ Workspace** (applies only to the current project)
Visit the [Windsurf rules for Synta](https://github.com/Synta-ai/synta-rules-for-agents/blob/main/.windsurf/synta.md).
Copy the file's content, paste it into the editor, and save.
## Contributing
The repository is open-source and welcomes contributions:
* Add configurations for new AI agents
* Improve existing rule sets
* Share workflow patterns and examples
Visit the [repository](https://github.com/Synta-ai/synta-rules-for-agents) to contribute or report issues.
These configurations are maintained by the Synta community and are designed to help agents make the most of Synta's MCP server capabilities.
## Next Steps
Learn tips and tricks for building better workflows with AI
# Troubleshooting
Source: https://mcp-docs.synta.io/troubleshooting
Common issues and solutions for Synta MCP
Having trouble with Synta MCP? This guide covers the most common issues and how to resolve them.
## Common Issues
If your AI client isn't calling Synta MCP tools or seems unaware of the MCP connection:
### Solution
1. **Explicitly Mention Synta MCP in Your Prompt**
Try using a prompt like this:
```text theme={null}
Use synta-mcp to search for the Slack node in n8n
```
This explicitly tells the AI to use the Synta MCP tools.
2. **Restart Your AI Client**
* Completely quit your AI client (don't just close the window)
* Reopen the application
* Start a new conversation/chat
3. **Start a Fresh Chat**
* Previous conversations may have context that doesn't include MCP awareness
* Create a new chat window/conversation
* Try your request again with explicit mention of synta-mcp
4. **Verify MCP Connection**
* Check your MCP configuration is still active
* Look for MCP indicators in your client (e.g., tool icons, MCP badge)
* If the connection appears inactive (e.g. A red status icon on Cursor), restart your client or reconfigure following the [installation steps](/installation)
### Why This Happens
AI clients may not always automatically use MCP tools unless explicitly prompted, especially in existing conversations or after updates.
ChatGPT's MCP integration can be buggy and may not connect on the first try.
### Solution
1. Delete the MCP app from ChatGPT settings
2. Re-create the app following the [installation steps](/installation)
3. **Repeat the process 3-5 times** if it doesn't work initially
4. This is a known ChatGPT limitation, not a Synta issue
### Why This Happens
ChatGPT's MCP implementation is relatively new and can have intermittent connection issues. Retrying the setup process typically resolves the issue.
### Note
ChatGPT only supports OAuth authentication (no API key option). This requires a **Pro, Plus, Business, Enterprise or Education** paid plan.
After successfully connecting Synta MCP to ChatGPT, you may experience instability where the MCP connection becomes "gone" or tools return "Resource not found" errors during a session.
### Common Symptoms
* Tools work initially, then suddenly fail with "Resource not found"
* ChatGPT reports the MCP link is "gone" mid-conversation
* Tools like n8n\_get\_workflow or n8n\_update\_partial\_workflow stop working
* Connection appears to drop without warning
### Solution
**Use Vanilla Chat Instead of Projects:**
1. Do NOT use ChatGPT Projects for Synta MCP
2. Use regular chat conversations (vanilla chat) instead
3. The MCP connection is more stable in standard chat mode
### Why This Happens
ChatGPT's MCP support is currently flaky and unreliable, especially within Projects. The connection works better in standard chat conversations. This is a known ChatGPT limitation.
### Alternative Recommendation
For more stable MCP connections, consider using:
* **Cursor** - Excellent MCP support with OAuth or API key
* **Claude Desktop** - Native MCP support, very stable
* **Claude Code** - CLI-based, reliable MCP integration
See the [Installation](/installation) page for setup instructions for these alternatives.
If you're getting authentication or authorization errors:
### Solution
1. **Verify Synta API Key**
* Ensure you copied the full API key from [synta.io/mcp](https://synta.io/mcp)
* Check for extra spaces or newlines
* Make sure the key starts with the correct format
2. **Check N8N Credentials**
* Verify your N8N instance URL is accessible
* Test your N8N API key in a browser or API client
* Ensure the API key has the correct permissions
3. **Verify N8N Login Credentials (for self-healing tools)**
* Check `X-N8n-Login-Email` is set to your n8n account email
* Check `X-N8n-Login-Password` is set to your n8n account password
* Required for `n8n_trigger_execution` and `n8n_manage_pindata`
* Make sure the credentials are correct and the account has appropriate permissions
4. **Update Configuration**
* Replace credentials in your config file
* Restart your AI agent after updating
If the MCP server disconnects during operations or times out:
### Common Causes
* Long-running operations (large workflows, many templates)
* Network instability
* Server timeout settings
* Resource-intensive tool calls
### Solution
1. **Break Down Large Operations**
* Search templates in smaller batches (use `limit` parameter)
* Process workflows one at a time instead of bulk operations
* Use pagination with `cursor` for large result sets
2. **Use Faster Tool Variants**
* Use `get_node` with `view: "summary"` for quick property checks
* Use `n8n_validate_workflow` only after you have narrowed the problem to a specific workflow
* Use `get_template` with `mode: "nodes_only"` for quick previews
3. **Increase Timeout Settings**
* Check your MCP client's timeout configuration
* Some operations like `n8n_trigger_execution` may need longer timeouts
4. **Restart the Connection**
* Clear npx cache: `rm -rf ~/.npm/_npx`
* Restart your AI agent
* Verify network stability
5. **Check Tool Parameters**
* Ensure `limit` parameters are reasonable (avoid requesting 1000+ items)
* Avoid `includeConfigExamples` in `get_node` unless needed
* Disable expensive options like `includeTypeInfo` unless needed
If workflows fail to execute or webhook triggers don't work:
### Choose the Right Tool
**n8n\_trigger\_execution**:
* Requires N8N login credentials (`X-N8n-Login-Email`, `X-N8n-Login-Password`)
* Supports all trigger types: Manual, Chat, Webhook, Form
* AI automatically detects errors and suggests fixes (self-healing)
* Full execution data for debugging
* Works with n8n\_manage\_pindata for testing
**n8n\_test\_workflow**:
* External testing for activated workflows
* Supports: Webhook, Form, Chat triggers
**n8n\_manage\_pindata**:
* Requires N8N login credentials (`X-N8n-Login-Email`, `X-N8n-Login-Password`)
* Save mock data for any node and reuse in test runs
* Test webhooks/forms without sending real requests
* Skip API calls during development with saved responses
* Modes: addPinData, updatePinData, removePinData, readPinData
### Common Solutions
1. **Activate Workflow** (for `n8n_test_workflow`)
```json theme={null}
{
"id": "workflow-id",
"operations": [
{"type": "updateSettings", "settings": {"active": true}}
]
}
```
2. **Verify Trigger Configuration**
* Workflow has a valid trigger node
* Webhook path is correctly configured
* Chat triggers have a valid `chatMessage`
3. **Debug Failed Executions**
```javascript theme={null}
// Get error details
n8n_manage_executions({action: "get", id: "exec-id", mode: "error"})
// Trace multi-workflow chains
n8n_manage_executions({action: "correlate", executionId: "exec-id"})
// Re-run failed execution
n8n_manage_executions({action: "retry", id: "exec-id"})
```
If you can list tools but tool execution fails with errors like:
* `Failure in MCP tool execution: connection closed: calling "tools/call": client is closing: standalone SSE stream: failed to decode event: unmarshaling jsonrpc message: unexpected end of JSON input`
* `Failure in MCP tool execution: connection closed: calling "tools/call": client is closing: EOF`
* `mismatching session IDs`
### Solution
1. **Remove and re-add the MCP server in Antigravity**
* Go to Antigravity settings → MCP Servers
* Remove the Synta MCP server completely
* Close Antigravity entirely (not just the conversation)
* Reopen Antigravity and re-add the server
2. **Use the correct configuration format**
```json theme={null}
{
"mcpServers": {
"synta": {
"type": "streamable-http",
"serverUrl": "https://mcp.synta.io/mcp"
}
}
}
```
Setting `"type": "streamable-http"` explicitly tells Antigravity to use the correct transport protocol.
3. **If errors persist after re-adding**, start a new conversation in Antigravity. The previous conversation may have cached stale session state.
### Why This Happens
Antigravity's MCP client caches session state internally. When a session becomes stale (e.g., after a server update or network interruption), the cached session is never revalidated. This is a [known Antigravity/ADK issue](https://github.com/google/adk-go/issues/399). Removing and re-adding the server forces a fresh connection that bypasses the stale cache.
After a Claude Desktop update, all Synta MCP tools may be discovered (appear in the tool list with full schemas) but every call returns:
> "This tool has been disabled in your connector settings."
This only affects **Cowork mode** — the same setup works fine in standard Claude Chat.
### Why This Happens
Claude Desktop now requires MCP server IDs to be either a UUID or a `mcpsrv_*` prefixed string. The default server name `synta-mcp` doesn't match this format, so Cowork discovers the tools but blocks execution. The actual error (`Invalid server ID format. Expected UUID or mcpsrv_* tagged ID.`) only surfaces when you attempt to uninstall the connector — making this particularly hard to debug.
### Fix
1. Go to **Claude** → **Settings** → **Connectors**
2. Find the Synta MCP connector and click **Delete** to remove it
3. Click **Add custom connector** and re-add it with the updated name:
**Name:**
```text theme={null}
mcpsrv_synta
```
**Remote MCP server URL:**
```text theme={null}
https://mcp.synta.io/mcp
```
4. Authenticate with the **same account** you used at [synta.io](https://synta.io)
5. Restart Claude Desktop (**Cmd+Q**, then reopen)
1. Open your Claude Desktop config file:
* Go to **Claude** → **Settings** → **Developer** → **Edit Config**
2. Rename the server key from `synta-mcp` to `mcpsrv_synta`:
**Before:**
```json theme={null}
{
"mcpServers": {
"synta-mcp": {
"command": "npx",
"args": ["..."]
}
}
}
```
**After:**
```json theme={null}
{
"mcpServers": {
"mcpsrv_synta": {
"command": "npx",
"args": ["..."]
}
}
}
```
3. Save the file and restart Claude Desktop (**Cmd+Q**, then reopen)
If workflow nodes appear as "Unknown" on the canvas:
### Why This Happens
Your n8n instance doesn't recognize the node types in the workflow. This typically occurs when:
* The workflow uses nodes from a newer n8n version
* Community nodes are not installed
* Node packages are missing or outdated
### Solution
1. **Update n8n to Latest Version**
* Check your current version in **Settings** → **About n8n**
* Update to the latest version:
**n8n Cloud**: Automatically updated, contact support if issues persist
**Self-hosted**: Follow your hosting provider's instructions for updating n8n (Docker, npm, etc.)
2. **Install Missing Community Nodes**
* Go to **Settings** → **Community nodes**
* Search for and install any missing community nodes
* Restart n8n after installation
3. **Check Node Compatibility**
* Some nodes may be deprecated or renamed in newer versions
* Use `n8n_autofix_workflow` to automatically update node types
* Review the workflow and replace deprecated nodes with current alternatives
This error occurs when npm's cache has corrupted packages for npx.
### Solution
Clear the npx cache and try again:
```bash macOS/Linux theme={null}
rm -rf ~/.npm/_npx
```
```powershell Windows (PowerShell) theme={null}
Remove-Item -Recurse -Force "$env:USERPROFILE\.npm\_npx"
```
```cmd Windows (Command Prompt) theme={null}
rmdir /s /q "%USERPROFILE%\.npm\_npx"
```
After clearing the cache, restart your AI client.
### Why This Happens
The npx cache can sometimes store incomplete or corrupted package installations. Clearing it forces a fresh download of all required packages.
If you can't find your MCP configuration file, you may need to create it manually.
### Solution by Client
**Cursor**:
```bash macOS/Linux theme={null}
mkdir -p ~/.cursor && touch ~/.cursor/mcp.json
```
```powershell Windows (PowerShell) theme={null}
New-Item -ItemType Directory -Force -Path "$env:APPDATA\Cursor"
New-Item -ItemType File -Force -Path "$env:APPDATA\Cursor\mcp.json"
```
```cmd Windows (Command Prompt) theme={null}
mkdir "%APPDATA%\Cursor" 2>nul
type nul > "%APPDATA%\Cursor\mcp.json"
```
**Claude Desktop**:
```bash macOS theme={null}
mkdir -p ~/Library/Application\ Support/Claude
touch ~/Library/Application\ Support/Claude/claude_desktop_config.json
```
```bash Linux theme={null}
mkdir -p ~/.config/Claude
touch ~/.config/Claude/claude_desktop_config.json
```
```powershell Windows (PowerShell) theme={null}
New-Item -ItemType Directory -Force -Path "$env:APPDATA\Claude"
New-Item -ItemType File -Force -Path "$env:APPDATA\Claude\claude_desktop_config.json"
```
```cmd Windows (Command Prompt) theme={null}
mkdir "%APPDATA%\Claude" 2>nul
type nul > "%APPDATA%\Claude\claude_desktop_config.json"
```
After creating the file, add your configuration from the [Installation](/installation) page.
If Codex shows startup timeout errors when connecting to Synta MCP:
### Solution
Codex requires extended timeout settings for Synta MCP to work properly. Add these timeout configurations to your `~/.codex/config.toml` file:
```toml theme={null}
[mcp_servers.synta-mcp]
# ... your existing configuration ...
startup_timeout_sec = 30
tool_timeout_sec = 360
```
### Alternative: Increase Startup Timeout
If you still see timeout errors after adding the above settings, try increasing the startup timeout:
```toml theme={null}
[mcp_servers.synta-mcp]
# ... your existing configuration ...
startup_timeout_sec = 40
tool_timeout_sec = 360
```
### Why This Happens
Synta MCP performs initial setup operations when starting, which may exceed Codex's default timeout settings. The extended timeouts allow proper initialization.
### After Updating
1. Save your `config.toml` file
2. Restart your terminal or Codex session
3. Verify with: `codex mcp list`
If you're experiencing timeouts or connection issues:
### Solution
1. **Check Internet Connection**
* Ensure you have a stable internet connection
* Try accessing the MCP server URL in a browser
2. **Firewall/Proxy Settings**
* Check if your firewall is blocking the connection
* If using a corporate proxy, ensure npx can access external URLs
* You may need to configure proxy settings in your environment
3. **N8N Instance Accessibility**
* Verify your N8N instance is running and accessible
* Test the URL in a browser: `https://your-instance/api/v1/health`
* Check if the instance requires VPN or special network access
## Getting Help
If you're still experiencing issues after trying the solutions above:
Report bugs or request features on our GitHub repository
Ask questions and get help from the community
1. Which AI client you're using (Cursor, Claude Desktop, Claude Code, etc.)
2. Operating system (macOS, Windows, Linux)
3. Node.js version (run `node --version`)
4. Configuration file contents (with API keys redacted)
5. Error messages or screenshots
Never share your API keys or login credentials publicly. Always redact credentials when sharing configuration files or error messages.