Run MCP in the Browser The SDK allows you to run an MCP server as a JavaScript module in the browser, so there is no need for creating a PHP-based MCP server or creating an external SSE or HTTPStreamable-based MCP Server.

All logic runs client-side while you can use WP REST or even adminAjax to communicate with your plugin backend.
Register MCP with Angie Without an External Server You can register your MCP directly with Angie using the SDK, even if you don't have an external MCP Gateway. Angie discovers your server through the SDK.
Communicate with MCP on the Current Screen The SDK enables Angie to communicate with your plugin's MCP directly on the current page, so Angie will be able to see and act on the current user's screen.

How It Works

Angie SDK allows you to use the official TypeScript MCP SDK to write your MCP Server. Then with Angie SDK you can register it and let Angie run your MCP server like other MCP Hosts.

The SDK covers three main abilities:

Import and use the current supported official MCP SDK
Register your MCP Server
Run your MCP server in the browser

┌──────────────────────────────┐
│       Angie SDK Flow         │
├──────────────────────────────┤
│                              │
│  Your WordPress Plugin       │
│            │                 │
│            │ enqueue script  │
│            ▼                 │
│  Your MCP Server (JS)        │
│            │                 │
│            │ register server │
│            ▼                 │
│  Angie SDK                   │
│            │                 │
│            ◄─► Browser       │
│            │   Transport     │
│            ▼                 │
│  Angie (iframe)              │
│                              │
└──────────────────────────────┘

Supported MCP Features

Resources
Notifications
Tools
Sampling

Installation

npm install @elementor/angie-sdk

Quick Start

1. Create Your MCP Server

Create a TypeScript or a Javascript file (e.g., demo-mcp-server.ts):

import {
  AngieMcpSdk,
  CallToolRequest,
  CallToolRequestSchema,
  ListToolsRequestSchema,
  McpServer,
} from '@elementor/angie-sdk';

// Define the MCP server
function createSeoMcpServer() {
  const server = new McpServer(
    { name: 'my-seo-server', version: '1.0.0' },
    { capabilities: { tools: {} } }
  );

  // Add your tools, resources, etc.
  server.tool( ... );

  return server;
}

// Register the server with Angie
const server = createSeoMcpServer();
const sdk = new AngieMcpSdk();
await sdk.registerServer({
  name: 'my-seo-server',
  version: '1.0.0',
  description: 'SEO tools for Angie',
  server,
});

Triggering Angie with Prompts

The SDK can also trigger Angie with custom prompts - useful for help buttons or deep linking.

import { AngieMcpSdk } from '@elementor/angie-sdk';

// Register your MCP server and trigger Angie
const server = createSeoMcpServer();
const sdk = new AngieMcpSdk();
await sdk.registerServer({
  name: 'my-seo-server',
  version: '1.0.0',
  description: 'SEO tools for Angie',
  server,
});

// Trigger Angie with a prompt
await sdk.triggerAngie({
  prompt: 'Help me optimize this page for SEO',
  context: { pageType: 'product', source: 'my-plugin' },
  options: {
    timeout: 30000, // Optional: 30 seconds timeout (default: 30000)
    
  }
});

// Or simplified version
await sdk.triggerAngie({
  prompt: 'Help me create a contact page'
});

Options:

timeout: How long to wait for Angie response (milliseconds)
priority: Request priority level
context: Additional data to help Angie understand the request

Hash Parameter Method

// Trigger via URL hash - perfect for deep linking
window.location.hash = 'angie-prompt=' + encodeURIComponent('Help me create a contact page');

// Or visit URLs like: https://yoursite.com/wp-admin/edit.php#angie-prompt=Help%20me%20optimize%20SEO

Note: Always call await sdk.waitForReady() before triggering Angie.

MCP Server Example

A typical project structure:

your-plugin/
├── plugin.php               # Main WordPress plugin file
├── dist/
│   └── demo-mcp-server.js    # Bundled MCP server JS
├── src/
│   └── demo-mcp-server.ts    # MCP server source
└── ...

PHP: Implements REST API endpoints for your tool - if needed.
JS/TS: Registers tools and handles requests using the SDK.

Registering Tools

Each tool must be registered with:

name: Unique string identifier
description: What the tool does and when to use it
inputSchema: JSON schema describing required/optional parameters

Example:

server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [
    {
      name: 'analyze-page-seo',
      description: 'Analyzes the SEO of a page.',
      inputSchema: {
        type: 'object',
        properties: { url: { type: 'string', description: 'Page URL' } },
        required: ['url'],
      },
    },
  ],
}));

Handling Tool Calls

Implement a handler for CallToolRequestSchema:

server.setRequestHandler(CallToolRequestSchema, async (request: CallToolRequest) => {
  const { name, arguments: args } = request.params;
  switch (name) {
    case 'analyze-page-seo':
      // Call your backend or perform logic
      const { root, nonce } = window.wpApiSettings;
      const response = await fetch(`${root}my-plugin/v1/analyze-seo`, {
        method: 'POST',
        headers: {
          'X-WP-Nonce': nonce,
          'Content-Type': 'application/json',
        },
        credentials: 'same-origin',
        body: JSON.stringify(args),
      });
      
      if (!response.ok) {
        throw new Error(`API request failed: ${response.statusText}`);
      }
      
      const result = await response.json();
      return {
        content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
      };
    // Add more cases as needed
    default:
      throw new Error(`Unknown tool: ${name}`);
  }
});

Best Practices

Tool Naming: Use clear, outcome-focused names (e.g., "analyze-page-seo").
Descriptions: Clearly describe what the tool does, when to use it, and what it returns.
Input Schemas: Define precise input schemas for each tool, prefer using Zod.
Error Handling: Return user-friendly errors in natural language and log details for debugging.
Security: Use nonces for REST API calls and permission checks in your backend.
Versioning: Angie SDK exports the current supported MCP SDK, prefer to use the integrated MCP SDK to ensure supported MCP version features.

Security

⚠️ Security Responsibility: When you create MCP tools that interact with your WordPress backend, you become responsible for the security of those operations. Angie acts as a channel for user actions, so it's your responsibility to implement proper security measures.

Required Security Measures

Permission Checks: Always verify user permissions on your backend endpoints
Input Validation: Sanitize and validate all input data
Capability Checks: Use WordPress capability checks for specific operations

Example Secure Endpoint

add_action('rest_api_init', function () {
    register_rest_route('my-plugin/v1', '/analyze-seo', [
        'methods' => 'POST',
        'callback' => 'my_analyze_seo_callback',
        'permission_callback' => function () {
            return current_user_can('edit_posts');
        },
        'args' => array(
          'url' => array(
            'validate_callback' => function($param, $request, $key) {
              return filter_var($param, FILTER_VALIDATE_URL);
            },
            'required' => true,
          ),
        ),
    ]);
});

Remote SSE and HTTP Streamable MCP servers

For remote servers, let your Angie users add them via Angie MCP Gateway settings.

Supported Remote Server Types

SSE (Server-Sent Events): For real-time streaming responses
HTTP Streamable: For HTTP-based streaming communication

Configuration

Remote MCP servers can be configured through Angie's settings interface, allowing users to connect to external MCP services without requiring code changes.

Error Handling

Throw errors in handlers to return error responses to the client.
Use custom error messages for user-facing errors.
Log errors internally as needed.

Example:

server.setRequestHandler(CallToolRequestSchema, async (req) => {
  try {
    // Your tool implementation
    const result = await performToolAction(req.params);
    return {
      content: [{ type: 'text', text: result }],
    };
  } catch (err) {
    console.error('Tool error:', err);
    throw new Error('User-friendly error message');
  }
});

Changelog

v1.0.0: Initial release

Demo Plugin

For more examples, see the demo plugin and MCP server in the example folder

If you have questions or need help, open an issue or contact the Elementor team!

Debugging & Testing

Use browser console logs to verify server registration and tool calls.
Test REST endpoints directly (e.g., with Postman) before wiring up the MCP server.
Check Angie's UI for tool discovery and invocation.

Common Debugging Steps

Check browser console for registration errors
Verify tool names match between registration and handler
Test REST API endpoints independently
Ensure proper nonce and permission setup

Dev Mode for Enhanced Debugging

Angie includes a Dev Mode feature that displays tool execution progress and details directly in the chat interface, making it easier to debug your MCP server integrations and understand how Angie interacts with your tools.

To enable Dev Mode:

Open Angie in WordPress
Click on the User Profile icon
Navigate to Tools
Toggle "Dev Mode" on

What Dev Mode shows: When enabled, Angie will display in the chat:

Tool execution history for each user request
Tool call status (pending, in progress, completed, failed)
Tool input and output

License

MIT

Keywords

mcp

model-context-protocol

angie

elementor

sdk

FAQs

What is @elementor/angie-sdk?

Is @elementor/angie-sdk popular?

Is @elementor/angie-sdk well maintained?

Package last updated on 20 Oct 2025

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

@elementor/angie-sdk