CF ActivityPub MCP

English | Español

A remote Model Context Protocol server that lets AI assistants administer a CF ActivityPub instance through its administration API — fully hosted on Cloudflare Workers.

Overview

CF ActivityPub MCP is the administration companion for CF ActivityPub Next, the Mastodon-compatible ActivityPub server built for Cloudflare Workers.

Point it at your instance with the same ADMIN_TOKEN operator secret, connect any MCP-capable assistant, and manage accounts, reports, federation rules, relays, media cache, settings and more through natural conversation. The worker:

• Exposes the full administration surface as 30 well-described MCP tools.

• Speaks Streamable HTTP (/mcp, JSON responses) and an SSE-shaped endpoint (/sse) for clients that require it.

• Requires its own bearer token (MCP_AUTH_TOKEN) on every MCP request, independent from the instance token.

• Publishes a public landing page and a /health JSON report with live metrics.

• Runs with Cloudflare observability (traces, logs and real-time issues) enabled.

• Deploys to a custom domain with a single wrangler deploy.

The MCP never stores instance data: every tool call is a thin, authenticated proxy to the CF ActivityPub admin API, which keeps its own audit trail.

Related MCP server: BYOB MCP Server

Architecture

Endpoints

Modern protocol revisions (2026-07-28) receive JSON responses; legacy clients are served through the stateless compatibility lane. The deprecated HTTP+SSE session transport (a long-lived GET /sse stream plus POST /messages) is intentionally not implemented — point legacy clients at /mcp (or use a proxy such as mcp-remote).

Requirements

• A deployed CF ActivityPub Next instance with ADMIN_TOKEN configured (wrangler secret put ADMIN_TOKEN in that project).

• A Cloudflare account with the domain you want to use.

• Node.js 20+ and npm.

Quick start

# 1. Install dependencies
npm install

# 2. Configure the instance URL (and optionally the custom domain)
#    Edit `vars` in wrangler.jsonc: ACTIVITYPUB_URL=https://social.example.com

# 3. Create the two secrets
npx wrangler secret put ADMIN_TOKEN      # same value as the instance's ADMIN_TOKEN
npx wrangler secret put MCP_AUTH_TOKEN   # openssl rand -hex 32

# 4. Local development
npm run dev

# 5. Deploy
npm run deploy

For local development, copy .dev.vars.example to .dev.vars and fill in both tokens.

Configuration

Plain-text variables (vars in wrangler.jsonc)

Secrets (wrangler secret put)

Authentication

Two independent credentials are involved:

1. MCP clients → this worker. Every request to /mcp or /sse must include Authorization: Bearer <MCP_AUTH_TOKEN>. Requests are rejected with 401 otherwise, and the endpoint is closed with 503 when the secret is not configured. Token comparison hashes both values before comparing to avoid timing leaks.

2. This worker → the ActivityPub instance. Tool calls send Authorization: Bearer <ADMIN_TOKEN> to the instance admin API. The instance validates it with its own admin-auth logic and writes every mutation to the moderation log.

Rotate each token independently: changing MCP_AUTH_TOKEN only affects MCP access; changing ADMIN_TOKEN must be done in both workers.

Connecting an MCP client

Claude Desktop (via mcp-remote)

{
	"mcpServers": {
		"cf-activitypub": {
			"command": "npx",
			"args": [
				"mcp-remote",
				"https://mcp.example.com/mcp",
				"--header",
				"Authorization: Bearer <MCP_AUTH_TOKEN>"
			]
		}
	}
}

Clients with native remote transport (Cursor, VS Code, others)

{
	"mcpServers": {
		"cf-activitypub": {
			"url": "https://mcp.example.com/mcp",
			"headers": {
				"Authorization": "Bearer <MCP_AUTH_TOKEN>"
			}
		}
	}
}

Use https://mcp.example.com/sse instead of /mcp when a client explicitly requires an SSE endpoint.

MCP Inspector

npx @modelcontextprotocol/inspector
# Transport: Streamable HTTP
# URL:       https://mcp.example.com/mcp
# Header:    Authorization: Bearer <MCP_AUTH_TOKEN>

Tools

The server exposes 30 tools, grouped by administrative domain. Destructive actions (delete, reject, suspend, demote, purge, clear_all, remove, dismiss) require an explicit confirm: true argument, so an assistant cannot destroy data by accident.

Overview and health

Instance settings

Accounts and moderation

Reports

Federation

Content and policy

Operations

Known limitations

• manage_report with action: "add_note" needs an OAuth token owned by a local actor; the shared ADMIN_TOKEN cannot author notes and the instance answers 401.

• Announcement listing is actor-only on the instance, so this MCP can create and delete announcements but not list them.

• The MCP never exposes the instance database directly; it is limited to what the admin API supports.

Health and landing page

• GET / renders a public landing page linking to both repositories and showing live metrics (worker status, instance status, latency, active users, tool count).

• GET /health returns the same data as JSON, suitable for uptime monitors:

{
	"status": "ok",
	"service": { "name": "cf-activitypub-mcp", "version": "1.0.0", "tools": 30, "authentication": "bearer" },
	"instance": { "url": "https://social.example.com", "reachable": true, "latency_ms": 42, "users": 128 }
}

No secrets or administrative details are exposed by either endpoint.

Security

• Fail closed. MCP endpoints refuse to serve when MCP_AUTH_TOKEN is missing.

• Least privilege. The MCP only knows the instance admin API; it cannot reach Cloudflare account resources.

• Auditability. Every mutation performed through the MCP is recorded by the instance in its moderation log.

• Confirmation guards. Destructive tools require confirm: true; the model must be told explicitly.

• Constant-time token comparison. Candidate and expected tokens are hashed and compared with an XOR accumulator.

• Origin/Host allowlists. Optional MCP_ALLOWED_ORIGINS / MCP_ALLOWED_HOSTNAMES restrict browser and Host access.

• Source maps. upload_source_maps keeps stack traces readable in the dashboard without shipping them to clients.

If you find a security issue, please open a private report through GitHub rather than a public issue.

Development

Project structure

src/
  index.ts                  Worker entry: routing, auth, endpoints
  config.ts                 Environment parsing and defaults
  auth.ts                   Bearer authentication and secret comparison
  activitypub/
    client.ts               Authenticated client for the instance API
    types.ts                Shared API payload shapes
  mcp/
    server.ts               MCP server factory and tool catalogue
    context.ts              Per-request tool context (lazy clients)
    result.ts               Tool result helpers
    tools/                  One module per administrative domain
  web/
    health.ts               Health report collection
    index-page.ts           Public landing page renderer
test/
  index.spec.ts             Worker routes and MCP protocol tests
  config.spec.ts            Config and auth unit tests

Deployment notes

1. Set routes[0].pattern in wrangler.jsonc to your subdomain (for example mcp.example.com). Wrangler creates the DNS record and certificate automatically on deploy.

2. Set ACTIVITYPUB_URL to the public URL of your instance.

3. Configure both secrets with wrangler secret put.

4. Run npm run deploy, then open https://mcp.example.com/ to verify the health metrics.

5. Observability is already enabled: traces, logs and real-time issues are available in the Cloudflare dashboard under the worker's Observability tab.

The worker requires no Durable Objects, KV, R2 or D1 bindings — it is stateless and works entirely through the instance API.

License

MIT © 2026 manalejandro

CF ActivityPub MCP is not affiliated with Cloudflare, Inc. or the Mastodon project. The author is not responsible for the use of this software, nor for any charges Cloudflare may apply.