Skip to main content

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 stage
  • get_project_overview - Get comprehensive project statistics and structure
  • get_workflow_graph - Retrieve workflow as nodes and edges for visualization

Stage Management​

  • get_stage_details - Get detailed information about a specific stage
  • get_last_executions_for_stage - View recent executions for a stage

Task Tracking​

  • get_all_tasks - Retrieve all tasks in the workflow system
  • get_pending_tasks_for_stage - Get tasks waiting for a specific stage
  • get_sent_tasks_from_stage - Get tasks created by a specific stage
  • get_stage_tasks - Get all tasks associated with a stage
  • get_task_by_id - Get detailed information about a specific task
  • get_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 options
  • get_execution_by_id - Get detailed execution information
  • get_execution_logs - Retrieve stdout/stderr logs from executions
  • get_execution_sent_tasks - Get tasks created during a specific execution

Recent Activity & Analytics​

  • get_last_tasks - Get recent tasks with filtering
  • get_last_tasks_sent_by - Get recent tasks sent by a specific stage
  • get_last_tasks_received_by - Get recent tasks received by a specific stage
  • get_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:

  1. Ensure the Abstra editor is running with abstra editor
  2. Check that your AI tool is configured with the correct MCP server settings and URL
  3. Verify that your project is properly initialized with abstra.json

Missing Data​

If some workflow data isn't appearing:

  1. Make sure your workflow project is saved and up to date
  2. Check that all stages are properly configured
  3. 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 and offset) to paginate through large datasets
  • Consider using specific time ranges for activity queries

Learn More​