# Resources & Prompts API Reference
Complete API reference for MCP resources and workflow generation prompts. Discover workflows and generate from templates.
---
## Overview
The MCP server provides two discovery mechanisms:
1. **Resources**: Read-only data endpoints for workflow and execution discovery
2. **Prompts**: Template-based workflow generation with variable substitution
**Key Features:**
- **Static Resources**: Global workflow lists and execution statistics
- **Dynamic Resources**: Specific workflow and execution details
- **Workflow Prompts**: 5 pre-built workflow generation templates
- **Variable Substitution**: Customizable prompt arguments
---
## MCP Resources
Resources provide read-only access to workflow and execution data through URI-based endpoints.
### Resource Categories
| Type | Count | Purpose |
|------|-------|---------|
| Static Resources | 2 | Global lists and statistics |
| Dynamic Resources | 2 | Specific item details |
---
## Static Resources
### Resource: `n8n://workflows`
List all workflows with metadata (performance optimized).
**URI:** `n8n://workflows`
**Query Parameters:**
- `instance` (optional): Instance identifier
**Response Schema:**
```typescript
interface WorkflowsResource {
workflows: WorkflowMetadata[];
totalCount: number;
generatedAt: string; // ISO 8601 timestamp
}
interface WorkflowMetadata {
id: string;
name: string;
active: boolean;
createdAt: string;
updatedAt: string;
nodes?: number; // Node count
tags?: string[]; // Tag names
}
```
**Response Example:**
```json
{
"workflows": [
{
"id": "123",
"name": "Email Campaign Automation",
"active": true,
"createdAt": "2024-12-15T10:30:00Z",
"updatedAt": "2025-01-10T14:20:00Z",
"nodes": 12,
"tags": ["production", "marketing"]
},
{
"id": "456",
"name": "Slack Notifications",
"active": true,
"createdAt": "2024-11-20T08:15:00Z",
"updatedAt": "2024-12-05T16:45:00Z",
"nodes": 5,
"tags": ["production", "monitoring"]
}
],
"totalCount": 2,
"generatedAt": "2025-01-15T10:00:00Z"
}
```
**Equivalent MCP Tool:** `list_workflows`
**Use Cases:**
- Building workflow dashboards
- Workflow inventory reports
- Monitoring active workflow counts
- Workflow discovery and exploration
---
### Resource: `n8n://execution-stats`
Execution statistics summary with recent executions and workflow performance.
**URI:** `n8n://execution-stats`
**Query Parameters:**
- `instance` (optional): Instance identifier
- `timeRange` (optional): Time range in hours (default: 24)
**Response Schema:**
```typescript
interface ExecutionStatsResource {
summary: {
total: number;
successful: number;
failed: number;
running: number;
successRate: number; // Percentage
};
recentExecutions: ExecutionSummary[];
byWorkflow: WorkflowExecutionStats[];
timeRange: {
from: string; // ISO 8601
to: string; // ISO 8601
};
generatedAt: string;
}
interface WorkflowExecutionStats {
workflowId: number;
workflowName: string;
executions: number;
successRate: number;
avgDuration: number; // Milliseconds
}
```
**Response Example:**
```json
{
"summary": {
"total": 1250,
"successful": 1180,
"failed": 65,
"running": 5,
"successRate": 94.4
},
"recentExecutions": [
{
"id": 9876,
"workflowId": 123,
"finished": true,
"mode": "webhook",
"startedAt": "2025-01-15T10:30:00Z",
"stoppedAt": "2025-01-15T10:30:02.245Z"
}
],
"byWorkflow": [
{
"workflowId": 123,
"workflowName": "Email Campaign",
"executions": 450,
"successRate": 98.2,
"avgDuration": 2145
},
{
"workflowId": 456,
"workflowName": "Slack Notifications",
"executions": 800,
"successRate": 99.5,
"avgDuration": 345
}
],
"timeRange": {
"from": "2025-01-14T10:00:00Z",
"to": "2025-01-15T10:00:00Z"
},
"generatedAt": "2025-01-15T10:00:00Z"
}
```
**Use Cases:**
- Real-time monitoring dashboards
- Performance analytics
- Success rate tracking
- Workflow health monitoring
---
## Dynamic Resources
### Resource: `n8n://workflows/{id}`
Get complete workflow definition for specific workflow.
**URI Pattern:** `n8n://workflows/{workflowId}`
**Parameters:**
- `{workflowId}`: Workflow ID (required, in URI path)
- `instance` (query, optional): Instance identifier
**Example URI:** `n8n://workflows/123?instance=production`
**Response:** Complete `WorkflowDefinition` object (same as `get_workflow` tool)
**Equivalent MCP Tool:** `get_workflow`
**Use Cases:**
- Workflow detail views
- Workflow cloning and templating
- Configuration review
- Debugging and analysis
---
### Resource: `n8n://executions/{id}`
Get complete execution details including node outputs and errors.
**URI Pattern:** `n8n://executions/{executionId}`
**Parameters:**
- `{executionId}`: Execution ID (required, in URI path)
- `instance` (query, optional): Instance identifier
- `includeData` (query, optional): Include execution data (default: true)
**Example URI:** `n8n://executions/9876?instance=production&includeData=true`
**Response:** Complete `Execution` object (same as `get_execution` tool)
**Equivalent MCP Tool:** `get_execution`
**Use Cases:**
- Execution debugging
- Performance analysis
- Audit and compliance
- Error investigation
---
## MCP Prompts
Workflow generation templates with variable substitution for rapid workflow creation.
### Available Prompts
| Prompt Name | Purpose | Variables |
|-------------|---------|-----------|
| `schedule-triggered-workflow` | Cron-based scheduled workflows | 4 variables |
| `http-webhook-workflow` | HTTP endpoint responders | 4 variables |
| `data-transformation-workflow` | Data processing pipelines | 4 variables |
| `external-service-integration` | API integration workflows | 4 variables |
| `api-data-polling` | Interval-based API polling | 4 variables |
---
## Prompt: schedule-triggered-workflow
Generate workflow with schedule trigger (cron-based automation).
### Arguments
```typescript
interface ScheduleTriggeredWorkflowArgs {
workflow_name: string; // Workflow display name
cron_schedule: string; // Cron expression (e.g., "0 2 * * *")
action_description: string; // What the workflow does
timezone?: string; // Timezone (default: "America/New_York")
}
```
### Example Usage
```typescript
const prompt = await client.getPrompt({
name: 'schedule-triggered-workflow',
arguments: {
workflow_name: 'Daily Backup',
cron_schedule: '0 2 * * *', // 2 AM daily
action_description: 'Backup database to S3',
timezone: 'America/New_York'
}
});
// Prompt returns workflow definition
const workflowDef = JSON.parse(prompt.messages[0].content.text);
// Create workflow from prompt
await client.callTool({
name: 'create_workflow',
arguments: workflowDef
});
```
### Generated Workflow Structure
- **Trigger Node**: Schedule Trigger with cron expression
- **Action Node**: Code node with action description
- **Settings**: Timezone configuration
---
## Prompt: http-webhook-workflow
Generate workflow with HTTP webhook trigger.
### Arguments
```typescript
interface HttpWebhookWorkflowArgs {
workflow_name: string; // Workflow display name
webhook_path: string; // URL path (e.g., "customer-signup")
response_mode?: string; // "onReceived" or "lastNode" (default: "onReceived")
processing_description: string; // What the workflow does with request
}
```
### Example Usage
```typescript
const prompt = await client.getPrompt({
name: 'http-webhook-workflow',
arguments: {
workflow_name: 'Customer Signup Handler',
webhook_path: 'customer-signup',
response_mode: 'onReceived',
processing_description: 'Validate email, send welcome email, store in database'
}
});
const workflowDef = JSON.parse(prompt.messages[0].content.text);
await client.callTool({
name: 'create_workflow',
arguments: workflowDef
});
```
### Generated Workflow Structure
- **Trigger Node**: Webhook with specified path
- **Processing Node**: Code node with processing description
- **Response Node**: Respond to webhook
---
## Prompt: data-transformation-workflow
Generate workflow for data transformation and ETL operations.
### Arguments
```typescript
interface DataTransformationWorkflowArgs {
workflow_name: string; // Workflow display name
source_description: string; // Where data comes from
transformation_description: string; // How data is transformed
destination_description: string; // Where data goes
}
```
### Example Usage
```typescript
const prompt = await client.getPrompt({
name: 'data-transformation-workflow',
arguments: {
workflow_name: 'Sales Data ETL',
source_description: 'Fetch sales data from Salesforce API',
transformation_description: 'Aggregate by region and calculate totals',
destination_description: 'Store in PostgreSQL analytics database'
}
});
const workflowDef = JSON.parse(prompt.messages[0].content.text);
await client.callTool({
name: 'create_workflow',
arguments: workflowDef
});
```
### Generated Workflow Structure
- **Source Node**: Data source (manual trigger or HTTP)
- **Transform Node**: Code node with transformation logic
- **Destination Node**: Data storage/output
---
## Prompt: external-service-integration
Generate workflow integrating with external services.
### Arguments
```typescript
interface ExternalServiceIntegrationArgs {
workflow_name: string; // Workflow display name
service_name: string; // External service name (e.g., "Slack", "GitHub")
trigger_description: string; // What triggers the workflow
action_description: string; // What action to perform on service
}
```
### Example Usage
```typescript
const prompt = await client.getPrompt({
name: 'external-service-integration',
arguments: {
workflow_name: 'GitHub Issue Notifier',
service_name: 'Slack',
trigger_description: 'New GitHub issue created',
action_description: 'Send notification to #dev-team channel'
}
});
const workflowDef = JSON.parse(prompt.messages[0].content.text);
await client.callTool({
name: 'create_workflow',
arguments: workflowDef
});
```
### Generated Workflow Structure
- **Trigger Node**: Service-specific trigger
- **Action Node**: Service integration node
- **Notification Node**: Optional confirmation
---
## Prompt: api-data-polling
Generate workflow that polls API endpoint on interval.
### Arguments
```typescript
interface ApiDataPollingArgs {
workflow_name: string; // Workflow display name
api_endpoint: string; // API URL to poll
poll_interval: string; // Cron expression or interval
data_processing: string; // What to do with retrieved data
}
```
### Example Usage
```typescript
const prompt = await client.getPrompt({
name: 'api-data-polling',
arguments: {
workflow_name: 'Stock Price Monitor',
api_endpoint: 'https://api.stocks.com/prices',
poll_interval: '*/15 * * * *', // Every 15 minutes
data_processing: 'Compare with threshold and send alerts if exceeded'
}
});
const workflowDef = JSON.parse(prompt.messages[0].content.text);
await client.callTool({
name: 'create_workflow',
arguments: workflowDef
});
```
### Generated Workflow Structure
- **Trigger Node**: Schedule Trigger with poll interval
- **HTTP Request Node**: API endpoint call
- **Processing Node**: Data processing logic
- **Action Node**: Result handling
---
## Code Examples
### List Available Prompts
```typescript
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
const client = new Client({
name: 'n8n-prompt-explorer',
version: '1.0.0'
});
await client.connect(transport);
// List all available prompts
const prompts = await client.listPrompts();
console.log('Available workflow prompts:');
prompts.forEach(prompt => {
console.log(`\n${prompt.name}`);
console.log(` Description: ${prompt.description}`);
console.log(` Arguments:`);
prompt.arguments?.forEach(arg => {
const required = arg.required ? '(required)' : '(optional)';
console.log(` - ${arg.name} ${required}: ${arg.description}`);
});
});
```
### Generate Workflow from Prompt
```typescript
async function generateWorkflowFromPrompt(
promptName: string,
args: Record<string, string>,
instance?: string
) {
// Get prompt with arguments
const prompt = await client.getPrompt({
name: promptName,
arguments: args
});
// Parse workflow definition from prompt
const workflowDef = JSON.parse(prompt.messages[0].content.text);
// Create workflow
const result = await client.callTool({
name: 'create_workflow',
arguments: {
instance,
...workflowDef
}
});
const workflow = JSON.parse(result.content[0].text);
console.log(`Created workflow: ${workflow.name} (ID: ${workflow.id})`);
return workflow;
}
// Usage
const workflow = await generateWorkflowFromPrompt(
'http-webhook-workflow',
{
workflow_name: 'Order Processor',
webhook_path: 'process-order',
processing_description: 'Validate and store order'
},
'production'
);
```
### Python - Generate from Template
```python
import json
import subprocess
def generate_workflow_from_prompt(prompt_name, args, instance=None):
"""Generate workflow from MCP prompt."""
# Get prompt
prompt_request = {
"jsonrpc": "2.0",
"id": 1,
"method": "prompts/get",
"params": {
"name": prompt_name,
"arguments": args
}
}
prompt_result = subprocess.run(
['npx', '@kernel.salacoste/n8n-workflow-builder'],
input=json.dumps(prompt_request),
capture_output=True,
text=True
)
prompt_response = json.loads(prompt_result.stdout)
workflow_def = json.loads(
prompt_response['result']['messages'][0]['content']['text']
)
# Create workflow
create_request = {
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"name": "create_workflow",
"arguments": {
"instance": instance,
**workflow_def
}
}
}
create_result = subprocess.run(
['npx', '@kernel.salacoste/n8n-workflow-builder'],
input=json.dumps(create_request),
capture_output=True,
text=True
)
create_response = json.loads(create_result.stdout)
return json.loads(create_response['result']['content'][0]['text'])
# Usage
workflow = generate_workflow_from_prompt(
'schedule-triggered-workflow',
{
'workflow_name': 'Daily Report',
'cron_schedule': '0 9 * * *',
'action_description': 'Generate and email daily report',
'timezone': 'America/New_York'
},
instance='production'
)
print(f"Created workflow: {workflow['name']} (ID: {workflow['id']})")
```
---
## Best Practices
### 1. Resource vs Tool Comparison
**Use Resources When:**
- Building read-only dashboards
- Displaying workflow lists
- Showing execution statistics
- Creating monitoring UIs
**Use Tools When:**
- Creating or modifying workflows
- Managing executions
- Performing write operations
- Need fine-grained control
### 2. Prompt Customization
```typescript
// ✅ Good: Descriptive and specific arguments
const workflow = await generateFromPrompt('http-webhook-workflow', {
workflow_name: 'Customer Signup Processor',
webhook_path: 'customer-signup',
processing_description: 'Validate email format, check for duplicates, send welcome email, store in PostgreSQL customers table'
});
// ❌ Avoid: Vague descriptions
const workflow = await generateFromPrompt('http-webhook-workflow', {
workflow_name: 'Webhook',
webhook_path: 'webhook',
processing_description: 'Process data'
});
```
### 3. Prompt-Based Workflow Libraries
```typescript
// Build reusable workflow template library
const workflowTemplates = {
customerSignup: {
prompt: 'http-webhook-workflow',
args: {
workflow_name: 'Customer Signup',
webhook_path: 'customer-signup',
processing_description: 'Email validation → Duplicate check → Welcome email → Database storage'
}
},
dailyBackup: {
prompt: 'schedule-triggered-workflow',
args: {
workflow_name: 'Daily Backup',
cron_schedule: '0 2 * * *',
action_description: 'Backup production database to S3',
timezone: 'UTC'
}
},
slackNotifier: {
prompt: 'external-service-integration',
args: {
workflow_name: 'Error Notifier',
service_name: 'Slack',
trigger_description: 'Application error detected',
action_description: 'Send alert to #ops-alerts channel'
}
}
};
// Generate workflows from library
for (const [name, template] of Object.entries(workflowTemplates)) {
const workflow = await generateFromPrompt(
template.prompt,
template.args,
'production'
);
console.log(`Created ${name}: ${workflow.id}`);
}
```
---
## Next Steps
- **[Workflows API Reference](workflows-api.md)** - Create and manage workflows
- **[API Architecture Overview](overview.md)** - System architecture and components
- **[MCP Resources Guide](../features/mcp-resources.md)** - Complete resources documentation
---
**Document Version:** 1.0
**Last Updated:** January 2025
**Related Epic:** Epic 4 (MCP Resources & Prompts)
