Connecting an MCP Client to Stream

Connecting an MCP Client to Stream

This guide walks you through exposing Stream as an MCP (Model Context Protocol) server so an AI client (Claude Desktop, Claude Code, or any other MCP-aware tool) can read records, inspect connectors, manage alerts, and run other Stream operations on your site.

Stream itself does not implement MCP. It registers its operations as WordPress Abilities API abilities (WordPress 6.9+) and tags them as MCP-discoverable. The actual MCP server is provided by the WordPress MCP Adapter plugin.

┌──────────────┐    HTTP    ┌─────────────────────┐    PHP    ┌──────────────────┐
│  MCP client  │ ─────────► │ mcp-adapter plugin  │ ────────► │ Stream abilities │
│ (Claude etc) │            │ (WP MCP server)     │           │ (stream/*)       │
└──────────────┘            └─────────────────────┘           └──────────────────┘

---

Requirements

• WordPress 6.9+. Stream's Abilities API integration is a silent no-op on older versions.
• Stream plugin updated to the version that includes Abilities API + MCP support (see step 1).
• WordPress MCP Adapter plugin installed and active (step 2).
• HTTPS on the site. MCP clients and WordPress Application Passwords require it.
• A WordPress Application Password for the user the MCP client will authenticate as.

---

1. Install or update Stream

Make sure you are running the Stream version that ships the Abilities API + MCP integration. The toggle described in step 3 only appears in this version.

• From the WordPress admin: go to Plugins → Installed Plugins, find Stream, and click Update Now if an update is available. If Stream is not installed yet, go to Plugins → Add New, search for "Stream", and click Install Now followed by Activate.

• From WP-CLI:

  wp plugin install stream --activate
  # or, if already installed:
  wp plugin update stream

On a network-activated multisite, append --network to the activation command.

---

2. Install and activate the MCP Adapter plugin

The MCP Adapter is not yet on the wordpress.org plugin directory, so you have to install it from GitHub.

cd wp-content/plugins
git clone https://github.com/WordPress/mcp-adapter
cd mcp-adapter
composer install --no-dev
wp plugin activate mcp-adapter

On a network-activated multisite, use wp plugin activate mcp-adapter --network.

Verify the adapter is responding

Once activated, the default MCP server route should answer:

curl -sk https://your-site.example/wp-json/mcp/mcp-adapter-default-server

You should get a JSON response (the contents vary by adapter version). A 404 here means the plugin isn't active or rewrite rules haven't been flushed (wp rewrite flush).

---

3. Enable the Abilities API in Stream

Stream ships every ability with meta.mcp.public = true, but the registration is gated by a setting so MCP exposure is opt-in.

1. Go to Stream → Settings → Advanced.
   • On a network-activated multisite install, open Network Admin → Stream → Settings → Advanced. Per-site settings hide this toggle because it persists at the network level (wp_stream_network option).
2. Tick "Enable Abilities API and MCP".
3. Click Save Changes.

Verify the abilities are now registered:

curl -u admin:app-password \
  https://your-site.example/wp-json/wp-abilities/v1/abilities?category=stream

You should see all 11 Stream abilities listed (stream/get-records, stream/get-connectors, stream/create-alert, etc.).

---

4. Create an Application Password

MCP clients connect over HTTP and need an authenticated user. WordPress Application Passwords are the recommended mechanism.

1. Go to Users → Profile (or Users → All Users → Edit for the target user).
2. Scroll to Application Passwords.
3. Enter a name (e.g. Claude Desktop) and click Add New Application Password.
4. Copy the 24-character password. You will not see it again.

Application Passwords are only available over HTTPS. If you don't see the section, confirm your site is served over https:// and that your user has the manage_options capability (or whichever capability your install requires for app passwords).

---

5. Register Stream with your MCP client

Claude clients connect to a WordPress MCP server through the @automattic/mcp-wordpress-remote stdio bridge. It runs locally via npx, authenticates to your site with an Application Password, and proxies tool calls to the MCP Adapter endpoint.

You need Node.js available on the machine where the Claude client runs (npx ships with Node).

Claude Code (CLI)

Register the server scoped to your user so it works from any project directory:

claude mcp add-json stream --scope user '{
  "type": "local",
  "command": ["npx", "-y", "@automattic/mcp-wordpress-remote@latest"],
  "environment": {
    "WP_API_URL": "https://your-site.example/wp-json/mcp/mcp-adapter-default-server",
    "WP_API_USERNAME": "admin",
    "WP_API_PASSWORD": "xxxx xxxx xxxx xxxx xxxx xxxx"
  }
}'

Replace WP_API_USERNAME and WP_API_PASSWORD with your WordPress username and the Application Password from step 4. Keep the spaces in the password.

Then inside any Claude Code session:

/mcp

You should see stream listed as connected. Try a prompt like "discover abilities" or "show me the last 10 Stream records".

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows) and add:

{
  "mcpServers": {
    "stream": {
      "type": "local",
      "command": ["npx", "-y", "@automattic/mcp-wordpress-remote@latest"],
      "environment": {
        "WP_API_URL": "https://your-site.example/wp-json/mcp/mcp-adapter-default-server",
        "WP_API_USERNAME": "admin",
        "WP_API_PASSWORD": "xxxx xxxx xxxx xxxx xxxx xxxx"
      }
    }
  }
}

Restart Claude Desktop. The Stream tools appear under the plug icon in the chat input.

Other MCP clients (Cursor, Cline, VS Code, etc.) accept the same JSON shape; consult their docs for where to paste it.

Verifying the connection

Once connected, prompt the client with:

"List all available abilities under the stream namespace."

You should see 11 abilities returned, ranging from stream/get-records (read) to stream/purge-records (destructive, gated).

---

6. What you can do over MCP

Once connected, the following Stream operations are available as tools:

Ability	Purpose
stream/get-records	Query records with the full filter set (date, connector, context, action, user, etc.).
stream/get-record	Fetch a single record by ID, including meta.
stream/get-connectors	List registered connectors and their action/context labels.
stream/get-settings	Read current Stream settings.
stream/get-alerts	List existing alerts.
stream/get-exclusion-rules	Read exclusion rules.
stream/create-alert	Create a new alert.
stream/create-exclusion-rule	Append an exclusion rule.
stream/update-settings	Partial-merge update of Stream settings.
stream/delete-alert	Delete an alert by ID.
stream/purge-records	Filtered cascade delete of records. Requires confirm: true AND at least one filter.

All abilities require manage_options on the WordPress side. Stream's view_stream cap mapping is also honored for read abilities so users granted access via Settings → Role Access can query records over MCP.

Disabling MCP exposure

To turn it off, untick Enable Abilities API and MCP in Stream settings. The abilities are immediately unregistered on the next request, and the MCP Adapter has nothing left to expose under the stream/ namespace. The adapter plugin itself can remain active for other plugins.

To go further, deactivate the MCP Adapter plugin entirely. Stream's abilities remain available via the standard /wp-abilities/v1/stream/* REST routes for non-MCP consumers.

References

• WordPress MCP Adapter
• WordPress Abilities API
• Abilities API REST routes
• Stream developer notes (local dev env setup): contributing.md.