WAHA 2026.4 - MCP Server, API Key Scopes, Query Auth

🤖 MCP Server

WAHA now ships a built-in Model Context Protocol server. Any MCP-compatible AI agent — Claude, Goose, and others — can send messages, read chats, and manage contacts through your own self-hosted instance.

You create one MCP App per WhatsApp session. Each app gets its own scoped API key so you decide exactly what the agent is allowed to do — send only, read only, or any combination. — #1925

Check the 🧩 MCP docs for the full setup guide.

🔒 API Key Session Scopes

Session API keys now support an actions field that limits what the key can do within its session. Previously all session keys had the same set of permissions. Now you can create a read-only key for a dashboard, a send-only key for a bot, or a media-only key for embedding images — without granting any extra access.

Available scopes:

POST /api/keys

{
  "isAdmin": false,
  "session": "default",
  "isActive": true,
  "actions": {
    "read": true,
    "send": false,
    "control": false,
    "setting": false,
    "app": false,
    "delete": false
  }
}

See 🔒 Session Key Scopes for the full reference. — #2035

🔑 x-api-key Query Parameter

You can now pass the API key as a URL query parameter:

GET /api/files/true_11111111111@c.us_AAA.jpg?x-api-key=your-key

This is useful when you cannot set headers — for example, putting a media URL directly into an <img> tag in a browser.

⚠️ Never embed your admin or full-session key in a URL. Create a dedicated session key with only the scopes the consumer actually needs (for media-only access you can set all action scopes to false).

See 🔒 Use x-api-key query parameter for details.

🛠️ Other Fixes

GOWS

• Sessions taking a long time to start after server restart — fixed. — #2012
• 403 on some media downloads — fixed with re-upload request from the phone. — #2049
• GET /api/messages not returning messages sent via POST /api/sendFile. — #1998
• /chats/overview “no such column: jid” error. — #2009

NOWEB

• Missing Facebook and Instagram Ads messages. — #1922
• MongoDB GET /api/messages timestamp range filter (gte + lte combined) not respected. — #2011
• 0-byte audio/voice files on media download — now uses stream mode. — #1996

WEBJS

• window is undefined error. — #1990
• call.received event broken. — #2014
• Loading messages fix. — #2005, #2013

Other

• WHATSAPP_FILES_LIFETIME 32-bit setTimeout overflow causing immediate file deletion. — #2018, #2019

⚙️ Full Changelog

All versions, issue links, and engine bumps are in the 🆕 WAHA 2026.4 Changelog.