simetrik-inc-public/a4e-mcp-server

A4E MCP Server

The A4E MCP Server enables creators to build agents using natural language directly in their IDE (Cursor, Claude Desktop).

Installation

Prerequisites

1. Python 3.10+
2. uv (recommended) or pip
3. ngrok Account: Required for "Dev Mode" to share your local agent with the Hub.
   • Sign up at ngrok.com
   • Get your Authtoken from the dashboard.

Setup

1. Navigate to this directory:

   cd a4e-mcp-server
   

2. Install dependencies:

   uv sync
   

3. Configure ngrok (One-time setup):

   ngrok config add-authtoken <YOUR_TOKEN>
   

   Or pass it later to dev_start.

Usage in Cursor

Option 1: MCP Settings UI

1. Go to Cursor Settings > Features > MCP.
2. Click + Add New MCP Server.
3. Enter:
   • Name: a4e
   • Type: command
   • Command: uv
   • Args: run --directory /path/to/a4e-mcp-server python -m a4e.server

Option 2: mcp.json Configuration (Recommended)

Edit ~/.cursor/mcp.json (or .cursor/mcp.json in your project):

{
  "mcpServers": {
    "a4e": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/a4e-mcp-server",
        "python",
        "-m",
        "a4e.server",
        "--project-dir",
        "/absolute/path/to/a4e-mcp-server"
      ]
    }
  }
}

Example for macOS:

{
  "mcpServers": {
    "a4e": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/Users/yourname/Documents/a4e-mcp-server",
        "python",
        "-m",
        "a4e.server",
        "--project-dir",
        "/Users/yourname/Documents/a4e-mcp-server"
      ]
    }
  }
}

Configuration Options

After adding, restart Cursor to load the MCP server. You should see 21 tools available.

Usage in Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "a4e": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/a4e-mcp-server",
        "python",
        "-m",
        "a4e.server"
      ]
    }
  }
}

Concepts

What is an A4E Agent?

An A4E Agent is a specialized AI assistant tailored for a specific domain or task (e.g., a Nutrition Coach or Daily Planner). It combines natural language understanding with custom capabilities defined by Tools and Views.

Tools

Tools are Python functions that give the agent the ability to perform actions or retrieve information.

• Defined in tools/*.py using the @tool decorator.
• The agent decides when to call a tool based on the user's request.
• How it works: When you ask "Calculate BMI", the agent looks for a tool capable of that calculation, executes the Python code, and returns the result.

Views

Views are React components that provide a rich graphical interface for the agent's responses.

• Defined in views/*/view.tsx.
• Used to display structured data (like charts, lists, or forms) instead of just text.
• How it works: If a tool returns complex data (like a meal plan), the agent can choose to render a specific view (e.g., MealPlanView) to show that data interactively.

Workflow

1. Create an Agent: Open a new folder in Cursor (e.g., my-agents/). Ask Cursor: "Create a nutrition coach agent" -> This creates the folder nutrition-coach with agent.py, metadata.json, etc.

2. Add Tools: Ask: "Add a tool to calculate BMI" -> Creates tools/calculate_bmi.py.

3. Add Views: Ask: "Add a view to show the BMI result" -> Creates views/bmi_result/view.tsx.

4. Auto-Generate Schemas: The server automatically generates schemas from your Python code and React props when you run generate_schemas (or when the file watcher triggers, if enabled).

Where are agents created?

Agents are created in your current working directory.

• If you want to add an agent to the agent-store, open that folder in Cursor first.
• If you are testing, just create a temporary folder.

Integration

• Local Dev: dev_start - Starts local server and ngrok tunnel.
• Deployment: deploy (Mocked) - Will upload to S3 and register with the Hub.

Troubleshooting

"pyngrok not installed"

If dev_start fails, it means the MCP server environment is missing dependencies.

1. Run check_environment tool to diagnose.
2. Ensure you ran uv sync in the a4e-mcp-server directory.
3. Restart your IDE/MCP Client to reload the environment.

"ngrok command not found"

If you don't want to use pyngrok, install the ngrok CLI manually:

• Mac: brew install ngrok/ngrok/ngrok
• Windows: choco install ngrok

Agent Skills

This repository includes an Agent Skills compatible skill that teaches AI assistants how to build A4E agents using natural language.

What's Included

The A4E Agent Builder skill provides comprehensive knowledge about:

• Agent architecture and directory structure
• MCP server tools and their usage
• Database integration patterns (SQLite, Supabase, PostgreSQL, MySQL, MongoDB)
• Mobile-optimized view development
• UI/UX design system and guidelines
• Deployment workflows and best practices

Installation

Location: skills/a4e-agent-builder/

The skill works across multiple AI development tools including:

• Claude Code
• Cursor
• Claude Desktop
• VS Code with Continue
• Windsurf
• Cline
• Aider
• Any Agent Skills compatible tool

Quick Install for Claude Code:

# Copy to personal skills directory
cp -r skills/a4e-agent-builder ~/.claude/skills/

# Or create a symlink for auto-updates
ln -s "$(pwd)/skills/a4e-agent-builder" ~/.claude/skills/

For other platforms and detailed instructions: See

Usage

Once installed, the skill is automatically available:

• Automatic activation: Ask questions about building A4E agents
• Direct invocation: Use /a4e-agent-builder in supported tools
• Reference access: The skill provides access to detailed guides on demand

Benefits

• Portable knowledge: Works across 20+ AI development tools
• Always up-to-date: Git-based installation makes updates easy
• Comprehensive: Covers all aspects of A4E agent development
• Standards-compliant: Follows the open Agent Skills format