Model Context Protocol (MCP)
Abstra now supports the Model Context Protocol (MCP), an open standard that enables secure connections between host applications (like Claude Desktop, VS Code, or other AI tools) and external data sources. This allows AI assistants to interact with your Abstra workflows directly, providing intelligent assistance for workflow development, debugging, and analysis.
Overview
The Model Context Protocol support in Abstra provides a comprehensive set of tools that allow AI assistants to:
- Inspect project structure - Understand your workflow stages, connections, and overall architecture
- Analyze workflow execution - Review execution logs, performance metrics, and task flows
- Debug issues - Investigate failed executions, trace task dependencies, and identify bottlenecks
- Monitor activity - Get real-time insights into workflow performance and system health
- Understand data flow - Trace how data moves through your workflow stages
Getting Started
The MCP server is automatically available when you run the Abstra editor. The MCP endpoints are exposed at /_editor/api/mcp
on your editor server.
When you start your local Abstra editor with:
abstra editor
The MCP server becomes available at http://localhost:3000/_editor/api/mcp
(or whatever port your editor is running on).
Connecting to AI Tools
Once the MCP server is running, you can connect it to various AI tools that support the Model Context Protocol:
Claude Desktop
Add the following configuration to your Claude Desktop MCP settings to connect to your local Abstra editor:
{
"mcpServers": {
"abstra": {
"transport": "http",
"url": "http://localhost:3000/_editor/api/mcp"
}
}
}
Note: Replace localhost:3000
with your actual editor server URL and port. You can find your editor server port in the terminal output when you run abstra editor
.
VS Code with MCP Extensions
Configure your VS Code MCP extension by creating a .vscode/mcp.json
file in your project root:
{
"inputs": [
{
"type": "promptString",
"id": "abstra-port",
"description": "Abstra Editor Port (check terminal output when running 'abstra editor')"
}
],
"servers": {
"abstra": {
"type": "http",
"url": "http://localhost:${input:abstra-port}/_editor/api/mcp"
}
}
}
This configuration will prompt you for your Abstra editor port on first use. Refer to the VS Code MCP documentation for detailed setup instructions.
Available Tools
The Abstra MCP server provides the following comprehensive set of tools:
Project Structure Analysis
list_stages
- Get all workflow stages (forms, hooks, jobs, scripts)read_stage_file
- Read the Python code of any stageget_project_overview
- Get comprehensive project statistics and structureget_workflow_graph
- Retrieve workflow as nodes and edges for visualization
Stage Management
get_stage_details
- Get detailed information about a specific stageget_last_executions_for_stage
- View recent executions for a stage
Task Tracking
get_all_tasks
- Retrieve all tasks in the workflow systemget_pending_tasks_for_stage
- Get tasks waiting for a specific stageget_sent_tasks_from_stage
- Get tasks created by a specific stageget_stage_tasks
- Get all tasks associated with a stageget_task_by_id
- Get detailed information about a specific taskget_tasks_by_type
- Filter tasks by type (e.g., 'approved', 'invoice_needed')get_task_flow_summary
- Get analytics about task distribution and flow patterns
Execution Monitoring
get_last_executions
- Get recent executions with filtering optionsget_execution_by_id
- Get detailed execution informationget_execution_logs
- Retrieve stdout/stderr logs from executionsget_execution_sent_tasks
- Get tasks created during a specific execution
Recent Activity & Analytics
get_last_tasks
- Get recent tasks with filteringget_last_tasks_sent_by
- Get recent tasks sent by a specific stageget_last_tasks_received_by
- Get recent tasks received by a specific stageget_recent_activity_summary
- Get activity overview for the last N hours
Use Cases
Workflow Development
AI assistants can help you:
- Understand the current project structure
- Identify missing connections between stages
- Suggest improvements to workflow design
- Review code quality in stage implementations
Debugging
When workflows aren't behaving as expected:
- Trace execution paths through the workflow
- Identify failed stages and error messages
- Analyze task flow bottlenecks
- Review execution logs for specific runs
Performance Analysis
Monitor and optimize your workflows:
- Track execution times and success rates
- Identify stages with high failure rates
- Analyze task processing patterns
- Monitor recent activity trends
Documentation & Understanding
For existing projects:
- Generate documentation from workflow structure
- Explain complex workflow logic
- Create visual representations of data flow
- Understand the purpose of different stages
Example Interactions
Here are some example questions you can ask an AI assistant connected to your Abstra workflow via MCP:
Project Understanding:
- "What stages are in this workflow and how are they connected?"
- "Show me the Python code for the invoice processing stage"
- "What's the overall structure of this project?"
Debugging:
- "Why did the last execution fail?"
- "Show me the error logs for execution ID abc123"
- "Which stages have the highest failure rate?"
Monitoring:
- "What tasks are currently pending?"
- "Show me activity from the last 24 hours"
- "How many tasks has the approval stage processed today?"
Analysis:
- "What's the typical flow of data through this workflow?"
- "Which stages create the most tasks?"
- "Show me performance metrics for the last week"
Security & Access
The MCP server provides read-only access to your workflow data. It cannot:
- Modify workflow stages or code
- Create, update, or delete tasks
- Change project configuration
- Execute stages or trigger workflows
This ensures that AI assistants can help you understand and analyze your workflows without the risk of unintended modifications.
Technical Details
The Abstra MCP server implements the Model Context Protocol specification version 2025-06-18, providing:
- JSON-RPC 2.0 communication protocol
- Automatic tool discovery - AI assistants can discover available tools
- Type-safe parameters - All tool parameters are validated with JSON schema
- Comprehensive error handling - Clear error messages for debugging
- CORS support - Cross-origin requests for web-based AI tools
The server exposes your workflow data through a REST API that follows MCP standards, making it compatible with any MCP-compliant AI assistant or tool.
Troubleshooting
Connection Issues
If your AI assistant can't connect to the MCP server:
- Ensure the Abstra editor is running with
abstra editor
- Check that your AI tool is configured with the correct MCP server settings and URL
- Verify that your project is properly initialized with
abstra.json
Missing Data
If some workflow data isn't appearing:
- Make sure your workflow project is saved and up to date
- Check that all stages are properly configured
- Verify that the Abstra project is in the correct working directory
Performance
For large workflows with many executions:
- The MCP server automatically limits result sets to prevent overwhelming responses
- Use the filtering parameters (like
limit
andoffset
) to paginate through large datasets - Consider using specific time ranges for activity queries