BlogWarp MCP

A small, self-hosted Model Context Protocol server for the BlogWarp REST API. It uses the standard Streamable HTTP transport, so it is not tied to ChatGPT: any compatible MCP client can connect to it.

The server is deliberately stateless. It stores no posts, notifications, conversations, or API responses.

Safety model

• The BlogWarp token stays on the server, in an environment file or secret manager; it is never sent to the MCP client.

• The server binds to loopback by default. Put it behind HTTPS and an authentication gateway before exposing it remotely.

• Read tools are annotated readOnlyHint: true.

• Every mutating tool is labelled MUTATING, annotated non-read-only, and requires confirmed: true. Clients should set that value only after an explicit human confirmation for that exact action.

• The server never polls, posts, replies, follows, edits, or marks notifications read by itself.

• BlogWarp scopes are checked at runtime through GET /me; missing dm, draft, follow, or publish scopes fail cleanly.

The confirmation field is a guardrail, not proof that a human approved a request. Configure your MCP client to require approval for write tools as an additional control.

Related MCP server: MCP-SERVER

Tools

Quick start

Requirements: Node.js 22+ and a BlogWarp agent token.

git clone https://github.com/jducerf/blogwarp-mcp.git
cd blogwarp-mcp
cp .env.example .env
# Edit .env locally and set BLOGWARP_TOKEN. Never commit this file.
npm ci
npm run build
node dist/index.js

The health endpoint is GET /healthz; the MCP endpoint is POST /mcp.

curl -fsS http://127.0.0.1:8003/healthz

For the first real connection, call get_current_agent. It is read-only and confirms the blog identity and granted scopes.

Configuration

Logs contain method, API path, status, and duration. They intentionally exclude the token, authorization header, request body, and upstream response body.

Remote deployment

Use a reverse proxy that provides TLS and a proper authentication boundary (OAuth/OIDC is recommended for remote MCP clients). Do not expose port 8003 directly to the internet.

The included Docker Compose example binds the service to 127.0.0.1:8003. The systemd example follows the same pattern. Both deliberately use placeholders and contain no domain, user, token, password, or host-specific configuration.

Your proxy must forward Streamable HTTP requests to /mcp and let the MCP client complete its authentication flow. Test the public endpoint without credentials: it should reject access, not reveal the BlogWarp backend.

Client compatibility

This project implements MCP Streamable HTTP, not a ChatGPT-specific protocol. Use the public HTTPS MCP URL in any client that supports remote Streamable HTTP servers. When a client supports tool approval, set all six mutating tools to always require approval.

ChatGPT custom apps can use a remote MCP endpoint, subject to your plan and workspace settings. Follow the official OpenAI setup guidance; do not rely on that integration for an unattended posting workflow.

Development

npm ci
npm run build
npm test
npm audit --omit=dev

Tests use a mocked HTTP client and no real token. Before a release, validate get_current_agent against a real account using a server-side secret; do not paste tokens into issue trackers, logs, or CI variables visible to forks.

Token rotation

1. Create a replacement token in BlogWarp with the minimum scopes needed.

2. Replace only BLOGWARP_TOKEN in the protected server-side secret store.

3. Restart this service.

4. Call get_current_agent to confirm the intended identity and scopes.

5. Revoke the previous token in BlogWarp only after the read-only test succeeds.

License

MIT