# Instance Routing
How MCP tools route requests to the correct n8n environment.
---
## Routing Mechanism
### Parameter-Based Routing
All MCP tools accept optional `instance` parameter:
```typescript
{
name: "list_workflows",
inputSchema: {
properties: {
instance: {
type: "string",
description: "Instance identifier (optional)"
},
// ... other parameters
}
}
}
```
### Routing Logic
```
1. Tool invoked with parameters
↓
2. Extract instance parameter (if present)
↓
3. If instance provided → Use that instance
If not provided → Use defaultEnv
↓
4. EnvironmentManager.getApiWrapper(instance)
↓
5. Execute API call on selected instance
↓
6. Return results
```
---
## Usage Patterns
### Explicit Instance Selection
**Claude Desktop:**
```
List workflows from production
→ instance: "production"
Show staging executions
→ instance: "staging"
Create workflow in development
→ instance: "development"
```
### Default Instance
**Claude Desktop:**
```
List workflows
→ instance: undefined
→ Uses defaultEnv from .config.json
```
### Instance Context
Claude remembers instance context:
```
User: "List workflows in production"
Claude: [Uses instance: "production"]
User: "Activate workflow 5"
Claude: [Uses instance: "production" from context]
User: "Now list development workflows"
Claude: [Switches to instance: "development"]
```
---
## Multi-Instance Tool Examples
### Workflow Operations
```typescript
// Production
list_workflows({ instance: "production" })
create_workflow({ name: "...", instance: "production" })
activate_workflow({ id: "5", instance: "production" })
// Staging
list_workflows({ instance: "staging" })
get_workflow({ id: "10", instance: "staging" })
// Development (default)
list_workflows() // Uses defaultEnv
```
### Cross-Instance Operations
**Clone workflow across instances:**
```
1. Get workflow from staging
→ get_workflow({ id: "15", instance: "staging" })
2. Create in production
→ create_workflow({
name: workflow.name,
nodes: workflow.nodes,
connections: workflow.connections,
instance: "production"
})
```
**Compare executions:**
```
1. Get production executions
→ list_executions({ instance: "production" })
2. Get staging executions
→ list_executions({ instance: "staging" })
3. Compare success rates
```
---
## Routing Table
### Tool-to-Instance Mapping
| Tool | Instance Param | Default Behavior |
|------|---------------|------------------|
| `list_workflows` | ✅ Supported | Uses defaultEnv |
| `create_workflow` | ✅ Supported | Uses defaultEnv |
| `list_executions` | ✅ Supported | Uses defaultEnv |
| `create_tag` | ✅ Supported | Uses defaultEnv |
| All 17 tools | ✅ Supported | Uses defaultEnv |
**100% Coverage:** All tools support multi-instance routing
---
## Error Handling
### Invalid Instance
```
Request: list_workflows({ instance: "nonexistent" })
Response:
Error: Instance 'nonexistent' not found
Available instances:
- production
- staging
- development
Please use one of the available instance names.
```
### Connection Failure
```
Request: list_workflows({ instance: "production" })
Response:
Error: Failed to connect to instance 'production'
URL: https://prod.n8n.example.com/api/v1
Cause: ECONNREFUSED
Suggestions:
1. Verify n8n is running at production URL
2. Check firewall/network settings
3. Test connectivity: curl https://prod.n8n.example.com
```
---
## Performance Optimization
### Connection Pooling
```
Request 1 (production): 300ms (create + call)
Request 2 (production): 200ms (cached + call)
Request 3 (staging): 300ms (create + call)
Request 4 (production): 200ms (cached + call)
Request 5 (staging): 200ms (cached + call)
```
### Lazy Loading
Only creates connections when needed:
```
Config has 5 instances
→ EnvironmentManager loads config only
User requests from "production"
→ Creates production wrapper
User requests from "staging"
→ Creates staging wrapper
// Only 2 wrappers created (not all 5)
// Memory saved: ~60%
```
---
## Next Steps
- [Configuration](configuration.md) - Setup guide
- [Testing](testing.md) - Validate routing
- [Examples](examples.md) - Real-world usage
- [API Reference](../api/overview.md) - Technical specs
---
!!! info "Implementation"
Routing implementation: `src/services/environmentManager.ts:45`
