SwitchX MCP

A remote Model Context Protocol server for SwitchX, deployed on Cloudflare Workers.

SwitchX MCP exposes a small, focused set of tools for AI clients to work with SwitchX social primitives:

• communities
• channels
• groups
• messages

It is designed for clients such as Hermes, Cursor, Claude Desktop via a remote MCP adapter, or any MCP-compatible host that supports Streamable HTTP.

Public endpoints

MCP endpoint:    https://mcp.switchx.gg/mcp
Health endpoint: https://mcp.switchx.gg/health

Health check:

curl https://mcp.switchx.gg/health

Expected response:

{"status":"ok","service":"switchx-mcp"}

Authentication

The MCP endpoint uses the connecting SwitchX user’s own auth token.

Every MCP request to /mcp must include:

Authorization: Bearer 

The Worker does not use a shared MCP token. It forwards the user token to the SwitchX backend so permissions remain user-scoped.

This means:

• a valid SwitchX user token is required to connect;
• backend authorization still decides what the user can do;
• tools that create, update, or delete resources run with the user’s permissions.

/health is public and does not require auth.

Available tools

Tool names are registered as MCP tools by the server. Hermes prefixes remote MCP tools with the configured server name, for example:

mcp_switchx_switchx_create_community

The raw MCP tool names are:

Communities

Channels

Groups

Messages

Intentional v1 non-goals

SwitchX MCP v1 intentionally does not expose:

• quests;
• roles;
• moderation tools;
• stickers;
• organizations;
• games or leaderboards;
• ads;
• sessions;
• instant messaging configuration;
• webhook triggers.

The goal is to keep the public MCP surface small and social-core focused.

Using with Hermes Agent

Hermes supports remote HTTP MCP servers. Add this to the Hermes config:

mcp_servers:
  switchx:
    url: "https://mcp.switchx.gg/mcp"
    headers:
      Authorization: "Bearer ${SWITCHX_USER_TOKEN}"
    timeout: 180
    connect_timeout: 60
    enabled: true

Store the user token in your Hermes .env:

SWITCHX_USER_TOKEN=

Then restart Hermes or reload MCP:

/reload-mcp

Hermes will discover tools with the mcp_switchx_ prefix.

Using with a generic MCP client

Use Streamable HTTP transport and set:

URL: https://mcp.switchx.gg/mcp
Authorization: Bearer 

The MCP client must send an Accept header that includes both:

Accept: application/json, text/event-stream

Local development

Requirements:

• Node.js
• npm
• Wrangler
• Cloudflare account access for deployment

Install dependencies:

npm install

Run the Worker locally:

npm run dev

Run static verification:

npm run verify

This runs:

• TypeScript type checking;
• Vitest unit tests.

Live verification

The live verifier exercises the real SwitchX backend with disposable resources.

It requires a real SwitchX user token:

SWITCHX_USER_TOKEN= \
SWITCHX_API_BASE_URL=https://ai.switchx.gg \
npm run verify:live

The live verifier checks the full flow:

• create community;
• get community;
• list communities;
• update community;
• create/list/update/delete channel;
• create/list/update/delete group;
• send channel/group messages;
• read channel/group history;
• get/edit/delete message.

A successful run should end with:

passed: 19
failed: 0

The verifier creates disposable test communities and cleans up created channels, groups, and test messages. It does not currently delete the test community itself.

Deployment

This project deploys as a Cloudflare Worker custom domain:

{
  "routes": [
    {
      "pattern": "mcp.switchx.gg",
      "custom_domain": true
    }
  ]
}

Deploy:

npm run deploy

Dry-run deployment check:

npx wrangler deploy --dry-run

nodejs_compat is enabled because the Cloudflare Agents SDK dependency tree imports Node built-ins during bundling.

Project structure

src/
  index.ts                Cloudflare Worker entrypoint
  app.ts                  Testable route/auth shell
  auth.ts                 SwitchX bearer token extraction
  http.ts                 JSON response/query helpers
  mcp/
    server.ts             MCP server and tool registration
    schemas.ts            Zod input schemas
    toolDefinitions.ts    Tool catalog used by tests/docs
  switchx/
    client.ts             SwitchX backend REST client
    mappers.ts            MCP input -> SwitchX API payload mapping
scripts/
  verify-live.mjs         Live backend verification harness
tests/
  *.test.ts               Unit tests

Event triggers and webhooks

This MCP server is an action/tool layer. It is not the event trigger layer.

For agents to react to new SwitchX community messages, use an event trigger such as:

SwitchX backend -> webhook or queue -> Hermes -> SwitchX MCP tools

Recommended flow:

1. SwitchX emits message.created.
2. A webhook or Cloudflare Queue normalizes and deduplicates the event.
3. Hermes receives the event.
4. Hermes calls SwitchX MCP tools such as switchx_get_message or switchx_send_message.

MCP roots are not used for SwitchX message triggers. Roots are filesystem boundaries for MCP clients and servers, not an app event system.

Security notes

• Do not commit SwitchX user tokens.
• Do not put tokens in wrangler.jsonc.
• Use environment variables or the MCP client’s secret storage for user tokens.
• Treat any token pasted into logs or chat as exposed and rotate it when possible.
• The Worker forwards user credentials to SwitchX backend APIs, so backend permission checks remain the source of truth.